@megabytelabs/ansible-molecule-json

NPM Package: Ansible Molecule JSON

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:

[34mINFO    [0m docker scenario test matrix: lint, dependency, cleanup, destroy, syntax, create, prepare, converge, idempotence, side_effect, verify, cleanup, destroy
[34mINFO    [0m [2;36mRunning [0m[2;32mdocker[0m[2;36m > [0m[2;32mlint[0m
[34mINFO    [0m Lint is disabled.
[34mINFO    [0m [2;36mRunning [0m[2;32mdocker[0m[2;36m > [0m[2;32mdependency[0m
[31mWARNING [0m Skipping, missing the requirements file.
[31mWARNING [0m Skipping, missing the requirements file.
[34mINFO    [0m [2;36mRunning [0m[2;32mdocker[0m[2;36m > [0m[2;32mcleanup[0m
[31mWARNING [0m Skipping, cleanup playbook not configured.
[34mINFO    [0m [2;36mRunning [0m[2;32mdocker[0m[2;36m > [0m[2;32mdestroy[0m
[34mINFO    [0m Sanity checks: [32m'docker'[0m

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

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

➤ 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.

Sponsorship

I create open source projects out of love. Although I have a job, shelter, and as much fast food as I can handle, it would still be pretty cool to be appreciated by the community for something I have spent a lot of time and money on. Please consider sponsoring me! Who knows? Maybe I will be able to quit my job and publish open source full time.

Sincerely,

Brian Zalewski

➤ License

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