@frontmcp/skills 1.0.0-beta.13 → 1.0.0-beta.14

package/catalog/frontmcp-testing/examples/setup-testing/fixture-based-e2e-test.md

@@ -0,0 +1,70 @@
+---
+name: fixture-based-e2e-test
+reference: setup-testing
+level: advanced
+description: 'Write E2E tests using the fixture API from `@frontmcp/testing` that manages server lifecycle automatically and uses MCP-specific custom matchers.'
+tags: [testing, jest, e2e, setup, fixture, based]
+features:
+  - 'Using `test.use()` to configure server path and port for automatic lifecycle management'
+  - 'Importing `test` and `expect` from `@frontmcp/testing` (not from Jest) to access MCP-specific matchers'
+  - 'Custom matchers: `toContainTool()`, `toBeSuccessful()`, `toHaveTextContent()` for MCP assertions'
+  - 'Testing all three MCP primitives (tools, resources, prompts) in a single E2E suite'
+---
+
+# Fixture-Based E2E Test with Custom Matchers
+
+Write E2E tests using the fixture API from `@frontmcp/testing` that manages server lifecycle automatically and uses MCP-specific custom matchers.
+
+## Code
+
+```typescript
+// my-server.e2e.spec.ts
+import { test, expect } from '@frontmcp/testing';
+
+test.use({
+  server: './src/main.ts',
+  port: 3003,
+});
+
+test('server exposes expected tools', async ({ mcp }) => {
+  const tools = await mcp.tools.list();
+  expect(tools).toContainTool('create_record');
+  expect(tools).toContainTool('delete_record');
+});
+
+test('create_record tool returns success', async ({ mcp }) => {
+  const result = await mcp.tools.call('create_record', {
+    name: 'Test Record',
+    type: 'example',
+  });
+
+  expect(result).toBeSuccessful();
+  expect(result).toHaveTextContent('created');
+});
+
+test('reading a resource returns valid content', async ({ mcp }) => {
+  const result = await mcp.resources.read('config://server-info');
+
+  expect(result.contents).toHaveLength(1);
+  expect(result.contents[0]).toHaveProperty('mimeType', 'application/json');
+});
+
+test('prompts return well-formed messages', async ({ mcp }) => {
+  const result = await mcp.prompts.get('summarize', { topic: 'testing' });
+
+  expect(result.messages).toBeDefined();
+  expect(result.messages.length).toBeGreaterThan(0);
+});
+```
+
+## What This Demonstrates
+
+- Using `test.use()` to configure server path and port for automatic lifecycle management
+- Importing `test` and `expect` from `@frontmcp/testing` (not from Jest) to access MCP-specific matchers
+- Custom matchers: `toContainTool()`, `toBeSuccessful()`, `toHaveTextContent()` for MCP assertions
+- Testing all three MCP primitives (tools, resources, prompts) in a single E2E suite
+
+## Related
+
+- See `setup-testing` for the full testing setup reference
+- See `test-e2e-handler` for manual `McpTestClient` E2E patterns

package/catalog/frontmcp-testing/examples/setup-testing/jest-config-with-coverage.md

@@ -0,0 +1,59 @@
+---
+name: jest-config-with-coverage
+reference: setup-testing
+level: basic
+description: 'Set up a Jest configuration file that enforces 95%+ coverage across all metrics for a FrontMCP library.'
+tags: [testing, jest, setup, config, coverage]
+features:
+  - 'How to configure Jest with `ts-jest` for TypeScript test files'
+  - 'Setting 95%+ coverage thresholds required by FrontMCP standards'
+  - 'Proper `tsconfig.spec.json` that extends the base config and includes `.spec.ts` files'
+---
+
+# Jest Configuration with Coverage Thresholds
+
+Set up a Jest configuration file that enforces 95%+ coverage across all metrics for a FrontMCP library.
+
+## Code
+
+```typescript
+// jest.config.ts
+export default {
+  displayName: 'my-lib',
+  preset: '../../jest.preset.js',
+  transform: {
+    '^.+\\.tsx?$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.spec.json' }],
+  },
+  coverageThreshold: {
+    global: {
+      statements: 95,
+      branches: 95,
+      functions: 95,
+      lines: 95,
+    },
+  },
+};
+```
+
+```json
+// tsconfig.spec.json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "module": "commonjs",
+    "types": ["jest", "node"]
+  },
+  "include": ["jest.config.ts", "src/**/*.spec.ts", "src/**/*.spec.tsx"]
+}
+```
+
+## What This Demonstrates
+
+- How to configure Jest with `ts-jest` for TypeScript test files
+- Setting 95%+ coverage thresholds required by FrontMCP standards
+- Proper `tsconfig.spec.json` that extends the base config and includes `.spec.ts` files
+
+## Related
+
+- See `setup-testing` for the full testing setup reference

package/catalog/frontmcp-testing/examples/setup-testing/unit-test-tool-resource-prompt.md

@@ -0,0 +1,115 @@
+---
+name: unit-test-tool-resource-prompt
+reference: setup-testing
+level: intermediate
+description: 'Write unit tests for the three core MCP primitives, verifying that outputs match the expected MCP response shapes.'
+tags: [testing, jest, unit-test, setup, unit, tool]
+features:
+  - 'Testing tool `execute()` with a mock context object assigned via `Object.assign`'
+  - 'Verifying resource `read()` output matches the MCP `ReadResourceResult` shape'
+  - 'Verifying prompt `execute()` output matches the MCP `GetPromptResult` shape'
+  - 'Using Jest matchers like `expect.stringContaining` and `expect.objectContaining` for flexible assertions'
+---
+
+# Unit Testing Tools, Resources, and Prompts
+
+Write unit tests for the three core MCP primitives, verifying that outputs match the expected MCP response shapes.
+
+## Code
+
+```typescript
+// src/tools/__tests__/my-tool.spec.ts
+import { MyTool } from '../my-tool';
+
+describe('MyTool', () => {
+  let tool: MyTool;
+
+  beforeEach(() => {
+    tool = new MyTool();
+  });
+
+  it('should return formatted result for valid input', async () => {
+    const mockContext = {
+      scope: {
+        get: jest.fn(),
+        tryGet: jest.fn(),
+      },
+      fail: jest.fn(),
+      mark: jest.fn(),
+      fetch: jest.fn(),
+    };
+    Object.assign(tool, mockContext);
+
+    const result = await tool.execute({ query: 'test input' });
+
+    expect(result).toEqual({
+      content: [{ type: 'text', text: expect.stringContaining('test input') }],
+    });
+  });
+
+  it('should throw for invalid input', async () => {
+    const mockContext = {
+      scope: { get: jest.fn(), tryGet: jest.fn() },
+      fail: jest.fn(),
+    };
+    Object.assign(tool, mockContext);
+
+    await expect(tool.execute({ query: '' })).rejects.toThrow();
+  });
+});
+```
+
+```typescript
+// src/resources/__tests__/my-resource.spec.ts
+import { MyResource } from '../my-resource';
+
+describe('MyResource', () => {
+  it('should return resource contents matching ReadResourceResult', async () => {
+    const resource = new MyResource();
+    const result = await resource.read({ id: '123' });
+
+    expect(result).toEqual({
+      contents: [
+        {
+          uri: expect.stringMatching(/^resource:\/\//),
+          mimeType: 'application/json',
+          text: expect.any(String),
+        },
+      ],
+    });
+  });
+});
+```
+
+```typescript
+// src/prompts/__tests__/my-prompt.spec.ts
+import { MyPrompt } from '../my-prompt';
+
+describe('MyPrompt', () => {
+  it('should return a valid GetPromptResult', async () => {
+    const prompt = new MyPrompt();
+    const result = await prompt.execute({ topic: 'testing' });
+
+    expect(result).toEqual({
+      messages: expect.arrayContaining([
+        expect.objectContaining({
+          role: 'user',
+          content: expect.objectContaining({ type: 'text' }),
+        }),
+      ]),
+    });
+  });
+});
+```
+
+## What This Demonstrates
+
+- Testing tool `execute()` with a mock context object assigned via `Object.assign`
+- Verifying resource `read()` output matches the MCP `ReadResourceResult` shape
+- Verifying prompt `execute()` output matches the MCP `GetPromptResult` shape
+- Using Jest matchers like `expect.stringContaining` and `expect.objectContaining` for flexible assertions
+
+## Related
+
+- See `setup-testing` for the full testing setup reference
+- See `test-tool-unit` for detailed tool unit testing patterns

package/catalog/frontmcp-testing/examples/test-auth/oauth-flow-test.md

@@ -0,0 +1,78 @@
+---
+name: oauth-flow-test
+reference: test-auth
+level: advanced
+description: 'Use `MockOAuthServer` to simulate an OAuth identity provider and test the authorization code flow.'
+tags: [testing, oauth, auth, flow]
+features:
+  - 'Setting up `MockOAuthServer` with a mock issuer URL and port'
+  - 'Starting an OAuth flow with `startFlow()` specifying client ID, redirect URI, and scopes'
+  - 'Verifying the authorization URL contains an authorization code'
+  - 'Testing concurrent OAuth flows with different client configurations'
+  - 'Proper cleanup with `mockOAuth.close()` in `afterAll`'
+---
+
+# Testing OAuth Authorization Code Flow
+
+Use `MockOAuthServer` to simulate an OAuth identity provider and test the authorization code flow.
+
+## Code
+
+```typescript
+// src/__tests__/oauth-flow.e2e.spec.ts
+import { MockOAuthServer } from '@frontmcp/testing';
+
+describe('OAuth Flow', () => {
+  let mockOAuth: MockOAuthServer;
+
+  beforeAll(async () => {
+    mockOAuth = await MockOAuthServer.create({
+      issuer: 'https://test-idp.example.com',
+      port: 9999,
+    });
+  });
+
+  afterAll(async () => {
+    await mockOAuth.close();
+  });
+
+  it('should complete OAuth authorization code flow', async () => {
+    const { authorizationUrl } = await mockOAuth.startFlow({
+      clientId: 'test-client',
+      redirectUri: 'http://localhost:3001/callback',
+      scopes: ['openid', 'profile'],
+    });
+    expect(authorizationUrl).toContain('code=');
+  });
+
+  it('should support multiple concurrent flows', async () => {
+    const flow1 = await mockOAuth.startFlow({
+      clientId: 'client-a',
+      redirectUri: 'http://localhost:3001/callback',
+      scopes: ['openid'],
+    });
+
+    const flow2 = await mockOAuth.startFlow({
+      clientId: 'client-b',
+      redirectUri: 'http://localhost:3002/callback',
+      scopes: ['openid', 'email'],
+    });
+
+    expect(flow1.authorizationUrl).toContain('code=');
+    expect(flow2.authorizationUrl).toContain('code=');
+    expect(flow1.authorizationUrl).not.toBe(flow2.authorizationUrl);
+  });
+});
+```
+
+## What This Demonstrates
+
+- Setting up `MockOAuthServer` with a mock issuer URL and port
+- Starting an OAuth flow with `startFlow()` specifying client ID, redirect URI, and scopes
+- Verifying the authorization URL contains an authorization code
+- Testing concurrent OAuth flows with different client configurations
+- Proper cleanup with `mockOAuth.close()` in `afterAll`
+
+## Related
+
+- See `test-auth` for the full authentication testing reference

package/catalog/frontmcp-testing/examples/test-auth/role-based-access-test.md

@@ -0,0 +1,88 @@
+---
+name: role-based-access-test
+reference: test-auth
+level: intermediate
+description: 'Verify that tools enforce role-based access by testing admin and user tokens against protected endpoints.'
+tags: [testing, auth, role, based, access]
+features:
+  - 'Creating tokens with different `roles` arrays to simulate admin and user access'
+  - 'Testing that admin-only tools accept admin tokens and reject user tokens'
+  - 'Verifying that user-level tools remain accessible to users with the correct role'
+  - 'Each test creates and closes its own client for proper isolation'
+---
+
+# Testing Role-Based Access Control
+
+Verify that tools enforce role-based access by testing admin and user tokens against protected endpoints.
+
+## Code
+
+```typescript
+// src/__tests__/rbac.e2e.spec.ts
+import { McpTestClient, TestServer, TestTokenFactory } from '@frontmcp/testing';
+import Server from '../src/main';
+
+describe('Role-Based Access', () => {
+  let server: TestServer;
+  let tokenFactory: TestTokenFactory;
+
+  beforeAll(async () => {
+    server = await TestServer.create(Server);
+    tokenFactory = new TestTokenFactory({
+      issuer: 'https://test-idp.example.com',
+      audience: 'my-api',
+    });
+  });
+
+  afterAll(async () => {
+    await server.dispose();
+  });
+
+  it('should allow admin access to admin-only tool', async () => {
+    const adminToken = await tokenFactory.createToken({
+      sub: 'admin-1',
+      roles: ['admin'],
+    });
+
+    const client = await server.connect({ authToken: adminToken });
+    const result = await client.callTool('admin_only_tool', {});
+    expect(result).toBeSuccessful();
+    await client.close();
+  });
+
+  it('should deny user access to admin-only tool', async () => {
+    const userToken = await tokenFactory.createToken({
+      sub: 'user-1',
+      roles: ['user'],
+    });
+
+    const client = await server.connect({ authToken: userToken });
+    const result = await client.callTool('admin_only_tool', {});
+    expect(result.isError).toBe(true);
+    await client.close();
+  });
+
+  it('should allow user access to user-level tool', async () => {
+    const userToken = await tokenFactory.createToken({
+      sub: 'user-2',
+      roles: ['user'],
+    });
+
+    const client = await server.connect({ authToken: userToken });
+    const result = await client.callTool('user_tool', { data: 'hello' });
+    expect(result).toBeSuccessful();
+    await client.close();
+  });
+});
+```
+
+## What This Demonstrates
+
+- Creating tokens with different `roles` arrays to simulate admin and user access
+- Testing that admin-only tools accept admin tokens and reject user tokens
+- Verifying that user-level tools remain accessible to users with the correct role
+- Each test creates and closes its own client for proper isolation
+
+## Related
+
+- See `test-auth` for the full authentication testing reference

package/catalog/frontmcp-testing/examples/test-auth/token-factory-test.md

@@ -0,0 +1,71 @@
+---
+name: token-factory-test
+reference: test-auth
+level: basic
+description: 'Use `TestTokenFactory` to create tokens and verify authenticated and unauthenticated requests.'
+tags: [testing, auth, token, factory]
+features:
+  - 'Creating a `TestTokenFactory` with issuer and audience configuration'
+  - 'Generating test tokens with specific subjects and scopes via `createToken()`'
+  - 'Passing tokens to `server.connect({ authToken })` for authenticated client connections'
+  - 'Verifying that unauthenticated requests are rejected with `isError`'
+---
+
+# Testing Authentication with TestTokenFactory
+
+Use `TestTokenFactory` to create tokens and verify authenticated and unauthenticated requests.
+
+## Code
+
+```typescript
+// src/__tests__/auth.e2e.spec.ts
+import { McpTestClient, TestServer, TestTokenFactory } from '@frontmcp/testing';
+import Server from '../src/main';
+
+describe('Authenticated Server', () => {
+  let server: TestServer;
+  let tokenFactory: TestTokenFactory;
+
+  beforeAll(async () => {
+    server = await TestServer.create(Server);
+    tokenFactory = new TestTokenFactory({
+      issuer: 'https://test-idp.example.com',
+      audience: 'my-api',
+    });
+  });
+
+  afterAll(async () => {
+    await server.dispose();
+  });
+
+  it('should reject unauthenticated requests', async () => {
+    const client = await server.connect();
+    const result = await client.callTool('protected_tool', {});
+    expect(result.isError).toBe(true);
+    await client.close();
+  });
+
+  it('should accept valid token', async () => {
+    const token = await tokenFactory.createToken({
+      sub: 'user-123',
+      scopes: ['read', 'write'],
+    });
+
+    const client = await server.connect({ authToken: token });
+    const result = await client.callTool('protected_tool', { data: 'test' });
+    expect(result).toBeSuccessful();
+    await client.close();
+  });
+});
+```
+
+## What This Demonstrates
+
+- Creating a `TestTokenFactory` with issuer and audience configuration
+- Generating test tokens with specific subjects and scopes via `createToken()`
+- Passing tokens to `server.connect({ authToken })` for authenticated client connections
+- Verifying that unauthenticated requests are rejected with `isError`
+
+## Related
+
+- See `test-auth` for the full authentication testing reference

package/catalog/frontmcp-testing/examples/test-browser-build/browser-bundle-validation.md

@@ -0,0 +1,58 @@
+---
+name: browser-bundle-validation
+reference: test-browser-build
+level: basic
+description: 'Verify that the browser build produces a valid bundle without Node.js-only module references.'
+tags: [testing, browser, node, bundle, validation]
+features:
+  - 'Checking that the browser build output directory contains `.js` files'
+  - 'Scanning the bundle for Node.js-only `require()` calls that would break in browsers'
+  - 'Using dynamic `import()` to verify the bundle is loadable'
+  - 'Targeting the `dist/browser/` directory where `frontmcp build --target browser` places output'
+---
+
+# Validating Browser Build Output
+
+Verify that the browser build produces a valid bundle without Node.js-only module references.
+
+## Code
+
+```typescript
+// src/__tests__/browser-build.spec.ts
+import * as fs from 'fs';
+import * as path from 'path';
+
+const DIST_DIR = path.resolve(__dirname, '../dist/browser');
+
+describe('Browser Build', () => {
+  it('should produce browser-compatible bundle', () => {
+    const files = fs.readdirSync(DIST_DIR);
+    expect(files.some((f) => f.endsWith('.js'))).toBe(true);
+  });
+
+  it('should not contain Node.js-only modules', () => {
+    const bundle = fs.readFileSync(path.join(DIST_DIR, 'index.js'), 'utf-8');
+    // These should be polyfilled or excluded
+    expect(bundle).not.toContain("require('fs')");
+    expect(bundle).not.toContain("require('child_process')");
+    expect(bundle).not.toContain("require('net')");
+    expect(bundle).not.toContain("require('cluster')");
+  });
+
+  it('should export expected functions', async () => {
+    const mod = await import(path.join(DIST_DIR, 'index.js'));
+    expect(mod).toBeDefined();
+  });
+});
+```
+
+## What This Demonstrates
+
+- Checking that the browser build output directory contains `.js` files
+- Scanning the bundle for Node.js-only `require()` calls that would break in browsers
+- Using dynamic `import()` to verify the bundle is loadable
+- Targeting the `dist/browser/` directory where `frontmcp build --target browser` places output
+
+## Related
+
+- See `test-browser-build` for the full browser build testing reference

package/catalog/frontmcp-testing/examples/test-browser-build/playwright-browser-test.md

@@ -0,0 +1,69 @@
+---
+name: playwright-browser-test
+reference: test-browser-build
+level: advanced
+description: 'Use Playwright to test a browser-based MCP client that loads and calls tools from an MCP server.'
+tags: [testing, browser, playwright, e2e]
+features:
+  - "Using Playwright's `test` and `expect` from `@playwright/test` for browser E2E testing"
+  - 'Waiting for DOM elements with `waitForSelector` before asserting tool list counts'
+  - 'Filling form inputs and clicking buttons to simulate tool calls in the browser'
+  - 'Asserting tool results via `textContent` on result elements'
+  - 'Using the `.pw.spec.ts` file suffix required by FrontMCP naming conventions'
+---
+
+# Testing Browser MCP Client with Playwright
+
+Use Playwright to test a browser-based MCP client that loads and calls tools from an MCP server.
+
+## Code
+
+```typescript
+// src/__tests__/browser-client.pw.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('browser MCP client loads tools', async ({ page }) => {
+  await page.goto('http://localhost:3000');
+
+  // Wait for tools to load from MCP server
+  await page.waitForSelector('[data-testid="tool-list"]');
+
+  const tools = await page.locator('[data-testid="tool-item"]').count();
+  expect(tools).toBeGreaterThan(0);
+});
+
+test('browser client can call a tool', async ({ page }) => {
+  await page.goto('http://localhost:3000');
+
+  await page.fill('[data-testid="input-a"]', '5');
+  await page.fill('[data-testid="input-b"]', '3');
+  await page.click('[data-testid="call-tool"]');
+
+  const result = await page.textContent('[data-testid="result"]');
+  expect(result).toContain('8');
+});
+
+test('browser client shows error for invalid input', async ({ page }) => {
+  await page.goto('http://localhost:3000');
+
+  await page.fill('[data-testid="input-a"]', 'abc');
+  await page.fill('[data-testid="input-b"]', '3');
+  await page.click('[data-testid="call-tool"]');
+
+  const error = await page.textContent('[data-testid="error-message"]');
+  expect(error).toBeTruthy();
+});
+```
+
+## What This Demonstrates
+
+- Using Playwright's `test` and `expect` from `@playwright/test` for browser E2E testing
+- Waiting for DOM elements with `waitForSelector` before asserting tool list counts
+- Filling form inputs and clicking buttons to simulate tool calls in the browser
+- Asserting tool results via `textContent` on result elements
+- Using the `.pw.spec.ts` file suffix required by FrontMCP naming conventions
+
+## Related
+
+- See `test-browser-build` for the full browser build testing reference
+- See `test-e2e-handler` for server-side E2E testing patterns

package/catalog/frontmcp-testing/examples/test-cli-binary/binary-startup-test.md

@@ -0,0 +1,77 @@
+---
+name: binary-startup-test
+reference: test-cli-binary
+level: basic
+description: 'Verify that a compiled CLI binary starts correctly and responds to health checks.'
+tags: [testing, cli, binary, startup]
+features:
+  - 'Using `execSync` to test that `--help` flag exits with code 0 and prints usage info'
+  - 'Spawning the binary as a child process with `PORT=0` for dynamic port assignment'
+  - 'Waiting for the "listening" log message before sending requests'
+  - 'Testing the `/health` endpoint for server readiness'
+  - 'Cleaning up the child process with `child.kill()`'
+---
+
+# Testing CLI Binary Startup and Health Check
+
+Verify that a compiled CLI binary starts correctly and responds to health checks.
+
+## Code
+
+```typescript
+// src/__tests__/cli-binary.spec.ts
+import { spawn, execSync } from 'child_process';
+import * as path from 'path';
+
+const BINARY = path.resolve(__dirname, '../dist/my-server');
+
+describe('CLI Binary', () => {
+  it('should exit with code 0 on --help', () => {
+    const output = execSync(`${BINARY} --help`, { encoding: 'utf-8' });
+    expect(output).toContain('Usage');
+  });
+
+  it('should start and respond to health check', async () => {
+    const child = spawn(BINARY, [], {
+      env: { ...process.env, PORT: '0' },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    // Wait for server to start and parse the actual port from stdout
+    const port = await new Promise<string>((resolve, reject) => {
+      const timeout = setTimeout(() => reject(new Error('Server did not start within 10s')), 10_000);
+      child.stdout.on('data', (data: Buffer) => {
+        const match = data.toString().match(/listening.*?:(\d+)/i);
+        if (match) {
+          clearTimeout(timeout);
+          resolve(match[1]);
+        }
+      });
+      child.on('error', (err) => {
+        clearTimeout(timeout);
+        reject(err);
+      });
+    });
+
+    try {
+      // Test health endpoint on the dynamically assigned port
+      const res = await fetch(`http://localhost:${port}/health`);
+      expect(res.ok).toBe(true);
+    } finally {
+      child.kill();
+    }
+  });
+});
+```
+
+## What This Demonstrates
+
+- Using `execSync` to test that `--help` flag exits with code 0 and prints usage info
+- Spawning the binary as a child process with `PORT=0` for dynamic port assignment
+- Waiting for the "listening" log message before sending requests
+- Testing the `/health` endpoint for server readiness
+- Cleaning up the child process with `child.kill()`
+
+## Related
+
+- See `test-cli-binary` for the full CLI binary testing reference