Testing - Ragrails

Tests are organized by interface layer. Run any layer independently:

scripts/test-core.sh   # core pipeline stages
scripts/test-sdk.sh    # public SDK
scripts/test-cli.sh    # CLI commands
scripts/test-rest.sh   # REST API services

Pre-push hook

The repository ships a pre-push hook at .githooks/pre-push that runs all four layers before each push and blocks the push if any layer fails. Enable it once:

git config core.hooksPath .githooks

Test organization

Tests live beside the code they cover, in a tests/ package within each module:

ragrails/interfaces/cli/chunking/tests/test_commands.py
ragrails/interfaces/sdk/storing/tests/test_client.py
ragrails/core/stg_04_storing/tests/test_storing.py

Documentation contracts

Docs examples that are likely to drift are checked against the implementation. Run this from the documentation repo root with the source checkout path:

RAGRAILS_SOURCE="/path/to/ragrails" python scripts/check-docs-contracts.py

This verifies the golden quickstart path, the real CLI command list, REST ingestion schema behavior, and SDK llm() validation.

Reference generation

The high-level CLI, SDK, and REST reference pages are generated from the implementation:

RAGRAILS_SOURCE="/path/to/ragrails" uv run python scripts/generate-reference.py

Run this after changing CLI commands, SDK method signatures, or REST routes. Then run the docs contract checker.

​Pre-push hook

​Test organization

​Documentation contracts

​Reference generation

Pre-push hook

Test organization

Documentation contracts

Reference generation