From 47e2a2695970f4e8cf5990147c97182d42a5c5ba Mon Sep 17 00:00:00 2001
From: "Jon \"The Nice Guy\" Spriggs" <jon@sprig.gs>
Date: Mon, 20 Dec 2021 14:48:30 +0000
Subject: [PATCH] Update playbook_tests with type testing (#72732)

---
 .../rst/user_guide/playbooks_filters.rst      |  1 +
 .../rst/user_guide/playbooks_tests.rst        | 75 +++++++++++++++++++
 2 files changed, 76 insertions(+)

diff --git a/docs/docsite/rst/user_guide/playbooks_filters.rst b/docs/docsite/rst/user_guide/playbooks_filters.rst
index ccc3daa8bc6..f16b2359026 100644
--- a/docs/docsite/rst/user_guide/playbooks_filters.rst
+++ b/docs/docsite/rst/user_guide/playbooks_filters.rst
@@ -114,6 +114,7 @@ If you are unsure of the underlying Python type of a variable, you can use the `
 
     {{ myvar | type_debug }}
 
+You should note that, while this may seem like a useful filter for checking that you have the right type of data in a variable, you should often prefer :ref:`type tests <type_tests>`, which will allow you to test for specific data types.
 
 .. _dict_filter:
 
diff --git a/docs/docsite/rst/user_guide/playbooks_tests.rst b/docs/docsite/rst/user_guide/playbooks_tests.rst
index b8eecfb37a1..bbad2fe9906 100644
--- a/docs/docsite/rst/user_guide/playbooks_tests.rst
+++ b/docs/docsite/rst/user_guide/playbooks_tests.rst
@@ -416,7 +416,82 @@ The following tasks are illustrative of the tests meant to check the status of t
 
 .. note:: From 2.1, you can also use success, failure, change, and skip so that the grammar matches, for those who need to be strict about it.
 
+.. _type_tests:
 
+Type Tests
+==========
+
+When looking to determine types, it may be tempting to use the ``type_debug`` filter and compare that to the string name of that type, however, you should instead use type test comparisons, such as:
+
+.. code-block:: yaml
+
+    tasks:
+      - name: "String interpretation"
+        vars:
+          a_string: "A string"
+          a_dictionary: {"a": "dictionary"}
+          a_list: ["a", "list"]
+        assert:
+          that:
+          # Note that a string is classed as also being "iterable", "sequence" and "mapping"
+          - a_string is string
+          
+          # Note that a dictionary is classed as not being a "string", but is "iterable", "sequence" and "mapping"
+          - a_dictionary is not string and a_dictionary is mapping
+          
+          # Note that a list is classed as not being a "string" or "mapping" but is "iterable" and "sequence"
+          - a_list is not string and a_list is not mapping and a_list is iterable
+          
+      - name: "Number interpretation"
+        vars:
+          a_float: 1.01
+          a_float_as_string: "1.01"
+          an_integer: 1
+          an_integer_as_string: "1"
+        assert:
+          that:
+          # Both a_float and an_integer are "number", but each has their own type as well
+          - a_float is number and a_float is float
+          - an_integer is number and an_integer is integer
+          
+          # Both a_float_as_string and an_integer_as_string are not numbers
+          - a_float_as_string is not number and a_float_as_string is string
+          - an_integer_as_string is not number and a_float_as_string is string
+          
+          # a_float or a_float_as_string when cast to a float and then to a string should match the same value cast only to a string
+          - a_float | float | string == a_float | string
+          - a_float_as_string | float | string == a_float_as_string | string
+          
+          # Likewise an_integer and an_integer_as_string when cast to an integer and then to a string should match the same value cast only to an integer
+          - an_integer | int | string == an_integer | string
+          - an_integer_as_string | int | string == an_integer_as_string | string
+          
+          # However, a_float or a_float_as_string cast as an integer and then a string does not match the same value cast to a string
+          - a_float | int | string != a_float | string
+          - a_float_as_string | int | string != a_float_as_string | string
+          
+          # Again, Likewise an_integer and an_integer_as_string cast as a float and then a string does not match the same value cast to a string
+          - an_integer | float | string != an_integer | string
+          - an_integer_as_string | float | string != an_integer_as_string | string
+
+      - name: "Native Boolean interpretation"
+        loop:
+        - yes
+        - true
+        - True
+        - TRUE
+        - no
+        - No
+        - NO
+        - false
+        - False
+        - FALSE
+        assert:
+          that:
+          # Note that while other values may be cast to boolean values, these are the only ones which are natively considered boolean
+          # Note also that `yes` is the only case sensitive variant of these values.
+          - item is boolean
+    
 .. _builtin tests: https://jinja.palletsprojects.com/en/latest/templates/#builtin-tests
 
 .. seealso::