@frontmcp/skills 0.0.1 → 1.0.0-beta.11

package/catalog/frontmcp-testing/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: frontmcp-testing
+description: 'Use when you want to write tests, run tests, add e2e tests, improve test coverage, test a tool, test a resource, or learn how to test any FrontMCP component. The skill for ALL testing needs.'
+tags: [router, testing, jest, e2e, coverage, quality, guide]
+category: testing
+targets: [all]
+bundle: [recommended, full]
+priority: 10
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/testing/overview
+---
+
+# 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. Use `setup-testing` for hands-on Jest configuration and test writing.
+
+## Scenario Routing Table
+
+| Scenario                                | Skill / 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             | `setup-testing` (Unit Testing)  | 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`            | Testing browser builds                                       |
+| Test CLI binary builds                  | `test-cli-binary`               | Testing CLI binary builds                                    |
+| Test with the direct API client         | `test-direct-client`            | Testing with the direct API client                           |
+| Write E2E test handler patterns         | `test-e2e-handler`              | E2E test handler patterns                                    |
+| Unit test individual tools              | `test-tool-unit`                | Unit testing individual tools                                |
+
+## 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        | Use `frontmcp test` (not `jest --config ...`). It auto-generates the correct Jest/SWC config                                                                                                                                                                                                         |
+| 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 |
+
+## Reference
+
+- [Testing Documentation](https://docs.agentfront.dev/frontmcp/testing/overview)
+- Related skills: `setup-testing`, `create-tool`, `create-resource`, `create-prompt`, `configure-auth`

package/catalog/{testing/setup-testing/SKILL.md → frontmcp-testing/references/setup-testing.md}

@@ -1,53 +1,34 @@
 ---
 name: setup-testing
-description: Configure and run unit and E2E tests for FrontMCP applications. Use when writing tests, setting up Jest, configuring coverage, or testing tools and resources.
-tags:
-  - testing
-  - jest
-  - e2e
-  - quality
-bundle:
-  - recommended
-  - full
-visibility: both
-priority: 5
-parameters:
-  - name: test-type
-    description: Type of test to set up (unit, e2e, or both)
-    type: string
-    required: false
-    default: both
-  - name: coverage-threshold
-    description: Minimum coverage percentage required
-    type: number
-    required: false
-    default: 95
-examples:
-  - scenario: Set up unit tests for a tool with Jest
-    parameters:
-      test-type: unit
-    expected-outcome: Tool execute method is tested with mocked context, assertions verify output schema
-  - scenario: Set up E2E tests against a running MCP server
-    parameters:
-      test-type: e2e
-    expected-outcome: McpTestClient connects to server, calls tools, and verifies responses with MCP matchers
-  - scenario: Configure full test suite with 95% coverage enforcement
-    parameters:
-      test-type: both
-      coverage-threshold: 95
-    expected-outcome: Jest runs unit and E2E tests with coverage thresholds enforced in CI
-license: MIT
-compatibility: Requires Node.js 18+, Jest 29+, and @frontmcp/testing for E2E tests
-metadata:
-  category: testing
-  difficulty: beginner
-  docs: https://docs.agentfront.dev/frontmcp/testing/overview
+description: Configure Jest, write unit and E2E tests, and enforce 95%+ coverage for FrontMCP applications
 ---
 
 # Set Up Testing for FrontMCP Applications
 
 This skill covers testing FrontMCP applications at three levels: unit tests for individual tools/resources/prompts, E2E tests exercising the full MCP protocol, and manual testing with `frontmcp dev`.
 
+## When to Use This Skill
+
+### Must Use
+
+- Writing the first unit test for a new tool, resource, or prompt class
+- Setting up Jest configuration and coverage thresholds for a FrontMCP library
+- Creating E2E tests that exercise the full MCP protocol via `McpTestClient`
+
+### Recommended
+
+- Adding coverage enforcement to CI for an existing library that lacks thresholds
+- Writing authenticated E2E tests with `TestTokenFactory` and `MockOAuthServer`
+- Migrating existing `.test.ts` files to the required `.spec.ts` naming convention
+
+### Skip When
+
+- Building a new tool class from scratch (see `create-tool`)
+- Creating resources or prompts before you have anything to test (see `create-resource`, `create-prompt`)
+- Debugging deployment issues unrelated to test configuration (see `deploy-to-node`, `deploy-to-vercel`)
+
+> **Decision:** Use this skill when you need to configure, write, or run Jest tests for FrontMCP tools, resources, or prompts.
+
 ## Testing Standards
 
 FrontMCP requires:
@@ -65,7 +46,7 @@ FrontMCP requires:
 
 Place test files next to the source file or in a `__tests__` directory:
 
-```
+```text
 src/
   tools/
     my-tool.ts
@@ -350,7 +331,7 @@ describe('Advanced E2E', () => {
     });
 
     client = await McpTestClient.create({ baseUrl: server.info.baseUrl })
-      .withTransport('streamable-http')
+      .withTransport('modern') // 'modern' preset enables streamable HTTP + strict sessions
       .buildAndConnect();
   });
 
@@ -514,26 +495,61 @@ node scripts/fix-unused-imports.mjs feature/my-branch
 | Playwright browser tests | UI tests with Playwright                          | `.pw.spec.ts`   |
 | Constructor validation   | Unit test verifying throws on invalid input       | `.spec.ts`      |
 
-## Common Mistakes
+## Common Patterns
+
+| Pattern          | Correct                                                  | Incorrect                                        | Why                                                                            |
+| ---------------- | -------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------ |
+| Test file naming | `my-tool.spec.ts`, `my-tool.e2e.spec.ts`                 | `my-tool.test.ts`, `my-tool.test.tsx`            | Nx and Jest configs only recognize `.spec.ts` convention                       |
+| Test description | `'should return formatted output for valid input'`       | `'PT-001: test formatted output'`                | Descriptive names; no ID prefixes                                              |
+| Mock types       | `const ctx = { scope: { get: jest.fn() } } as unknown`   | `const ctx: any = { scope: { get: jest.fn() } }` | Strict TypeScript; avoid `any` in mocks                                        |
+| Error assertion  | `expect(err).toBeInstanceOf(ResourceNotFoundError)`      | `expect(() => ...).toThrow()`                    | Verify the exact error class and MCP error code, not just that something threw |
+| Constructor test | Always test `new MyService({})` throws on invalid config | Skip constructor validation                      | Catches misconfiguration early; required for 95% branch coverage               |
+| E2E test imports | `import { test, expect } from '@frontmcp/testing'`       | `import { expect } from '@jest/globals'`         | `@frontmcp/testing` provides MCP-specific matchers like `toContainTool()`      |
+| Coverage check   | `nx test my-lib --coverage` before push                  | Push without coverage check                      | CI enforces 95% thresholds; catch failures locally first                       |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] Jest config exists with `coverageThreshold` set to 95% for all metrics
+- [ ] `tsconfig.spec.json` exists and extends the base tsconfig
+- [ ] `@frontmcp/testing` is installed as a dev dependency for E2E tests
+- [ ] Test files use `.spec.ts` (unit), `.e2e.spec.ts` (E2E), or `.perf.spec.ts` (perf) extension
+
+### Unit Tests
+
+- [ ] Each tool's `execute()` method is tested with valid and invalid inputs
+- [ ] Each resource's `read()` method is tested and output matches `ReadResourceResult` shape
+- [ ] Each prompt's `execute()` method is tested and output matches `GetPromptResult` shape
+- [ ] Constructor validation tests verify throws on invalid config
+- [ ] Error classes are verified with `instanceof` checks and `mcpErrorCode` assertions
+
+### E2E Tests
+
+- [ ] Fixture-based tests use `test.use({ server, port })` for server lifecycle
+- [ ] Tools appear in `tools/list` response via `toContainTool()` matcher
+- [ ] Tool calls return expected results via `toBeSuccessful()` matcher
+- [ ] Authenticated tests use `TestTokenFactory` and verify rejection without token
+
+### CI Integration
+
+- [ ] `nx test <lib> --coverage` passes locally with 95%+ on all metrics
+- [ ] Unused imports are cleaned via `node scripts/fix-unused-imports.mjs`
+- [ ] No TypeScript warnings in test files
+
+## Troubleshooting
 
-- **Using `.test.ts` file extension** -- all test files must use `.spec.ts`. The Nx and Jest configurations expect this convention.
-- **Testing implementation details** -- test inputs and outputs, not internal method calls. Tools should be tested through their `execute` interface.
-- **Skipping constructor validation tests** -- always test that constructors throw on invalid input.
-- **Skipping error `instanceof` checks** -- verify that thrown errors are instances of the correct error class, not just that an error was thrown.
-- **Using test ID prefixes** -- do not use prefixes like "PT-001" in test names. Use descriptive names like "should return formatted output for valid input".
-- **Falling below 95% coverage** -- the CI pipeline enforces coverage thresholds. Run `nx test <lib> --coverage` locally before pushing.
-- **Using `any` in test mocks** -- use `unknown` or properly typed mocks. Follow the strict TypeScript guidelines.
+| Problem                                      | Cause                                                   | Solution                                                                                              |
+| -------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Jest cannot find test files                  | Files use `.test.ts` instead of `.spec.ts`              | Rename to `.spec.ts`; Nx test runner only picks up `.spec.ts` by default                              |
+| Coverage below 95% threshold                 | Untested branches or constructor paths                  | Run `nx test <lib> --coverage` and check the HTML report for uncovered lines                          |
+| E2E test times out on `TestServer.start()`   | Server entrypoint fails to start or wrong port          | Verify `server` path and `port` in `test.use()`; check server logs for startup errors                 |
+| `toContainTool` matcher not found            | Using `expect` from Jest instead of `@frontmcp/testing` | Import `expect` from `@frontmcp/testing` to get MCP-specific matchers                                 |
+| `McpTestClient.create()` connection refused  | Test server not running or wrong `baseUrl`              | Ensure `TestServer.start()` completes before creating client; verify port matches                     |
+| Istanbul shows 0% coverage for async methods | TypeScript compilation source-map mismatch              | Known issue with `ts-jest` and certain async patterns; check `tsconfig.spec.json` source-map settings |
+| Auth E2E test returns 401 unexpectedly       | Token not set or expired                                | Call `mcp.setAuthToken(token)` before the tool call; use `auth.createToken()` with valid claims       |
 
 ## Reference
 
-- Testing package: [`@frontmcp/testing`](https://docs.agentfront.dev/frontmcp/testing/overview)
-- Test client: `McpTestClient` — import from `@frontmcp/testing`
-- Test client builder: `McpTestClient.builder()` — fluent API for test setup
-- MCP matchers: `toContainTool()`, `toBeSuccessful()` — import from `@frontmcp/testing`
-- Test fixtures: `createTestFixture()` — import from `@frontmcp/testing`
-- Test server: `TestServer` — import from `@frontmcp/testing`
-- Performance testing: `perfTest()`, `MetricsCollector` — import from `@frontmcp/testing`
-- Auth testing: `TestTokenFactory`, `MockOAuthServer` — import from `@frontmcp/testing`
-- Interceptors: `TestInterceptor` — import from `@frontmcp/testing`
-- HTTP mocking: `HttpMock` — import from `@frontmcp/testing`
-- [Source code on GitHub](https://github.com/agentfront/frontmcp/tree/main/libs/testing)
+- [Testing Documentation](https://docs.agentfront.dev/frontmcp/testing/overview)
+- Related skills: `create-tool`, `create-resource`, `create-prompt`, `setup-project`, `nx-workflow`

package/catalog/{testing/setup-testing → frontmcp-testing}/references/test-auth.md

@@ -1,3 +1,8 @@
+---
+name: test-auth
+description: Test authenticated MCP servers with TestTokenFactory, MockOAuthServer, and role-based access
+---
+
 # Testing with Authentication
 
 ```typescript

package/catalog/{testing/setup-testing → frontmcp-testing}/references/test-browser-build.md

@@ -1,3 +1,8 @@
+---
+name: test-browser-build
+description: Validate browser build output for Node.js-free bundles and test with Playwright
+---
+
 # Testing Browser Build
 
 After building with `frontmcp build --target browser`, validate the output:

package/catalog/{testing/setup-testing → frontmcp-testing}/references/test-cli-binary.md

@@ -1,3 +1,8 @@
+---
+name: test-cli-binary
+description: Test CLI binary and SEA build for startup, health check, and JS bundle import
+---
+
 # Testing CLI Binary / SEA Build
 
 After building with `frontmcp build --target cli`, test the binary:

package/catalog/{testing/setup-testing → frontmcp-testing}/references/test-direct-client.md

@@ -1,3 +1,8 @@
+---
+name: test-direct-client
+description: In-memory testing with create() and connectOpenAI/connectClaude without HTTP overhead
+---
+
 # Testing with Direct Client (No HTTP)
 
 Uses `connect()` or `create()` for in-memory testing without HTTP overhead.

package/catalog/{testing/setup-testing → frontmcp-testing}/references/test-e2e-handler.md

@@ -1,3 +1,8 @@
+---
+name: test-e2e-handler
+description: Full MCP protocol E2E tests over HTTP with McpTestClient and TestServer
+---
+
 # E2E Testing with McpTestClient (HTTP Handler)
 
 Tests the full MCP protocol over HTTP — validates tools, resources, prompts end-to-end.

package/catalog/{testing/setup-testing → frontmcp-testing}/references/test-tool-unit.md

@@ -1,6 +1,12 @@
+---
+name: test-tool-unit
+description: Unit test a ToolContext execute method with mock context, inputs, and Zod schema validation
+---
+
 # Unit Testing a Tool
 
 ```typescript
+import { z } from 'zod';
 import { ToolContext } from '@frontmcp/sdk';
 import { AddTool } from '../tools/add.tool';