diff --git a/docs/development.rst b/docs/development.rst index b2f0fd2c3c5591a3a508d28e5eda1c7c904508a0..f05f37182fa3b67519d7eef4fb6a60b67d3d4538 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -172,6 +172,56 @@ In order to run tests for a specific role, perform the following steps: molecule test +Running role tests during development +------------------------------------- + +During development, as new features are being implemented, it is +usually necessary to bring up the test machines and have them +operational for prolonged periods of time while changes are being +applied and tested. + +This usually starts off by bringing up the test machines and applying +the configuration against them using Ansible:: + + workon majic-ansible-roles + cd roles/ROLENAME/ + molecule converge + +After the test machines have been brought up and configured, tests can +be run with (without destroying the test machines themselves):: + + molecule verify + +Another scenario is ability to run individual tests for faster +develpoment iteration. Individual tests can be selected for execution +by passing options to the underlying test runner (`pytest +`_) via ``PYTEST_ADDOPTS`` +environment variable. + +For example, to run a singular test by its function name, use the +``-k`` option:: + + PYTEST_ADDOPTS="-k test_config_file_content" molecule verify + +Tests can also be decorated with markers (``@pytest.mark.*``), which +can in turn be used to run the matching (marked) subset of tests. For +example, to execute slow-running tests (decorated with +``@pytest.mark.slow``), run:: + + PYTEST_ADDOPTS="-m slow" molecule verify + +To exclude the slow-running tests, use logical expressions (just make +sure to surround the entire expression with additional quotation +marks):: + + PYTEST_ADDOPTS="-m 'not slow'" molecule verify + +To determine what tests take a long time to finish, use the +``--durations`` option:: + + PYTEST_ADDOPTS="--durations 0" molecule verify" + + Running role tests via shell script -----------------------------------