> ## Documentation Index
> Fetch the complete documentation index at: https://sunpeak.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Add automated testing to any MCP server in under five minutes.

## Prerequisites

* **Node.js 20+** is required, even if your MCP server is written in Python, Go, or another language. The testing framework runs on Node.js and Playwright.
* Your MCP server running locally (HTTP or stdio)

## 1. Try the inspector (optional)

Before writing tests, try the inspector to verify sunpeak can connect to your server:

<Tabs>
  <Tab title="HTTP server">
    ```bash theme={null}
    npx sunpeak inspect --server http://localhost:8000/mcp
    ```
  </Tab>

  <Tab title="Python (stdio)">
    ```bash theme={null}
    npx sunpeak inspect --server "python server.py"

    # With uv:
    npx sunpeak inspect --server "uv run python server.py"
    ```
  </Tab>

  <Tab title="Go (stdio)">
    ```bash theme={null}
    npx sunpeak inspect --server "go run ./cmd/server"
    ```
  </Tab>

  <Tab title="Node.js (stdio)">
    ```bash theme={null}
    npx sunpeak inspect --server "node server.js"
    ```
  </Tab>
</Tabs>

This opens the inspector at `http://localhost:3000`, where you can call your tools and see them rendered in simulated ChatGPT and Claude runtimes. Browse your tools, switch hosts and themes, and verify everything connects.

## 2. Scaffold test infrastructure

Once the inspector works, scaffold automated tests:

```bash theme={null}
npx sunpeak test init --server http://localhost:8000/mcp
```

Or with a stdio command:

```bash theme={null}
npx sunpeak test init --server "python server.py"
```

This creates test files for all four testing levels. For non-JS projects, everything goes into a self-contained `tests/sunpeak/` directory with its own `package.json`.

Install dependencies:

<Tabs>
  <Tab title="Non-JS project">
    ```bash theme={null}
    cd tests/sunpeak
    npm install
    npx playwright install chromium
    ```
  </Tab>

  <Tab title="JS/TS project">
    ```bash theme={null}
    npm add -D sunpeak @playwright/test
    npx playwright install chromium
    ```
  </Tab>
</Tabs>

## 3. Run the smoke test

```bash theme={null}
npx sunpeak test
```

For non-JS projects, `sunpeak test` auto-discovers `tests/sunpeak/playwright.config.ts` when no root-level config exists. You can run it from your project root without cd-ing into the test directory.

The scaffolded smoke test verifies that the inspector can connect to your server and load. You should see one passing test.

## 4. Write your first real test

Open the scaffolded smoke test (`smoke.test.ts`) and add a test for one of your tools. Replace `your-tool` with an actual tool name from your server:

```typescript theme={null}
import { test, expect } from 'sunpeak/test';

test('server is reachable and inspector loads', async ({ inspector }) => {
  await expect(inspector.page.locator('#root')).not.toBeEmpty();
});

test('my tool returns a result', async ({ mcp }) => {
  const result = await mcp.callTool('your-tool', { key: 'value' });
  expect(result.isError).toBeFalsy();
});

// If your tool renders a UI, you can interact with it:
test('my tool renders a UI', async ({ inspector }) => {
  const result = await inspector.renderTool('your-tool', { key: 'value' });
  const app = result.app();
  await expect(app.getByText('Expected text')).toBeVisible();
});
```

The `mcp` and `inspector` fixtures handle all the plumbing: starting the inspector, connecting to your server, navigating to the tool, and traversing the double-iframe sandbox. Each test runs automatically against both ChatGPT and Claude hosts.

There are two fixtures: `mcp` for protocol-level testing (`callTool`, `listTools`, etc., returning raw MCP data) and `inspector` for UI testing (`renderTool`, which renders the result in the inspector). When you pass `input` to `renderTool`, the tool is called on your real server and the result is rendered. Without `input`, the tool uses pre-baked simulation fixture data (if available) for fast, deterministic tests. See [Simulations](/testing/simulations#simulations-vs-real-server-calls) for more on when to use each approach.

<Tip>
  Run `npx sunpeak inspect --server <url>` to browse your tools interactively and find the right tool names and arguments to use in tests.
</Tip>

## 5. Add more test levels

The scaffolded files include templates for all four testing levels:

| Level      | File                    | Command                 | Cost         |
| ---------- | ----------------------- | ----------------------- | ------------ |
| **E2E**    | `smoke.test.ts`         | `sunpeak test`          | Free         |
| **Visual** | `visual.test.ts`        | `sunpeak test --visual` | Free         |
| **Live**   | `live/example.test.ts`  | `sunpeak test --live`   | Host credits |
| **Evals**  | `evals/example.eval.ts` | `sunpeak test --eval`   | API keys     |

Start with E2E tests (free, fast, local). Add visual regression when you want to catch CSS regressions. Add live tests and evals when you need production host validation and multi-model reliability testing.

## Language-specific tips

<AccordionGroup>
  <Accordion title="Python">
    For stdio servers, pass the full command including any virtual environment activation:

    ```typescript theme={null}
    // playwright.config.ts
    import { defineConfig } from 'sunpeak/test/config';
    export default defineConfig({
      server: {
        // Option 1: uv (recommended)
        command: 'uv', args: ['run', 'python', 'server.py'],

        // Option 2: venv absolute path
        // command: '.venv/bin/python', args: ['server.py'],

        // Option 3: HTTP server (no shell needed)
        // url: 'http://localhost:8000/mcp',

        // Pass environment variables to the server process
        env: { PYTHONPATH: './src', DATABASE_URL: 'sqlite:///test.db' },

        // Set the working directory
        cwd: './my-python-server',
      },
    });
    ```

    HTTP servers (FastAPI, Flask) are the simplest option because you start them separately and sunpeak just connects to the URL.
  </Accordion>

  <Accordion title="Go">
    ```typescript theme={null}
    import { defineConfig } from 'sunpeak/test/config';
    export default defineConfig({
      server: {
        command: 'go', args: ['run', './cmd/server'],
        env: { GO_ENV: 'test' },

        // Or connect to a running HTTP server:
        // url: 'http://localhost:8000/mcp',
      },
    });
    ```
  </Accordion>

  <Accordion title="Rust">
    ```typescript theme={null}
    import { defineConfig } from 'sunpeak/test/config';
    export default defineConfig({
      server: {
        command: 'cargo', args: ['run', '--release'],
        // url: 'http://localhost:8000/mcp',
      },
    });
    ```
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card horizontal title="E2E Testing" icon="flask" href="/testing/e2e">
    Write Playwright tests against simulated hosts.
  </Card>

  <Card horizontal title="Visual Regression" icon="image" href="/testing/visual">
    Screenshot comparison across themes and hosts.
  </Card>

  <Card horizontal title="Live Testing" icon="globe" href="/testing/live">
    Test against real ChatGPT and Claude.
  </Card>

  <Card horizontal title="Evals" icon="chart-bar" href="/testing/evals">
    Multi-model tool calling reliability.
  </Card>
</CardGroup>