1---2name: frontmcp-testing3description: Use for anything about testing FrontMCP servers: writing or running unit, integration, and E2E tests and reaching the 95%+ coverage bar. Covers Jest setup and coverage gating; unit-testing a ToolContext execute() with mock context, inputs, and Zod schema validation; testing resources and prompts; in-memory testing via create() and connectOpenAI / connectClaude (no HTTP); full MCP-protocol E2E over HTTP with McpTestClient and TestServer; authenticated tests with TestTokenFactory, MockOAuthServer, and role-based access; browser-bundle validation with Playwright; and CLI-binary / SEA startup tests. Triggers: write tests, run tests, add e2e tests, improve coverage, test a tool / resource / prompt, mock auth, jest config. The skill for ALL testing needs.4license: Apache-2.05---67# FrontMCP Testing Router89Entry point for testing FrontMCP applications. This skill helps you navigate testing strategies across component types and find the right patterns for unit, integration, and E2E tests.1011## When to Use This Skill1213### Must Use1415- Setting up testing infrastructure for a new FrontMCP project16- Deciding how to test a specific component type (tool, resource, prompt, agent)17- Planning a testing strategy that covers unit, E2E, and coverage requirements1819### Recommended2021- Looking up testing patterns for a component type you haven't tested before22- Understanding the relationship between unit tests, E2E tests, and coverage thresholds23- Troubleshooting test failures or coverage gaps2425### Skip When2627- You need detailed Jest configuration and test harness setup (go directly to `setup-testing`)28- You need to build components, not test them (see `frontmcp-development`)29- You need to deploy, not test (see `frontmcp-deployment`)3031> **Decision:** Use this skill for testing strategy and routing. Open the `setup-testing` reference under `references/` for hands-on Jest configuration and test writing.3233## Prerequisites3435- A FrontMCP project with at least one component to test (see `frontmcp-development`).36- Jest installed and configured — if not, start with `setup-testing` before opening any other testing skill.37- The component itself implemented and exported; tests reach decorated classes through the SDK, not by importing internal builders.3839## Steps4041This is a router skill. Follow this order to pick a testing approach, then move to the target reference under `references/`.42431. **Pick the test layer** — unit (fastest, mock DI), integration (real DI scope), or E2E (real MCP client + server). Use the Testing Strategy table below.442. **Pick the component flavour** — tool / resource / prompt / agent / job — each has a distinct recipe.453. **Pick the runtime concern** — auth, browser/CLI build, direct vs streamable transport — and add the matching reference to your reading list.464. **Open the target reference** (e.g. `references/test-tool-unit.md`, `references/test-e2e-handler.md`, `references/test-auth.md`) and follow its Steps section.475. **Enforce coverage** — confirm the project's 95%+ thresholds are wired into Jest before merging (see `references/setup-testing.md`).4849## Scenario Routing Table5051| Scenario | Reference / Section | Description |52| --------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------- |53| Set up Jest, coverage, and test harness | `setup-testing` | Full Jest config, test utilities, and coverage thresholds |54| Write unit tests for a tool | `test-tool-unit` | Mock DI, validate input/output, test error paths |55| Write unit tests for a resource | `setup-testing` (Unit Testing) | Test URI resolution, template params, read results |56| Write unit tests for a prompt | `setup-testing` (Unit Testing) | Test argument handling, message generation |57| Write E2E protocol-level tests | `setup-testing` (E2E Testing) | Real MCP client/server, full protocol flow |58| Test authenticated endpoints | `test-auth` | E2E with OAuth tokens, session validation, role-based access |59| Test deployment builds | `setup-testing` + `deploy-to-*` | Smoke tests against built output |60| Test browser builds | `test-browser-build` | Smoke-test a `frontmcp build --target browser` bundle (import the bundle, optional Playwright suite) |61| Test CLI binary builds | `test-cli-binary` | Spawn-and-curl smoke tests for `frontmcp build --target cli` artifacts |62| Test with the direct API client | `test-direct-client` | In-memory testing via `create()`, `connectOpenAI()`, `connectClaude()` (no HTTP) |63| Write E2E test handler patterns | `test-e2e-handler` | Manual `McpTestClient` + `TestServer` E2E patterns (alternative to fixture API) |64| Unit test individual tools | `test-tool-unit` | Unit testing individual `ToolContext` subclasses with a mock context |6566## Testing Strategy by Component Type6768| Component | Unit Test Focus | E2E Test Focus | Key Assertions |69| --------- | -------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------- |70| Tool | Input validation, execute logic, error paths, DI mocking | `tools/call` via MCP client | Output matches schema, errors return MCP codes |71| Resource | URI resolution, read content, template param handling | `resources/read` via MCP client | Content type correct, URI patterns resolve |72| Prompt | Argument validation, message generation, multi-turn | `prompts/get` via MCP client | Messages match expected structure |73| Agent | LLM config, tool selection, handoff logic | Agent loop via MCP client | Tools called in order, result synthesized |74| Provider | Lifecycle hooks, factory output, singleton behavior | Indirectly via tool/resource tests | Instance reuse, cleanup on scope disposal |75| Job | Progress tracking, retry logic, attempt counting | Job execution via test harness | Progress events emitted, retries respected |76| Workflow | Step dependencies, conditions, input mapping functions | Workflow run via test harness | Steps execute in order, conditions evaluated, continueOnError respected |77| Skill | Instruction loading (inline/file/url), tool validation | Skill discovery via MCP/HTTP | Instructions resolve, tool refs validated per `toolValidation` mode |78| Plugin | Context extensions, provider registration, hook firing | Indirectly via tool tests | Extensions available on `this`, hooks fire at correct stages |7980## Cross-Cutting Testing Patterns8182| Pattern | Rule |83| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |84| File naming | Always `.spec.ts` (not `.test.ts`); E2E uses `.e2e.spec.ts` |85| File organization | Split E2E tests by app/feature: `e2e/calc.e2e.spec.ts`, `e2e/ecommerce.e2e.spec.ts`. Never put all tests in a single `server.e2e.spec.ts` |86| Test runner | Standalone projects: use `frontmcp test` (auto-generates Jest/SWC config; discovers `src/**/*.spec.ts(x)`, `__tests__/**/*.spec.ts(x)`, and `e2e/**/*.e2e.spec.ts(x)`; transforms both `.ts` and `.tsx` with the automatic JSX runtime; transpiles ESM-only deps such as `jose` under npm, yarn AND pnpm's `node_modules/.pnpm/` store — add your own via `test.esmPackages` in `frontmcp.config.ts`; delegates to a user-provided `jest.config.{ts,js,mjs,cjs,json}` if present, which drops the injected ESM transforms). Nx monorepos: use `nx test <lib>` (resolves the project's `jest.config.ts`). Never invoke `jest --config ...` directly |87| Coverage threshold | 95%+ across statements, branches, functions, lines |88| Test descriptions | Plain English, no prefixes like "PT-001"; describe behavior not implementation |89| Mocking | Mock providers via DI token replacement, never mock the framework |90| httpMock scope | `httpMock` intercepts HTTP in the **test process** only, NOT in the MCP server subprocess. Do not use httpMock to intercept server-to-API calls — those happen in the child process. Use httpMock for verifying client-to-server request shapes or mocking external APIs called from the test itself |91| Error testing | Assert `instanceof` specific error class AND MCP error code |92| Async | Always `await` async operations; use `expect(...).rejects.toThrow()` for async errors |9394## Common Patterns9596| Pattern | Correct | Incorrect | Why |97| ------------------ | ------------------------------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------- |98| Test file location | `fetch-weather.tool.spec.ts` next to source | `__tests__/fetch-weather.test.ts` | Co-location with `.spec.ts` extension matches FrontMCP conventions |99| DI mocking | Replace token with mock via `scope.register(TOKEN, mockImpl)` | `jest.mock('../provider')` module mock | DI mocking is cleaner, type-safe, and tests the real integration path |100| Error assertions | `expect(err).toBeInstanceOf(ResourceNotFoundError)` | `expect(err.message).toContain('not found')` | Class checks are stable; message strings are fragile |101| E2E transport | Use `@frontmcp/testing` MCP client with real server | HTTP requests with `fetch` | The test client handles protocol details (session, framing) |102| Coverage gaps | Investigate uncovered branches, add targeted tests | Add `istanbul ignore` comments | Coverage gaps often hide real bugs; ignoring them defeats the purpose |103104## Verification Checklist105106### Infrastructure107108- [ ] Jest configured with `@frontmcp/testing` preset109- [ ] Coverage thresholds set to 95% in jest.config110- [ ] Test files use `.spec.ts` extension throughout111112### Unit Tests113114- [ ] Each tool has unit tests covering happy path, validation errors, and DI failures115- [ ] Each resource has unit tests covering URI resolution and read content116- [ ] Provider lifecycle (init, dispose) tested where applicable117118### E2E Tests119120- [ ] At least one E2E test exercises full MCP protocol flow (connect, list, call, disconnect)121- [ ] Authenticated E2E tests use proper test tokens (not mocked auth)122- [ ] E2E tests clean up state after execution123124### CI Integration125126- [ ] Tests run in CI pipeline on every PR127- [ ] Coverage report published and enforced128- [ ] Failing tests block merge129130## Troubleshooting131132| Problem | Cause | Solution |133| ---------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |134| Jest not finding test files | Wrong file extension (`.test.ts` instead of `.spec.ts`) | Rename to `.spec.ts`; check `testMatch` in jest.config |135| `SyntaxError: Unexpected token 'export'` | An ESM-only dependency is being ignored instead of transpiled | Add it to `test.esmPackages` in `frontmcp.config.ts`. With a hand-written `jest.config.ts`, use the pnpm-safe `transformIgnorePatterns` in [`setup-testing`](./references/setup-testing.md#jest-configuration) AND make sure `transform` matches `.js` (`^.+\.[tj]sx?$` + `allowJs`) — un-ignoring a file does nothing if no transform matches it |136| Coverage below 95% | Untested error paths or conditional branches | Run `frontmcp test --coverage` and inspect uncovered lines in the report |137| E2E test timeout | Server startup too slow or port conflict | Increase Jest timeout; use random port allocation |138| DI resolution fails in tests | Provider not registered in test scope | Register mock providers before creating the test context |139| Istanbul shows 0% on async methods | TypeScript source-map mismatch with Istanbul | Known issue with some TS compilation settings; verify coverage with actual test output |140141## Examples142143Each reference has matching examples under [`examples/<reference>/`](./examples/):144145### `setup-testing`146147| Example | Level | Description |148| ---------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |149| [`fixture-based-e2e-test`](./examples/setup-testing/fixture-based-e2e-test.md) | Advanced | Write E2E tests using the fixture API from `@frontmcp/testing` that manages server lifecycle automatically and uses MCP-specific custom matchers. |150| [`jest-config-with-coverage`](./examples/setup-testing/jest-config-with-coverage.md) | Basic | Set up a Jest configuration file that enforces 95%+ coverage across all metrics for a FrontMCP library. |151| [`unit-test-tool-resource-prompt`](./examples/setup-testing/unit-test-tool-resource-prompt.md) | Intermediate | Write unit tests for the three core MCP primitives, verifying that outputs match the expected MCP response shapes. |152153### `test-auth`154155| Example | Level | Description |156| -------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------- |157| [`oauth-flow-test`](./examples/test-auth/oauth-flow-test.md) | Advanced | Use `MockOAuthServer` to simulate an OAuth identity provider and test the authorization code flow. |158| [`role-based-access-test`](./examples/test-auth/role-based-access-test.md) | Intermediate | Verify that tools enforce role-based access by testing admin and user tokens against protected endpoints. |159| [`token-factory-test`](./examples/test-auth/token-factory-test.md) | Basic | Use `TestTokenFactory` to create tokens and verify authenticated and unauthenticated requests. |160161### `test-browser-build`162163| Example | Level | Description |164| ----------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------ |165| [`browser-bundle-validation`](./examples/test-browser-build/browser-bundle-validation.md) | Basic | Verify that the browser build produces a valid bundle without Node.js-only module references. |166| [`playwright-browser-test`](./examples/test-browser-build/playwright-browser-test.md) | Advanced | Use Playwright to test a browser-based MCP client that loads and calls tools from an MCP server. |167168### `test-cli-binary`169170| Example | Level | Description |171| ------------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------ |172| [`binary-startup-test`](./examples/test-cli-binary/binary-startup-test.md) | Basic | Verify that a compiled CLI binary starts correctly and responds to health checks. |173| [`js-bundle-import-test`](./examples/test-cli-binary/js-bundle-import-test.md) | Intermediate | Verify that the compiled JS bundle can be imported and exports the expected modules after a `frontmcp build` step. |174175### `test-direct-client`176177| Example | Level | Description |178| ----------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------- |179| [`basic-create-test`](./examples/test-direct-client/basic-create-test.md) | Basic | Test tools in-memory without any HTTP overhead using the `create()` function from `@frontmcp/sdk`. |180| [`openai-claude-format-test`](./examples/test-direct-client/openai-claude-format-test.md) | Intermediate | Verify that tools are returned in the correct format for OpenAI and Claude clients using `connectOpenAI` and `connectClaude`. |181182### `test-e2e-handler`183184| Example | Level | Description |185| --------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------- |186| [`basic-e2e-test`](./examples/test-e2e-handler/basic-e2e-test.md) | Basic | Set up a basic E2E test that starts a server, connects a client, and verifies tools are listed. |187| [`manual-client-with-transport`](./examples/test-e2e-handler/manual-client-with-transport.md) | Advanced | Use `McpTestClient.create()` with explicit transport settings for fine-grained control over E2E tests. |188| [`tool-call-and-error-e2e`](./examples/test-e2e-handler/tool-call-and-error-e2e.md) | Intermediate | Test successful tool calls and verify that invalid inputs produce proper error responses over the full MCP protocol. |189190### `test-tool-unit`191192| Example | Level | Description |193| ----------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------- |194| [`basic-tool-test`](./examples/test-tool-unit/basic-tool-test.md) | Basic | Test a simple tool's `execute()` method with mock context and verify the output. |195| [`schema-validation-test`](./examples/test-tool-unit/schema-validation-test.md) | Intermediate | Validate that a tool's Zod input schema rejects invalid data before `execute()` is called. |196| [`tool-error-handling-test`](./examples/test-tool-unit/tool-error-handling-test.md) | Advanced | Test that a tool throws the correct MCP error classes with proper error codes and JSON-RPC error shapes. |197198## Accessing This Skill199200Skills are distributed as plain SKILL.md files plus a sibling `references/`201and `examples/` tree, so consumers can pick whichever access mode fits:202203| Mode | How it works |204| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |205| **Filesystem** | Read `libs/skills/catalog/frontmcp-testing/` directly from a clone of the catalog repo, or from a published `@frontmcp/skills` install. SKILL.md is the entry point. |206| **`frontmcp` CLI** | `frontmcp skills list`, `frontmcp skills read frontmcp-testing`, `frontmcp skills read frontmcp-testing:references/<file>.md`, `frontmcp skills install frontmcp-testing` — no server required. |207| **MCP `skill://`** | When a developer mounts this skill into their own FrontMCP server (`@FrontMcp({ skills: [...] })`), the SDK exposes it via SEP-2640 resources: `skill://frontmcp-testing/SKILL.md`, `skill://frontmcp-testing/references/{file}.md`, etc. The server’s `skill://index.json` returns the SEP-2640 discovery document for everything mounted on it. |208209The catalog itself is **not** an MCP server. The `skill://` URIs only resolve210when a server has been configured to host this skill.211212## Reference213214- [Testing Documentation](https://docs.agentfront.dev/frontmcp/testing/overview)215- Related skills: `setup-testing`, `create-tool`, `create-resource`, `create-prompt`, `configure-auth`
agentfront