Update docs for --tags default, and add some tests (#70939)

Change:
- Clarify that not passing `--tags` will cause `ansible_run_tags` to
  default to `["all"]`.
- Add some extra coverage around `ansible_run_tags`

Test Plan:
- New integration and unit tests

Tickets:
- Fixes #69619

Signed-off-by: Rick Elrod <rick@elrod.me>

docs/docsite/rst/reference_appendices/special_variables.rst

@@ -74,7 +74,7 @@ ansible_collection_name
     The name of the collection the task that is executing is a part of. In the format of ``namespace.collection``
 
 ansible_run_tags
-    Contents of the ``--tags`` CLI option, which specifies which tags will be included for the current run.
+    Contents of the ``--tags`` CLI option, which specifies which tags will be included for the current run. Note that if ``--tags`` is not passed, this variable will default to ``["all"]``.
 
 ansible_search_path
     Current search path for action plugins and lookups, i.e where we search for relative paths when you do ``template: src=myfile``

lib/ansible/cli/__init__.py

@@ -318,6 +318,9 @@ class CLI(with_metaclass(ABCMeta, object)):
         # process tags
         if hasattr(options, 'tags') and not options.tags:
             # optparse defaults does not do what's expected
+            # More specifically, we want `--tags` to be additive. So we cannot
+            # simply change C.TAGS_RUN's default to ["all"] because then passing
+            # --tags foo would cause us to have ['all', 'foo']
             options.tags = ['all']
         if hasattr(options, 'tags') and options.tags:
             tags = set()

test/integration/targets/tags/ansible_run_tags.yml

@@ -0,0 +1,49 @@
+---
+- name: verify ansible_run_tags work as expected
+  hosts: testhost
+  gather_facts: False
+  tasks:
+    - debug:
+        var: ansible_run_tags
+      tags:
+        - always
+
+    - debug:
+        var: expect
+      tags:
+        - always
+
+    - assert:
+        that:
+          - ansible_run_tags == ['all']
+      when: expect == 'all'
+      tags:
+        - always
+
+    - assert:
+        that:
+          - ansible_run_tags|sort == ['tag1', 'tag3']
+      when: expect == 'list'
+      tags:
+        - always
+
+    - assert:
+        that:
+          - ansible_run_tags == ['untagged']
+      when: expect == 'untagged'
+      tags:
+        - always
+
+    - assert:
+        that:
+          - ansible_run_tags|sort == ['tag3', 'untagged']
+      when: expect == 'untagged_list'
+      tags:
+        - always
+
+    - assert:
+        that:
+          - ansible_run_tags == ['tagged']
+      when: expect == 'tagged'
+      tags:
+        - always

test/integration/targets/tags/runme.sh

@@ -47,3 +47,24 @@ export LC_ALL=en_US.UTF-8
 # Run templated tags
 [ "$("${COMMAND[@]}" --tags tag3 | grep -F Task_with | xargs)" = \
 "Task_with_always_tag TAGS: [always] Task_with_templated_tags TAGS: [tag3]" ]
+
+# Run tagged
+[ "$("${COMMAND[@]}" --tags tagged | grep -F Task_with | xargs)" = \
+"Task_with_tag TAGS: [tag] Task_with_always_tag TAGS: [always] Task_with_unicode_tag TAGS: [くらとみ] Task_with_list_of_tags TAGS: [café, press] Task_with_csv_tags TAGS: [tag1, tag2] Task_with_templated_tags TAGS: [tag3]" ]
+
+# Run untagged
+[ "$("${COMMAND[@]}" --tags untagged | grep -F Task_with | xargs)" = \
+"Task_with_always_tag TAGS: [always] Task_without_tag TAGS: []" ]
+
+# Skip 'always'
+[ "$("${COMMAND[@]}" --tags untagged --skip-tags always | grep -F Task_with | xargs)" = \
+"Task_without_tag TAGS: []" ]
+
+# Test ansible_run_tags
+ansible-playbook -i ../../inventory ansible_run_tags.yml -e expect=all "$@"
+ansible-playbook -i ../../inventory ansible_run_tags.yml -e expect=all --tags all "$@"
+ansible-playbook -i ../../inventory ansible_run_tags.yml -e expect=list --tags tag1,tag3 "$@"
+ansible-playbook -i ../../inventory ansible_run_tags.yml -e expect=list --tags tag1 --tags tag3 "$@"
+ansible-playbook -i ../../inventory ansible_run_tags.yml -e expect=untagged --tags untagged "$@"
+ansible-playbook -i ../../inventory ansible_run_tags.yml -e expect=untagged_list --tags untagged,tag3 "$@"
+ansible-playbook -i ../../inventory ansible_run_tags.yml -e expect=tagged --tags tagged "$@"

test/units/playbook/test_taggable.py

@@ -83,6 +83,9 @@ class TestTaggable(unittest.TestCase):
     def test_evaluate_tags_special_all_in_only_tags(self):
         self.assert_evaluate_equal(True, ['tag'], ['all'], ['untagged'])
 
+    def test_evaluate_tags_special_all_in_only_tags_and_object_untagged(self):
+        self.assert_evaluate_equal(True, [], ['all'], [])
+
     def test_evaluate_tags_special_all_in_skip_tags(self):
         self.assert_evaluate_equal(False, ['tag'], ['tag'], ['all'])