agentfront/frontmcp-testing

FrontMCP Testing Router

Entry 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.

When to Use This Skill

Must Use

• Setting up testing infrastructure for a new FrontMCP project
• Deciding how to test a specific component type (tool, resource, prompt, agent)
• Planning a testing strategy that covers unit, E2E, and coverage requirements

Recommended

• Looking up testing patterns for a component type you haven't tested before
• Understanding the relationship between unit tests, E2E tests, and coverage thresholds
• Troubleshooting test failures or coverage gaps

Skip When

• You need detailed Jest configuration and test harness setup (go directly to setup-testing)
• You need to build components, not test them (see frontmcp-development)
• You need to deploy, not test (see frontmcp-deployment)

Decision: Use this skill for testing strategy and routing. Open the setup-testing reference under references/ for hands-on Jest configuration and test writing.

Prerequisites

• A FrontMCP project with at least one component to test (see frontmcp-development).
• Jest installed and configured — if not, start with setup-testing before opening any other testing skill.
• The component itself implemented and exported; tests reach decorated classes through the SDK, not by importing internal builders.

Steps

This is a router skill. Follow this order to pick a testing approach, then move to the target reference under references/.

1. Pick the test layer — unit (fastest, mock DI), integration (real DI scope), or E2E (real MCP client + server). Use the Testing Strategy table below.
2. Pick the component flavour — tool / resource / prompt / agent / job — each has a distinct recipe.
3. Pick the runtime concern — auth, browser/CLI build, direct vs streamable transport — and add the matching reference to your reading list.
4. 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.
5. Enforce coverage — confirm the project's 95%+ thresholds are wired into Jest before merging (see references/setup-testing.md).

Scenario Routing Table

| Scenario | Reference / Section | Description | | --------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------- | | Set up Jest, coverage, and test harness | setup-testing | Full Jest config, test utilities, and coverage thresholds | | Write unit tests for a tool | test-tool-unit | Mock DI, validate input/output, test error paths | | Write unit tests for a resource | setup-testing (Unit Testing) | Test URI resolution, template params, read results | | Write unit tests for a prompt | setup-testing (Unit Testing) | Test argument handling, message generation | | Write E2E protocol-level tests | setup-testing (E2E Testing) | Real MCP client/server, full protocol flow | | Test authenticated endpoints | test-auth | E2E with OAuth tokens, session validation, role-based access | | Test deployment builds | setup-testing + deploy-to-* | Smoke tests against built output | | Test browser builds | test-browser-build | Smoke-test a frontmcp build --target browser bundle (import the bundle, optional Playwright suite) | | Test CLI binary builds | test-cli-binary | Spawn-and-curl smoke tests for frontmcp build --target cli artifacts | | Test with the direct API client | test-direct-client | In-memory testing via create(), connectOpenAI(), connectClaude() (no HTTP) | | Write E2E test handler patterns | test-e2e-handler | Manual McpTestClient + TestServer E2E patterns (alternative to fixture API) | | Unit test individual tools | test-tool-unit | Unit testing individual ToolContext subclasses with a mock context |

Testing Strategy by Component Type

| Component | Unit Test Focus | E2E Test Focus | Key Assertions | | --------- | -------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------- | | Tool | Input validation, execute logic, error paths, DI mocking | tools/call via MCP client | Output matches schema, errors return MCP codes | | Resource | URI resolution, read content, template param handling | resources/read via MCP client | Content type correct, URI patterns resolve | | Prompt | Argument validation, message generation, multi-turn | prompts/get via MCP client | Messages match expected structure | | Agent | LLM config, tool selection, handoff logic | Agent loop via MCP client | Tools called in order, result synthesized | | Provider | Lifecycle hooks, factory output, singleton behavior | Indirectly via tool/resource tests | Instance reuse, cleanup on scope disposal | | Job | Progress tracking, retry logic, attempt counting | Job execution via test harness | Progress events emitted, retries respected | | Workflow | Step dependencies, conditions, input mapping functions | Workflow run via test harness | Steps execute in order, conditions evaluated, continueOnError respected | | Skill | Instruction loading (inline/file/url), tool validation | Skill discovery via MCP/HTTP | Instructions resolve, tool refs validated per toolValidation mode | | Plugin | Context extensions, provider registration, hook firing | Indirectly via tool tests | Extensions available on this, hooks fire at correct stages |

Cross-Cutting Testing Patterns

| Pattern | Rule | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | File naming | Always .spec.ts (not .test.ts); E2E uses .e2e.spec.ts | | 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 | | 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; delegates to a user-provided jest.config.{ts,js,mjs,cjs,json} if present). Nx monorepos: use nx test <lib> (resolves the project's jest.config.ts). Never invoke jest --config ... directly | | Coverage threshold | 95%+ across statements, branches, functions, lines | | Test descriptions | Plain English, no prefixes like "PT-001"; describe behavior not implementation | | Mocking | Mock providers via DI token replacement, never mock the framework | | 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 | | Error testing | Assert instanceof specific error class AND MCP error code | | Async | Always await async operations; use expect(...).rejects.toThrow() for async errors |

Common Patterns

| Pattern | Correct | Incorrect | Why | | ------------------ | ------------------------------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------- | | 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 | | 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 | | Error assertions | expect(err).toBeInstanceOf(ResourceNotFoundError) | expect(err.message).toContain('not found') | Class checks are stable; message strings are fragile | | E2E transport | Use @frontmcp/testing MCP client with real server | HTTP requests with fetch | The test client handles protocol details (session, framing) | | Coverage gaps | Investigate uncovered branches, add targeted tests | Add istanbul ignore comments | Coverage gaps often hide real bugs; ignoring them defeats the purpose |

Verification Checklist

Infrastructure

• [ ] Jest configured with @frontmcp/testing preset
• [ ] Coverage thresholds set to 95% in jest.config
• [ ] Test files use .spec.ts extension throughout

Unit Tests

• [ ] Each tool has unit tests covering happy path, validation errors, and DI failures
• [ ] Each resource has unit tests covering URI resolution and read content
• [ ] Provider lifecycle (init, dispose) tested where applicable

E2E Tests

• [ ] At least one E2E test exercises full MCP protocol flow (connect, list, call, disconnect)
• [ ] Authenticated E2E tests use proper test tokens (not mocked auth)
• [ ] E2E tests clean up state after execution

CI Integration

• [ ] Tests run in CI pipeline on every PR
• [ ] Coverage report published and enforced
• [ ] Failing tests block merge

Troubleshooting

| Problem | Cause | Solution | | ---------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------- | | Jest not finding test files | Wrong file extension (.test.ts instead of .spec.ts) | Rename to .spec.ts; check testMatch in jest.config | | Coverage below 95% | Untested error paths or conditional branches | Run frontmcp test --coverage and inspect uncovered lines in the report | | E2E test timeout | Server startup too slow or port conflict | Increase Jest timeout; use random port allocation | | DI resolution fails in tests | Provider not registered in test scope | Register mock providers before creating the test context | | 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 |

Examples

Each reference has matching examples under examples/<reference>/:

setup-testing

| Example | Level | Description | | ---------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | | fixture-based-e2e-test | Advanced | Write E2E tests using the fixture API from @frontmcp/testing that manages server lifecycle automatically and uses MCP-specific custom matchers. | | jest-config-with-coverage | Basic | Set up a Jest configuration file that enforces 95%+ coverage across all metrics for a FrontMCP library. | | unit-test-tool-resource-prompt | Intermediate | Write unit tests for the three core MCP primitives, verifying that outputs match the expected MCP response shapes. |

test-auth

| Example | Level | Description | | -------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------- | | oauth-flow-test | Advanced | Use MockOAuthServer to simulate an OAuth identity provider and test the authorization code flow. | | role-based-access-test | Intermediate | Verify that tools enforce role-based access by testing admin and user tokens against protected endpoints. | | token-factory-test | Basic | Use TestTokenFactory to create tokens and verify authenticated and unauthenticated requests. |

test-browser-build

| Example | Level | Description | | ----------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------ | | browser-bundle-validation | Basic | Verify that the browser build produces a valid bundle without Node.js-only module references. | | playwright-browser-test | Advanced | Use Playwright to test a browser-based MCP client that loads and calls tools from an MCP server. |

test-cli-binary

| Example | Level | Description | | ------------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------ | | binary-startup-test | Basic | Verify that a compiled CLI binary starts correctly and responds to health checks. | | js-bundle-import-test | Intermediate | Verify that the compiled JS bundle can be imported and exports the expected modules after a frontmcp build step. |

test-direct-client

| Example | Level | Description | | ----------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | | basic-create-test | Basic | Test tools in-memory without any HTTP overhead using the create() function from @frontmcp/sdk. | | openai-claude-format-test | Intermediate | Verify that tools are returned in the correct format for OpenAI and Claude clients using connectOpenAI and connectClaude. |

test-e2e-handler

| Example | Level | Description | | --------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------- | | basic-e2e-test | Basic | Set up a basic E2E test that starts a server, connects a client, and verifies tools are listed. | | manual-client-with-transport | Advanced | Use McpTestClient.create() with explicit transport settings for fine-grained control over E2E tests. | | tool-call-and-error-e2e | Intermediate | Test successful tool calls and verify that invalid inputs produce proper error responses over the full MCP protocol. |

test-tool-unit

| Example | Level | Description | | ----------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------- | | basic-tool-test | Basic | Test a simple tool's execute() method with mock context and verify the output. | | schema-validation-test | Intermediate | Validate that a tool's Zod input schema rejects invalid data before execute() is called. | | tool-error-handling-test | Advanced | Test that a tool throws the correct MCP error classes with proper error codes and JSON-RPC error shapes. |

Accessing This Skill

Skills are distributed as plain SKILL.md files plus a sibling references/ and examples/ tree, so consumers can pick whichever access mode fits:

| Mode | How it works | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | | 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. | | 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. |

The catalog itself is not an MCP server. The skill:// URIs only resolve when a server has been configured to host this skill.

Reference

• Testing Documentation
• Related skills: setup-testing, create-tool, create-resource, create-prompt, configure-auth