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_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 }}