How to test modules

To test, you need a running instance of Foreman, probably with Katello (use forklift if unsure). Also you need to run make test-setup and update tests/test_playbooks/vars/server.yml:

make test-setup
vi tests/test_playbooks/vars/server.yml # point to your Foreman instance

To run the tests using the foreman_global_parameter module as an example:

make test # all tests
make test_global_parameter  # single test
make test TEST="-k 'organzation or global_parameter'"  # select tests by expression (see `pytest -h`)

The tests are run against prerecorded server-responses. You can (re-)record the cassettes for a specific test with

make record_global_parameter

Guideline to writing tests

The tests in this repository run playbooks that can be found in tests/test_playbooks. To be run, the name of the corresponding playbook must be listed in tests/test_crud.py.

The playbooks should be self contained, target the features of a specific module and be able to run against an actual foreman instance. The structure would usually be something like setup -> run tests -> clean up.

In tests/test_playbooks/tasks, preconfigured tasks for individual entities / actions can be found. They can be reused, to create common dependent resources, as well as to manipulate the entities in the actual test. If the boolean variable expected_change is set, such a task fails if the result does not meet this expectation.

The ansible inventory contains two hosts:

  • localhost: This host runs locally without modification it is meant to setup (and teardown) dependent resources, only when (re-)recording. It can also be useful to run ad hoc commands or small playbooks during development.

  • tests: This host should run the actual tests. It is used to record the vcr-yaml-files, or to run isolated against those files.

In order to run these tests, the API responses of a running Foreman or Katello server must be recorded. For this last step, tests/test_playbooks/vars/server.yml must be configured to point to a running Foreman or Katello server. Then, make record_<playbook name> must be called, and the resulting vcr files (test_playbook/fixtures/<playbook_name>-*.yml) must be checked into git.

Recording/storing apidoc.json for tests

The tests depend on a valid apidoc.json being available during execution. The easiest way to do so is to provide a <module>.json in the tests/fixtures/apidoc folder. Most modules can just use a symlink to either foreman.json or katello.json, depending on whether they need a plain Foreman or Foreman+Katello to function properly. If you need a setup with different plugins enabled, just get https://foreman.example.com/apidoc/v2.json from your install and place it in tests/fixtures/apidoc.