> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ragrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing

> Run the Ragrails test suite.

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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.