add check_mode option for tasks (#16056)

* add check_mode option for tasks

includes example testcases for the template module

* extend check_mode option

* replace always_run, see also proposal rename_always_run
* rename always_run where used and add deprecation warning
* add some documentation

* have check_mode overwrite always_run

* use unique template name to prevent conflicts

test_check_mode was right before, but failed due to using the same filename as other roles

* still mention always_run in the docs

* set deprecation of always_run to version 2.4

* fix rst style

* expand documentation on per-task check mode

test/integration/roles/test_always_run/tasks/main.yml

@@ -18,7 +18,7 @@
 
 - name: run a command while in check mode
   shell: echo "running"
-  always_run: yes
+  check_mode: no
   register: result
 
 - name: assert that the command was run

test/integration/roles/test_check_mode/tasks/main.yml

@@ -17,23 +17,30 @@
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 - name: fill in a basic template in check mode
-  template: src=foo.j2 dest={{output_dir}}/foo.templated mode=0644
+  template: src=foo.j2 dest={{output_dir}}/checkmode_foo.templated mode=0644
   register: template_result
 
+- name: check whether file exists
+  stat: path={{output_dir}}/checkmode_foo.templated
+  register: foo
+
 - name: verify that the file was marked as changed in check mode
   assert: 
     that: 
-      - "template_result.changed == true"
+      - "template_result|changed"
+      - "not foo.stat.exists"
 
-- name: Actually create the file
-  template: src=foo.j2 dest={{output_dir}}/foo.templated2 mode=0644
-  always_run: True
+- name: Actually create the file, disable check mode
+  template: src=foo.j2 dest={{output_dir}}/checkmode_foo.templated2 mode=0644
+  check_mode: no
+  register: checkmode_disabled
 
-- name: fill in a basic template in check mode
-  template: src=foo.j2 dest={{output_dir}}/foo.templated2 mode=0644
+- name: fill in template with new content
+  template: src=foo.j2 dest={{output_dir}}/checkmode_foo.templated2 mode=0644
   register: template_result2
 
-- name: verify that the file was marked as not changed in check mode
+- name: verify that the file was not changed
   assert: 
     that: 
-      - "template_result2.changed == false"
+      - "checkmode_disabled|changed"
+      - "not template_result2|changed"

test/integration/roles/test_template/tasks/main.yml

@@ -179,3 +179,49 @@
     that:
       - "template_result.changed == False"
 
+
+# check_mode
+
+- name: fill in a basic template in check mode
+  template: src=short.j2 dest={{output_dir}}/short.templated
+  register: template_result
+  check_mode: True
+
+- name: check file exists
+  stat: path={{output_dir}}/short.templated
+  register: templated
+
+- name: verify that the file was marked as changed in check mode but was not created
+  assert: 
+    that: 
+      - "not templated.stat.exists"
+      - "template_result|changed"
+
+- name: fill in a basic template
+  template: src=short.j2 dest={{output_dir}}/short.templated
+
+- name: fill in a basic template in check mode
+  template: src=short.j2 dest={{output_dir}}/short.templated
+  register: template_result
+  check_mode: True
+
+- name: verify that the file was marked as not changes in check mode
+  assert: 
+    that: 
+      - "not template_result|changed"
+      - "'templated_var_loaded' in lookup('file', '{{output_dir | expanduser}}/short.templated')"
+
+- name: change var for the template
+  set_fact: 
+    templated_var: "changed"
+
+- name: fill in a basic template with changed var in check mode
+  template: src=short.j2 dest={{output_dir}}/short.templated
+  register: template_result
+  check_mode: True
+
+- name: verify that the file was marked as changed in check mode but the content was not changed
+  assert: 
+    that: 
+      - "'templated_var_loaded' in lookup('file', '{{output_dir | expanduser }}/short.templated')"
+      - "template_result|changed"

test/integration/roles/test_template/templates/short.j2

@@ -0,0 +1 @@
+{{ templated_var }}