computer-playbook/docs/contributing/flow/testing.md

Testing and Validation

Use the real commands from the repository. Run them from the repository root.

This repository uses several test and validation types:

• Lint and syntax checks catch style, formatting, and Ansible syntax problems early.
• Unit tests verify isolated logic.
• Integration tests verify behavior across modules and runtime boundaries.
• Combined validation runs the standard main verification flow.
• Local deploy and E2E validation checks whether apps and deployment flows work in a realistic local stack.

Code Quality and Automated Checks

Use the following table to choose the right lint, syntax, unit, integration, or combined validation command for your change.

Validation Commands

Category	Command	What it does	When to use it
Lint	make lint	Runs the main lint checks for the repository.	Use this when you want a broad lint pass before pushing.
Syntax	make lint-ansible	Runs the Ansible syntax validation for playbook.yml.	Use this when you changed Ansible roles, inventories, or playbook-related files.
Lint tests	make test-lint	Runs the lint test suite inside the development environment.	Use this when you want CI-like lint validation.
Unit tests	make test-unit	Runs the unit test suite.	Use this when you changed Python logic or other isolated code paths.
Integration tests	make test-integration	Runs the integration test suite.	Use this when your change affects behavior across modules or runtime boundaries.
Combined validation	make test	Runs the main combined validation flow.	Use this whenever a change touches at least one file that is not .md or .rst, or before opening a Pull Request.

Local Deploy and End-to-End Checks

For the retry-loop policy, use Iteration as the SPOT. The table below is a command reference for the supported local deployment paths.

Local Validation Commands

Use the following table when you need realistic local deployment validation or app-level end-to-end checks.

Category	Command	What it does	When to use it
Local deploy	APPS=web-app-nextcloud make deploy-fresh-kept-apps	Creates the needed inventory and deploys one or more apps.	Fresh deploy for a specific app set.
Local deploy	APPS=web-app-nextcloud make deploy-reuse-kept-apps	Reuses an existing devices.yml inventory and redeploys one or more apps quickly.	Fast reuse path.
Local deploy	APPS=web-app-nextcloud make deploy-reuse-purged-apps	Reuses an existing devices.yml inventory, purges the entity first, and redeploys one or more apps quickly.	Fast reuse path after a state reset.
Local deploy and E2E	APPS=web-app-matomo make deploy-fresh-purged-apps	Runs a dedicated local validation flow for one or more apps against the dev stack, creating and re-initializing the inventory first.	Baseline and recovery path.
Full local validation	make deploy-fresh-kept-all	Builds the broader local deployment flow across apps.	Broad coverage when you explicitly need it.
Local reset	make container-refresh-inventory	Recreates the local inventory without deploying apps.	Use this when your local inventory is broken or you want a clean reset.
Local cleanup	make container-purge-system	Deletes local deploy artifacts and cleanup data.	Use this only when you really want to remove local state.

Important:

• Some local deploy commands are destructive.
• Read reset/README.md, purge/README.md, or exec/README.md before using the matching helper.
• For act-based workflow checks, see Act Workflow Checks.
• After a successful local deploy, run make trust-ca and restart your browser.

Testing Standards

For test-type-specific requirements, framework, and creation procedures see:

• Unit Tests
• Integration Tests
• Playwright Tests