computer-playbook/docs/contributing/code/tests/integration.md

Integration Tests

This page is the SPOT for integration testing requirements, framework, and structure. Run integration tests with make test-integration.

Framework

• You MUST use Python unittest as the test framework.
• Tests MUST live under tests/integration/.
• Mirror the source tree structure used for unit tests.

When to Write

• You MUST add or update integration tests for every *.py file you touch when the change affects behavior across module or runtime boundaries.
• Write an integration test when the behavior you are verifying depends on two or more components working together — for example, a lookup plugin reading from real group_vars or a filter interacting with an Ansible variable structure.

Requirements

• You MUST NOT mock collaborators that are part of the integration boundary being tested. The point is to verify real interaction.
• You MUST NOT write tests that only assert a file contains a string.
• You MUST NOT write tests only for non-executable files such as .yml or .j2. Test the behavior that consumes them.
• You SHOULD keep each test focused on one integration boundary.
• You SHOULD test realistic inputs that match what Ansible would pass at runtime.
• You MAY use unittest.mock to stub out external services or filesystem state that is genuinely outside the integration scope.

How to Create

1. Identify the integration boundary (e.g. lookup plugin + group_vars variable loading).
2. Create the matching test file under tests/integration/ if it does not exist.
3. Subclass unittest.TestCase.
4. Use realistic inputs. Build hypotheses about cross-component behavior before writing assertions.
5. Run make test-integration and verify all tests pass.

Running Specific Tests

Use TEST_PATTERN to scope the test run to a single file or a glob:

# Run a single integration test file
TEST_PATTERN=test_my_module.py make test-integration

# Run all files matching a prefix
TEST_PATTERN=test_applications*.py make test-integration