Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 29 ยท Real-World Practice

Testing, Linting and Debugging

Test Ansible automation: syntax-check, check and diff mode, ansible-lint, yamllint, Molecule with containers, assert and fail, verbosity levels, the debugger and a CI pipeline.

Automation that changes servers deserves the same care as application code. A typo in a playbook can break a fleet in seconds. The good news is that Ansible has a ladder of checks, from instant and free to slow and thorough: syntax checking, linting, check mode with diffs, and full tests of roles in throwaway containers with Molecule. You also need tools to debug the runs that go wrong.

This lesson climbs that ladder. The real tools need Ansible installed, so their commands are read-only. Two JavaScript stand-ins show the ideas inside: a tiny lint rule engine that inspects tasks the way ansible-lint does, and a model of check mode with a diff.

The testing ladder

Run the cheap checks first and often; run the expensive ones in CI.

flowchart LR
  A["yamllint<br/>YAML style"] --> B["--syntax-check<br/>does it parse?"]
  B --> C["ansible-lint<br/>best practices"]
  C --> D["--check --diff<br/>dry run on real hosts"]
  D --> E["Molecule<br/>test in containers"]
  E --> F["Run for real"]

Every step catches a different kind of mistake, and each is slower than the one before.

Syntax check and listing

CONSOLE
$ ansible-playbook site.yml --syntax-check
playbook: site.yml

$ ansible-playbook site.yml --list-hosts
$ ansible-playbook site.yml --list-tasks
$ ansible-playbook site.yml --list-tags

--syntax-check parses the playbook, expands roles and imports, and reports YAML or structure errors without connecting to any host. It does not check that module arguments are valid or that variables exist. The --list-* options show which hosts, tasks and tags a run would use, which is a good way to confirm a --limit or --tags selection before you run anything.

Check mode and diff

--check (often called a dry run) asks modules to report what they would change without changing it. --diff shows the before and after of files and templates.

CONSOLE
$ ansible-playbook site.yml --check --diff --limit web1
TASK [Write the nginx config] ***********************
--- before: /etc/nginx/nginx.conf
+++ after: /etc/nginx/nginx.conf
@@ -1,4 +1,4 @@
-worker_processes 1;
+worker_processes 4;
changed: [web1]

Know the limits. Modules that support check mode predict their result. Modules that do not (including command and shell, unless you give them creates/removes) are skipped in check mode, so later tasks may behave differently than in a real run. Two keywords help:

YAML
- name: Read the current version (safe to run even in check mode)
  ansible.builtin.command: /opt/myapp/bin/myapp --version
  register: current_version
  changed_when: false
  check_mode: false          # run this one for real, even during --check

- name: Show a diff for this file even without --diff on the command line
  ansible.builtin.template:
    src: app.conf.j2
    dest: /etc/myapp/app.conf
  diff: true

Use check_mode: false only for read-only tasks. A check-mode run is a strong signal, but not a guarantee, so treat it as a preview.

This stand-in models a template task in check mode: it compares the current file with the desired lines, returns a changed flag and a simple diff, and writes nothing.

JS Check mode and diff stand-in

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Linting: yamllint and ansible-lint

yamllint checks YAML style: indentation, line length, trailing spaces, and truthy values (yes/no are ambiguous in older YAML, so write true/false).

ansible-lint knows Ansible. It reads playbooks, roles and collections and reports violations of best practices, each with a rule ID.

CONSOLE
$ pip install ansible-lint yamllint
$ ansible-lint site.yml roles/
WARNING  Listing 3 violation(s) that are fatal
fqcn[action-core]: Use FQCN for builtin module actions (command).
site.yml:12 Task/Handler: Run the migration

no-changed-when: Commands should not change things if nothing needs doing.
site.yml:12 Task/Handler: Run the migration

name[missing]: All tasks should be named.
site.yml:20 Task/Handler: ansible.builtin.service

Rules you will see often: name[missing] (every task needs a name), fqcn[action-core] (write ansible.builtin.copy, not copy), no-changed-when (a command or shell task needs changed_when), command-instead-of-module (use a real module instead of shell: apt-get install), package-latest (avoid state: latest), risky-file-permissions (set a mode on file-creating tasks) and yaml[truthy]. Configure it with a .ansible-lint file to choose a profile (from min to production), or to skip a rule for a good reason. Exact messages and rule names change between versions, so run it on your own project to see the current ones.

The stand-in below is a miniature rule engine. Each rule is a function that inspects a task (already parsed into an object) and returns a message. This is the same shape that real linters have: parse, run every rule on every task, collect the findings.

JS A tiny lint rule engine

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The real ansible-lint also understands roles, vars, handlers and includes, and has many more rules. This stand-in only models the idea.

Asserting your assumptions

Inside a playbook, ansible.builtin.assert and ansible.builtin.fail stop a run early with a clear message, instead of letting a bad value cause damage later.

YAML
- name: Refuse to run on unsupported systems
  ansible.builtin.assert:
    that:
      - ansible_facts['os_family'] in ['Debian', 'RedHat']
      - app_port | int > 1024
      - app_env in ['dev', 'staging', 'prod']
    fail_msg: "Unsupported host or bad settings: {{ ansible_facts['os_family'] }}, port {{ app_port }}, env {{ app_env }}"
    success_msg: "Preconditions are fine"

- name: Stop if production is targeted without the safety flag
  ansible.builtin.fail:
    msg: "Add -e confirm_prod=true to deploy to production."
  when: app_env == 'prod' and not (confirm_prod | default(false) | bool)

Assertions are also how you test behavior: after converging a role in Molecule, an assert or uri task can check that the port answers and the config contains what you expect.

Molecule: testing roles in containers

Molecule runs your role against disposable instances, usually containers (with Docker or Podman), so you can test without touching real servers. A scenario describes the instances and the steps:

CONSOLE
$ pip install molecule molecule-plugins[docker]
$ molecule init scenario default          # inside a role directory
$ molecule test
YAML
# molecule/default/molecule.yml
driver:
  name: docker
platforms:
  - name: instance-debian
    image: debian:12
    pre_build_image: true
YAML
# molecule/default/converge.yml
- name: Converge
  hosts: all
  roles:
    - role: myrole
YAML
# molecule/default/verify.yml
- name: Verify
  hosts: all
  tasks:
    - name: The config file exists
      ansible.builtin.stat:
        path: /etc/myapp/app.conf
      register: conf
    - name: Check it
      ansible.builtin.assert:
        that: conf.stat.exists

molecule test runs a sequence: create the instance, converge (apply the role), run the role a second time to prove idempotence (the second run must report no changes), verify, and destroy the instance. The idempotence step alone catches many mistakes, such as a command task without changed_when. Containers have no real init system by default, so roles that manage services often need a systemd-enabled image or a VM driver. Molecule's drivers and options have changed across versions, so follow the documentation for the version you install, and see Roles and Project Layout for the layout it expects.

Debugging a failing run

Start with more output. Each -v adds detail:

Flag Shows
-v task results, including returned data
-vv the playbook and task file locations
-vvv connection details, such as the SSH command lines
-vvvv even more connection debugging

Beyond that:

  • Use ansible.builtin.debug to print a variable (var: result), and register to capture module results.
  • Set ANSIBLE_STDOUT_CALLBACK=yaml (or callback_result_format = yaml in newer versions, see the docs of your release) for readable multi-line errors.
  • Use --step to confirm each task, and --start-at-task "Task name" to resume in the middle.
  • Turn on the task debugger: debugger: on_failed on a play, block or task drops you into an interactive prompt when the task fails, where you can print task_vars, change an argument and redo.
YAML
- name: Deploy
  hosts: web
  debugger: on_failed
  tasks:
    - name: Render config
      ansible.builtin.template:
        src: app.conf.j2
        dest: /etc/myapp/app.conf

The commands inside the debugger include p task, p task.args, task.args['dest'] = '/tmp/x', update_task, redo and continue. Remember to remove debugger before you commit, and never use it where output is recorded without people watching. The most common error messages and what they mean are collected in Common Mistakes and Troubleshooting.

A CI pipeline

Put the ladder in CI so every change is checked automatically. This example uses GitHub Actions; the same steps work in GitLab CI or any other system:

YAML
name: ansible-ci
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install ansible-core ansible-lint yamllint
      - run: yamllint .
      - run: ansible-lint
      - run: ansible-playbook site.yml -i inventory/ci --syntax-check

  molecule:
    runs-on: ubuntu-latest
    needs: lint
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install ansible-core molecule "molecule-plugins[docker]"
      - run: molecule test
        working-directory: roles/myrole

Keep the lint job fast so people run it before every push, and run Molecule on the roles that changed. Pin tool versions in a requirements file so your pipeline does not change underneath you. The deployment side of CI is in Ansible with Docker, Terraform and CI/CD.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does ansible-playbook --syntax-check verify?

    It only parses the playbook and expands roles and imports. Argument values, variables and reachability are not checked.
  2. 2. Why do shell and command tasks often misbehave in --check mode?

    Ansible cannot predict what an arbitrary command would do. Use creates/removes, or check_mode: false for read-only commands you need.
  3. 3. Which Molecule step proves that a role is idempotent?

    Molecule runs the role again after the first converge. Any changed task in the second run signals a non-idempotent task.
  4. 4. What does debugger: on_failed do?

    The task debugger pauses on failure so you can inspect task variables and arguments, update the task and run it again.
  5. 5. The lint rule no-changed-when flags a task. What should you do?

    command and shell always report changed unless you say otherwise, which breaks idempotence reporting.

Summary

  • Climb the ladder: yamllint, --syntax-check, ansible-lint, --check --diff, then Molecule.
  • Check mode previews changes; commands without creates/removes are skipped, and check_mode: false runs read-only tasks for real.
  • ansible-lint enforces best practices by rule ID: names, FQCNs, changed_when, permissions and more.
  • assert and fail stop runs early with a clear message and also work as test checks.
  • Molecule creates containers, converges a role, checks idempotence, verifies and destroys.
  • Debug with -v to -vvvv, debug, --step, --start-at-task and debugger: on_failed; put the checks into CI.

Next: Performance, Dynamic Inventory and AWX.