An npm package that converts the terminal output from an Ansible Molecule test into a JSON compatibility matrix

➤ Table of Contents

• ➤ Requirements
• ➤ Overview
• ➤ Getting Started
  • Example Usage
  • Example Output
  • Example Input
• ➤ Ansible Molecule Example
• ➤ Contributing
• ➤ License

➤ Requirements

• Node.js >9

➤ Overview

Ansible is a tool that allows you to provision machines over SSH. When developing with Ansible, it is common to support multiple operating systems. Testing multiple operating systems after making changes to an Ansible role can be time consuming. In order to help developers get over this hurdle, Ansible provides the Molecule testing platform. Molecule helps you test your Ansible roles against multiple environments at the same time. Sadly, Molecule does not support the ability to output the results in JSON format.

This NPM package converts Ansible Molecule test data into JSON format. We personally use this to embed compatibility matrices into our README.md files across hundreds of Ansible roles. After piping the output of your Ansible Molecule test to a text file, you can then use this NPM package to convert the data into JSON format (for consumption by other applications). The JSON output is formatted to be compatible with @appnest/readme which we utilize to generate our documentation using partials.

➤ Getting Started

You can run ansible-molecule-json by installing it globally or running it with npx. You can run ansible-molecule-json --help to see the available parameters. You should see output that looks something like this:

❯ ansible-molecule-json --help
Usage: ansible-molecule-json [options]

  -h, --help            Displays help
  -d, --data String     Relative path to the data file.
  -o, --output String   Relative path to the output file - default: ./ansible-molecule.json
  -c, --command String  Additional commands to run before analyzing
  -i, --inject String   Inject output to a JSON file

Example Usage

1. Run the molecule test and pipe the output to a text file (e.g. molecule test > molecule-output.txt)
2. Run npx ansible-molecule-json --data ./molecule-output.txt --output ./molecule-output.json

Example Output

The converter will generate the JSON in the following format:

{
  "compatibility": [
    ["OS Family", "OS Version", "Status", "Idempotent"],
    ["Archlinux", null, "✅", "✅"],
    ["CentOS", 7, "✅", "✅"],
    ["CentOS", 8, "✅", "✅"],
    ["Debian", 10, "✅", "✅"],
    ["Debian", 9, "✅", "✅"],
    ["Fedora", 33, "✅", "✅"],
    ["Ubuntu", 18.04, "✅", "✅"],
    ["Ubuntu", 20.04, "✅", "✅"]
  ]
}

Example Input

For debugging purposes, below is a snippet of the format that ansible-molecule-json is expecting. When you run molecule test > molecule-output.txt, you should see that the contents of molecule-output.txt looks something like this:

INFO     docker scenario test matrix: lint, dependency, cleanup, destroy, syntax, create, prepare, converge, idempotence, side_effect, verify, cleanup, destroy
INFO     Running docker > lint
INFO     Lint is disabled.
INFO     Running docker > dependency
WARNING  Skipping, missing the requirements file.
WARNING  Skipping, missing the requirements file.
INFO     Running docker > cleanup
WARNING  Skipping, cleanup playbook not configured.
INFO     Running docker > destroy
INFO     Sanity checks: 'docker'

PLAY [Destroy] *****************************************************************

TASK [Destroy molecule instance(s)] ********************************************
changed: [localhost] => (item=Archlinux-Latest)
changed: [localhost] => (item=CentOS-7)
changed: [localhost] => (item=CentOS-8)
changed: [localhost] => (item=Debian-9)
changed: [localhost] => (item=Debian-10)
changed: [localhost] => (item=Fedora-33)
changed: [localhost] => (item=Ubuntu-18.04)
changed: [localhost] => (item=Ubuntu-20.04)

➤ Ansible Molecule Example

If you are new to Ansible Molecule and are looking for an example of how to integrate Ansible Molecule tests into your Ansible project, you might find our Android Studio role helpful. You can find the Ansible Molecule test scenarios in the molecule/ folder. Each scenario is in its own folder. The default scenario (i.e. the scenario in the folder named default/) will run when you run molecule test. For all the other scenarios, you have to run molecule test -s folder_name. For more information, please see the Android Studio README.md and CONTRIBUTING.md.

➤ Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page. If you would like to contribute, please take a look at the contributing guide.

Brian Zalewski

➤ License

Copyright © 2021 Megabyte LLC. This project is MIT licensed.