# How to Test Fastio MCP Server Tools with Playwright

Testing Fastio MCP server tools with Playwright lets developers verify AI agent integrations in a browser environment. Playwright handles authentication and network mocking. It interacts just like a real user or agent client. This approach catches issues in SSE streams and tool responses early. Expect step-by-step setup plus mocking examples and complete tests.

Source: https://fast.io/resources/testing-fastio-mcp-tools-playwright/
Last reviewed: 2026-02-24

## Why Test MCP Tools End-to-End?

Fastio's MCP server exposes multiple tools for file management via Streamable HTTP or SSE. Browser-based AI agents or web apps connect to handle uploads, queries, and shares. Real-world tests confirm these tools work under network conditions.

Playwright works great here. It runs Chromium, Firefox, and WebKit with good control over network requests. You can use it to mimic agent behavior, mock server responses, and verify results without flakiness.

Skip unit tests alone. They miss browser quirks like EventSource handling for SSE. E2E tests validate the full stack from client connect to tool execution.

Helpful references: [Fastio Workspaces](/product/workspaces/), [Fastio Collaboration](/product/collaboration/), and [Fastio AI](/product/ai/).

## What to check before scaling Testing Fastio MCP server tools with Playwright

Install Playwright in a new Node.js project.

```bash
npm init -y
npm i -D @playwright/test
npx playwright install
```

Create `playwright.config.ts`:

```typescript
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true.
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined.
  reporter: 'html',
  use: {
    baseURL: 'http://localhost:3000',  // Your MCP client app
    trace: 'on-first-retry',
  },
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
  ],
});
```

Run tests with `npx playwright test`.

### Mock MCP Server Locally

For offline testing, run a mock MCP server. Use `npx http-server` or tools like MSW for SSE simulation.

## Practical rollout checklist



## Handle Authentication in Tests

MCP requires auth via signup, signin, or API keys. Use Playwright's storage state for persistence.

Create `tests/auth.spec.ts`:

```typescript
import { test, expect } from '@playwright/test';

test('authenticate MCP', async ({ page, context }) => {
  await page.goto('/storage-for-agents/');
  // Simulate PKCE or API key setup
  await context.storageState({ path: 'playwright/.auth/mcp-state.json' });
});
```

Load state in config: `storageState: 'playwright/.auth/mcp-state.json'`.

For API keys, set headers in context:

```typescript
const context = await browser.newContext({
  extraHTTPHeaders: { 'Authorization': `Bearer ${apiKey}` }
});
```

## Mock and Intercept SSE Streams

MCP's SSE transport sends tool responses as events. Mock with Playwright routes.

Intercept SSE:

```typescript
await page.route('/storage-for-agents/', async route => {
  const sseResponse = `data: ${JSON.stringify(mockToolResponse)}

`;
  await route.fulfill({
    status: 200,
    headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' },
    body: sseResponse
  });
});
```

For Streamable HTTP (/mcp), mock POST responses:

```typescript
await page.route('**/mcp', async route => {
  await route.fulfill({ json: mockToolResult });
});
```

Many guides overlook SSE mocking details.

## Write End-to-End Test Examples

Test listing workspaces:

```typescript
test('list MCP workspaces', async ({ page }) => {
  await page.goto('/your-mcp-client');
  await expect(page.locator('[data-testid=workspace-list]')).toHaveText(/My Workspace/);
});
```

Test file upload via MCP tool:

```typescript
test('upload file with MCP', async ({ page }) => {
  await page.route('**/upload', route => route.fulfill({ json: { nodeId: 'mock-node' } }));
  await page.getByTestId('file-upload').setInputFiles('test.pdf');
  await expect(page.locator('[data-testid=upload-success]')).toBeVisible();
});
```

Assert tool responses match expected JSON schemas.

## works alongside CI/CD and Best Practices

In GitHub Actions, cache Playwright:

```yaml
- uses: actions/setup-node@v4
  with:
    node-version: 20
- run: npm ci
- uses: browser-actions/setup-playwright@v1
  with:
    playwright-version: multiple.42.0
- run: npx playwright test
```

Best practices:
* Use traces for debugging: `trace: 'retain-on-failure'`
* Mock external deps to avoid flakes.
* Parallelize with shards.
* Video record failures.

Capture these lessons in a shared runbook so new contributors can follow the same process. Consistency reduces regression risk and makes troubleshooting faster.

## Frequently asked questions

### How do I mock MCP servers in Playwright?

Use page.route() to intercept SSE or HTTP endpoints. Fulfill with mock JSON events matching MCP schema. See the SSE example above for text/event-stream headers.

### Can I test AI agents with Playwright?

Yes. Launch browser, inject agent script, trigger MCP tool calls, and assert DOM changes or network payloads. Mock server for offline runs.

### What about WebSocket mocks?

MCP uses SSE, not WS. For WS, use page.routeWebSocket().

### How to handle auth tokens?

Persist with context.storageState(). Use API keys in extraHTTPHeaders for stateless tests.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.