How to Run Tests in ag-kit: CLI, Antigravity Runtime, and Toolkit Guide

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:

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:

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) – 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) – Ensures version numbers remain synchronized across the three package.json files in the repository.

To debug a single test file without running the entire suite:

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:

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:

npm run check:agents

Run the Python unit tests:

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:

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:

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):

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 <path> 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).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}