Documentation

SDK Setup

Install the SimuTest SDK and run tests against any server — including localhost.

Prerequisites

Before installing, make sure you have:

Requirement	Version	Notes
Node.js	18+	Required for the Node.js SDK
Python	3.9+	Required for the Python SDK
SimuTest account	—	Sign up at app.simutest.dev
API key	—	See the next section

Get Your API Key

To authenticate SDK requests, you need an API key with the tests:write scope.

Go to your Dashboard → Settings → API Keys
Click Create key
Give your key a name (e.g., local-dev) and select the tests:write scope
Copy the key — it won't be shown again

Keep your API key secret. Never commit it to source control. Use environment variables or a secrets manager instead.

Install the SDK

Install the Node.js SDK via npm:

npm install @simutest/sdk

Or install the Python SDK via pip:

pip install simutest

Your First Local Test

The SDK connects SimuTest's AI sessions directly to any reachable server — including localhost. This makes it easy to test before deploying.

Node.js example:

import { SimuTest } from '@simutest/sdk';

const client = new SimuTest({
  apiKey: process.env.SIMUTEST_API_KEY,
});

async function main() {
  const test = await client.tests.create({
    url: 'http://localhost:3000',
    task: 'Find the pricing page and sign up for the Pro plan',
    sessions: 20,
    model: 'claude-sonnet',
    viewport: ['desktop', 'mobile'],
  });

  console.log(`Test started: ${test.id}`);

  // Stream results as sessions complete
  for await (const event of client.tests.stream(test.id)) {
    if (event.type === 'session.completed') {
      console.log(`Session ${event.session.index}: ${event.session.outcome}`);
    }
    if (event.type === 'test.completed') {
      console.log('\nTest complete!');
      console.log(`Score: ${event.report.score}/100`);
      console.log(`Completion rate: ${event.report.completionRate}%`);
    }
  }
}

main();

Python equivalent:

import asyncio
import os
from simutest import SimuTest

client = SimuTest(api_key=os.environ["SIMUTEST_API_KEY"])

async def main():
    test = await client.tests.create(
        url="http://localhost:3000",
        task="Find the pricing page and sign up for the Pro plan",
        sessions=20,
        model="claude-sonnet",
        viewport=["desktop", "mobile"],
    )

    print(f"Test started: {test.id}")

    async for event in client.tests.stream(test.id):
        if event.type == "session.completed":
            print(f"Session {event.session.index}: {event.session.outcome}")
        if event.type == "test.completed":
            print("\nTest complete!")
            print(f"Score: {event.report.score}/100")
            print(f"Completion rate: {event.report.completion_rate}%")

asyncio.run(main())

Understanding Results

When a test completes, the test.completed event includes a full report object. Here's what each field means:

Field	Type	Description
report.score	number (0–100)	Composite UX score weighted across completion rate, time-on-task, and error frequency
report.completionRate	number (0–100)	Percentage of sessions that completed the task successfully
report.sessions	Session[]	Array of individual session results with outcome, duration, and interaction timeline
report.thinkingTraces	ThinkingTrace[]	Key moments from AI reasoning — confusion signals, decision points, and abandonment triggers
report.issues	Issue[]	Ranked list of UX problems with severity, affected session count, and suggested fixes

For the full type definitions, see the Node.js SDK reference or Python SDK reference.

Using Environment Variables

Store your API key in a .env file and load it with your preferred dotenv library. Both the Node.js and Python SDKs also auto-read the SIMUTEST_API_KEY environment variable if no apiKey is passed to the constructor.

# .env
SIMUTEST_API_KEY=sk-simu-your-api-key-here

Add .env to your .gitignore to avoid accidentally committing your key.

On this page