# How to Run Tests in ag-kit: CLI, Antigravity Runtime, and Toolkit Guide > Learn how to run tests in ag-kit using simple npm commands for CLI, runtime, and toolkit verification. Execute the full CI matrix locally with npm run ci. - Repository: [Vũ Đỗ/ag-kit](https://github.com/vudovn/ag-kit) - Tags: how-to-guide - Published: 2026-07-29 --- **Run tests in ag-kit using `npm run test:cli` for Node.js unit tests, `npm run test:antigravity` for runtime validation, and `npm run test:toolkit` for Python-based toolkit verification, or use `npm run ci` to execute the complete CI matrix locally.** The ag-kit repository maintains distinct test suites for its command-line interface, Antigravity runtime, and `.agents` toolkit. Learning how to run tests in ag-kit ensures your changes pass the same validation gates defined in the GitHub Actions workflow, from managed-tree API integrity to Python manifest validation. ## Prerequisites Install root-level dependencies before executing any test commands: ```bash npm ci ``` This installs dev dependencies for the root workspace, `cli/`, and `web/` packages, ensuring the Node.js built-in test runner and Python unittest environment are ready. ## Running CLI Tests The **CLI test suite** validates the managed-tree API and release-safety checks using Node.js’s native `--test` runner. Execute the full CLI test matrix: ```bash npm run test:cli ``` This command runs all `*.test.js` files in the `cli/test/` directory, including: - **[[`cli/test/managed-tree.test.js`](https://github.com/vudovn/ag-kit/blob/main/cli/test/managed-tree.test.js)](https://github.com/vudovn/ag-kit/blob/main/cli/test/managed-tree.test.js)** – Validates the managed-tree API that powers the CLI’s `giget` workflow. - **[[`cli/test/release-safety.test.js`](https://github.com/vudovn/ag-kit/blob/main/cli/test/release-safety.test.js)](https://github.com/vudovn/ag-kit/blob/main/cli/test/release-safety.test.js)** – Ensures version numbers remain synchronized across the three [`package.json`](https://github.com/vudovn/ag-kit/blob/main/package.json) files in the repository. To debug a single test file without running the entire suite: ```bash node --test cli/test/managed-tree.test.js ``` ## Running Antigravity Runtime Tests The **Antigravity runtime tests** verify hooks, contract validation, and the Antigravity plugin itself. Run the runtime validation: ```bash npm run test:antigravity ``` This executes Node.js unit tests that confirm the runtime’s hook system and contract validation logic function correctly across supported Node.js versions. ## Running Toolkit Tests The **`.agents` toolkit** uses Python’s unittest framework to validate front-matter schemas, generated manifests, and component registration. Run the manifest and graph validation: ```bash npm run check:agents ``` Run the Python unit tests: ```bash npm run test:toolkit ``` Under the hood, this invokes `[.agents/scripts/validate_kit.py](https://github.com/vudovn/ag-kit/blob/main/.agents/scripts/validate_kit.py)`, which performs schema verification and dependency graph checks for agent definitions. For manual execution with verbose output: ```bash python -m unittest discover -s .agents/scripts/tests -v ``` ## Running Web Documentation Tests The optional **web test suite** uses Jest to validate the Next.js documentation site. Run the web tests: ```bash npm run test:web ``` While currently minimal, this command ensures documentation-specific utilities pass basic validation. ## Replicating CI Locally To match the exact test environment used in continuous integration, execute the CI shortcut defined in the root `[package.json](https://github.com/vudovn/ag-kit/blob/main/package.json)`: ```bash npm run ci ``` This command runs `test:cli`, `test:antigravity`, and `test:toolkit` sequentially, mirroring the validation gates in `[.github/workflows/ci.yml](https://github.com/vudovn/ag-kit/blob/main/.github/workflows/ci.yml)`. ## Summary - **Install dependencies** with `npm ci` before running any test commands. - **CLI tests** use Node.js’s built-in runner via `npm run test:cli`, covering the managed-tree API and release safety in `[cli/test/](https://github.com/vudovn/ag-kit/tree/main/cli/test)`. - **Antigravity tests** validate runtime hooks and contracts with `npm run test:antigravity`. - **Toolkit tests** require Python and run via `npm run test:toolkit`, executing `[validate_kit.py](https://github.com/vudovn/ag-kit/blob/main/.agents/scripts/validate_kit.py)` for schema and manifest verification. - **Single-file debugging** is supported with `node --test ` for JavaScript or `python -m unittest discover` for Python. - **Full validation** replicates CI when running `npm run ci`. ## Frequently Asked Questions ### How do I run only the managed-tree tests without executing the full CLI suite? Use Node.js’s built-in test runner with the specific file path: `node --test cli/test/managed-tree.test.js`. This executes only the managed-tree API tests, bypassing the release-safety checks and other CLI test files. ### Do I need Python installed to run the full test suite? Yes, the toolkit validation requires Python 3 and the unittest module. If Python is unavailable, the Node.js-based tests (`test:cli` and `test:antigravity`) will still execute, but `npm run test:toolkit` will fail until the Python environment is configured. ### How can I verify my changes match the CI environment exactly? Run `npm run ci` from the repository root. This script executes the same test commands defined in `[.github/workflows/ci.yml](https://github.com/vudovn/ag-kit/blob/main/.github/workflows/ci.yml)`, ensuring your local results align with the GitHub Actions pipeline. ### Where are the test commands defined? The npm scripts are defined in the root `[package.json](https://github.com/vudovn/ag-kit/blob/main/package.json)` under the `"scripts"` section, with CLI-specific configurations in `[cli/package.json](https://github.com/vudovn/ag-kit/blob/main/cli/package.json)`. The CI workflow orchestration is documented in `[.agents/workflows/test.md](https://github.com/vudovn/ag-kit/blob/main/.agents/workflows/test.md)`.