From 507fd1bd60f529681c96fa526ffa7835e122ddcb Mon Sep 17 00:00:00 2001
From: Alicia Cozine <879121+acozine@users.noreply.github.com>
Date: Thu, 16 Mar 2023 14:47:01 -0500
Subject: [PATCH] Document debugging conditionals (#80239)

##### SUMMARY
Add a section to the docs describing how to debug conditional statements - how to get Ansible to show you whether your `when:` clause evaluates to `true` or `false`.

I ran into trouble with this and couldn't find anything in the docs. Thought I'd add it.


##### ISSUE TYPE
- Docs Pull Request

+label: docsite_pr
---
 .../playbook_guide/playbooks_conditionals.rst | 38 +++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst b/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst
index e1bf42d5cbb..1de9ec39c71 100644
--- a/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst
+++ b/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst
@@ -464,6 +464,44 @@ For example, you can template out a configuration file that is very different be
           -  default.conf
         mypaths: ['search_location_one/somedir/', '/opt/other_location/somedir/']
 
+.. _debugging_conditionals:
+
+Debugging conditionals
+======================
+
+If your conditional ``when`` statement is not behaving as you intended, you can add a ``debug`` statement to determine if the condition evaluates to ``true`` or ``false``. A common cause of unexpected behavior in conditionals is testing an integer as a string or a string as an integer. To debug a conditional statement, add the entire statement as the ``var:`` value in a ``debug`` task. Ansible then shows the test and how the statement evaluates. For example, here is a set of tasks and sample output: 
+
+.. code-block:: yaml
+
+   - name: check value of return code
+     ansible.builtin.debug:
+       var: bar_status.rc
+       
+   - name: check test for rc value as string
+     ansible.builtin.debug:
+       var: bar_status.rc == "127"
+
+   - name: check test for rc value as integer
+     ansible.builtin.debug:
+       var: bar_status.rc == 127
+
+.. code-block:: ansible-output
+
+   TASK [check value of return code] *********************************************************************************
+   ok: [foo-1] => {
+       "bar_status.rc": "127"
+   }
+
+   TASK [check test for rc value as string] **************************************************************************
+   ok: [foo-1] => {
+       "bar_status.rc == \"127\"": false
+   }
+
+   TASK [check test for rc value as integer] *************************************************************************
+   ok: [foo-1] => {
+       "bar_status.rc == 127": true
+   }
+
 .. _commonly_used_facts:
 
 Commonly-used facts