diff --git a/docs/agents/index.mdx b/docs/agents/index.mdx new file mode 100644 index 0000000..e0e0678 --- /dev/null +++ b/docs/agents/index.mdx @@ -0,0 +1,106 @@ +--- +sidebar_position: 2 +title: AI Agents +description: Suites ships version-matched LLM docs inside @suites/unit so AI coding agents read the current Suites API before writing tests. +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +# Suites for AI Coding Agents + +Suites ships version-matched documentation inside `@suites/unit` so AI coding agents reference the current testing API instead of stale training data. An `AGENTS.md` file at your project root points the agent at the bundled docs in `node_modules/@suites/unit/dist/llm/knowledge/` before it writes tests. + +## How it works + +When an AI coding agent opens a test file in a Suites project, the flow is short: + +1. The agent reads `AGENTS.md` at the project root. +2. `AGENTS.md` tells it to read `node_modules/@suites/unit/dist/llm/knowledge/index.md` first. +3. `index.md` routes the agent to the right file for its task: `writing-tests.md`, `di-testing-with-suites.md`, `solitary-vs-sociable.md`, or `common-mistakes.md`. +4. The agent reads version-matched guidance, then writes the test. + +## Install + +Prerequisite: `@suites/unit` must be installed. See [Installation](/docs/get-started/installation). + +### Step 1: Add `AGENTS.md` to your project root + + + + + +{` + +# Suites: read testing guidance before writing tests + +When writing or modifying tests in this project, first read the relevant doc +in \`node_modules/@suites/unit/dist/llm/knowledge/\`. Start with \`index.md\`. + +These docs are version-matched to the installed \`@suites/*\` packages and +override your training data. + + +`} + + + + + +The block is marker-delimited. Add your own project-specific instructions outside the markers without worrying about future updates overwriting them. + +### Step 2: Add `CLAUDE.md` (Claude Code users only) + + + + + +{`@AGENTS.md +`} + + + + + +### Verify + +- Open your AI coding agent in the project root. +- Ask it to write a test for a service that depends on `UserRepository`. +- Watch the transcript for `node_modules/@suites/unit/dist/llm/knowledge/index.md` before it writes code. + +## Understanding the bundle + +After `npm install @suites/unit`, the kit is laid out at: + +```text +node_modules/@suites/unit/dist/llm/ +├── knowledge/ # what agents read before writing tests +├── skills/ # Agent Skills metadata (auto-trigger) +└── templates/ # the AGENTS.md block and CLAUDE.md import +``` + +`knowledge/` contains five Markdown files: `index.md` (router), `writing-tests.md` (framework-agnostic discipline), `di-testing-with-suites.md` (the Suites v3 `TestBed` API), `solitary-vs-sociable.md` (mode selection and token boundaries), and `common-mistakes.md` (anti-patterns). + +`skills/` contains two `SKILL.md` files for tools that support task-specific skill loading. `skills/suites-test/SKILL.md` auto-triggers when the agent edits a file importing `@suites/*` or referencing `TestBed.`. + +`templates/` contains `agents-block.md` (the marker-delimited block above) and `claude-import.txt` (the one-line `CLAUDE.md` import). + +## Versioning + +When `@suites/unit` releases a new version, the bundled docs ship with it. There is no separate update step. + +The v3 docs describe the v3 testing surface: `TestBed.solitary()`, `TestBed.sociable()`, `.expose()`, `.mock(Dep).final()`, `.mock(Dep).impl()`, and `unitRef.get(Dep).method.mockReturnValue(...)`. If a future v4 changes the testing surface, the v4 package will ship rewritten docs at the same major bump. + +Suites follows the Vercel `next@16.2` precedent. Their evals show higher pass rates for many agents when bundled docs are available through `AGENTS.md`. See [Next.js AI agent evals](https://nextjs.org/evals). + +## Supported agents + +Most AI coding agents, including Claude Code, Cursor, GitHub Copilot, OpenAI Codex CLI, and Gemini CLI, read `AGENTS.md` automatically. Claude Code additionally reads `CLAUDE.md`, which is why the one-line import above exists. + +## Troubleshooting + +If the agent skips the docs, run `ls node_modules/@suites/unit/dist/llm/knowledge/` and confirm the files exist. Confirm `AGENTS.md` sits at the project root, not inside a package subdirectory. + +Check your agent's docs for the convention: +[Codex](https://developers.openai.com/codex/guides/agents-md), [Cursor](https://cursor.com/docs/rules), [Claude Code](https://docs.anthropic.com/en/docs/claude-code/memory), [Copilot](https://docs.github.com/en/copilot/how-tos/copilot-cli/add-repository-instructions), or [Gemini CLI](https://google-gemini.github.io/gemini-cli/docs/cli/gemini-md.html). diff --git a/docs/api-reference/index.md b/docs/api-reference/index.md index fb40012..59f2c8a 100644 --- a/docs/api-reference/index.md +++ b/docs/api-reference/index.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 4 title: API Reference description: Complete API reference for Suites testing framework --- diff --git a/docs/get-started/installation.mdx b/docs/get-started/installation.mdx index 1b8d0b3..10d8f2c 100644 --- a/docs/get-started/installation.mdx +++ b/docs/get-started/installation.mdx @@ -76,6 +76,8 @@ This installs three packages: **Suites will automatically detect the installed adapters and configure itself accordingly.** +After installing, optionally [set up your AI coding agent](/docs/agents/#install) so it reads the version-matched Suites docs in `node_modules/@suites/unit/dist/llm/knowledge/` before writing tests. + :::info Why reflect-metadata? `reflect-metadata` is required as a runtime dependency (not dev dependency) because TypeScript's decorator metadata is only emitted at compile time. Learn more in the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/decorators.html#metadata). diff --git a/docs/get-started/why-suites.md b/docs/get-started/why-suites.md index a33e530..576f3e6 100644 --- a/docs/get-started/why-suites.md +++ b/docs/get-started/why-suites.md @@ -268,6 +268,12 @@ const { unit, unitRef } = await TestBed.solitary(PaymentService).compile(); Same API, same patterns across frameworks. All utilities are exported from a single entry point: `@suites/unit` +:::tip Set this up for your AI agent +Suites ships version-matched guidance for AI coding agents inside `@suites/unit`. After installation, add the project-level `AGENTS.md` block and one-line `CLAUDE.md` import so tools like Codex CLI, Claude Code, Cursor, Gemini CLI, and Copilot read `node_modules/@suites/unit/dist/llm/knowledge/` before writing tests. + +[Install Suites for AI agents](/docs/agents/#install) +::: + ## In Summary Suites replaces thousands of lines of brittle, manual test setup with a single, declarative call. Backend teams gain diff --git a/docs/guides/index.md b/docs/guides/index.md index e0ca6be..00da2c3 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 title: Guides description: Practical guides for testing with Suites toc_min_heading_level: 3 diff --git a/docs/guides/sociable.md b/docs/guides/sociable.md index ed7705c..837947c 100644 --- a/docs/guides/sociable.md +++ b/docs/guides/sociable.md @@ -11,7 +11,7 @@ import TabItem from '@theme/TabItem'; > **What this covers:** Testing real component (class) interactions while controlling external dependencies \ > **Time to read:** ~15 minutes \ -> **Prerequisites:** [Unit Testing Fundamentals](/docs/guides/fundamentals), [Solitary Unit Tests](./solitary), [Test Doubles](./test-doubles) \ +> **Prerequisites:** [Unit Testing Fundamentals](/docs/guides/fundamentals), [Solitary Unit Tests](/docs/guides/solitary), [Test Doubles](/docs/guides/test-doubles) \ > **Best for:** Verifying components (classes) work together correctly, catching integration bugs while maintaining test speed Sociable unit tests verify how components interact with their real dependencies while keeping external I/O operations under control. This approach identifies bugs in how business logic components work together - bugs that solitary tests miss. @@ -325,5 +325,6 @@ Sociable tests work alongside solitary tests to provide comprehensive coverage: After understanding sociable testing, explore these resources: -- **[Test Doubles](./test-doubles)**: Core concepts of mocking and stubbing +- **[Test Doubles](/docs/guides/test-doubles)**: Core concepts of mocking and stubbing +- **[AI agent setup](/docs/agents/#install)**: Point your coding agent at the version-matched Suites docs before it writes sociable tests - **[Suites Examples Repository](https://github.com/suites-dev/examples)**: Working examples of sociable testing patterns diff --git a/docs/migration-guides/from-automock.md b/docs/migration-guides/from-automock.md index f1de56e..ab4ea57 100644 --- a/docs/migration-guides/from-automock.md +++ b/docs/migration-guides/from-automock.md @@ -81,6 +81,10 @@ npm install --save-dev @suites/doubles.sinon @suites/di.inversify Suites splits the doubles library and the DI integration into separate packages, so install one `@suites/doubles.*` and one `@suites/di.*` matching your stack. +:::tip Use Suites with AI coding agents +After installing the new packages, point your AI coding agent at the version-matched Suites docs so it stops writing old Automock patterns. [Set up for AI agents](/docs/agents/#install). +::: + ### Step 2: Update Imports Change all imports from Automock packages to the unified Suites import: diff --git a/static/llms.txt b/static/llms.txt index d3c0e04..7c64a45 100644 --- a/static/llms.txt +++ b/static/llms.txt @@ -4,6 +4,14 @@ Suites supports NestJS and InversifyJS, integrates with Jest, Sinon, and Vitest, and offers a migration path from Automock. +## For AI coding agents + +If you are working inside a project that has `@suites/unit` installed, read the bundled docs first: + +`node_modules/@suites/unit/dist/llm/knowledge/index.md` + +These docs are version-matched to the installed `@suites/*` packages and override your training data. Do not use pre-v3 Automock patterns or `Test.createTestingModule` boilerplate when the project uses Suites. See [AI Agents](https://suites.dev/docs/agents/) for the human-facing setup. + ## Get started - [Get Started overview](https://suites.dev/docs/get-started/): entry point for new users