@frontmcp/skills 0.0.1 → 1.0.0-beta.10

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

@@ -1,53 +1,29 @@
----
-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
----
-
 # 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 +41,7 @@ FrontMCP requires:
 
 Place test files next to the source file or in a `__tests__` directory:
 
-```
+```text
 src/
   tools/
     my-tool.ts
@@ -350,7 +326,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 +490,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-tool-unit.md

@@ -1,6 +1,7 @@
 # Unit Testing a Tool
 
 ```typescript
+import { z } from 'zod';
 import { ToolContext } from '@frontmcp/sdk';
 import { AddTool } from '../tools/add.tool';