Skip to main content

​
Canonical resources

For new integrations, prefer client.testRuns, client.tests, client.sandboxRuns, and client.twinRuns.

​
Create an ad hoc test run

const run = await client.testRuns.create({
  prompt: 'Test the checkout flow',
  startUrl: 'https://staging.myapp.com',
  twins: ['stripe', 'slack'],   // optional
  repo: 'myorg/myrepo',         // optional
  branch: 'feature/checkout',   // optional
});

const detail = await client.testRuns.wait(run.id, { timeout: 300000 });
console.log(detail.status);
List, inspect, or rerun test runs: 
const runs = await client.testRuns.list();
const detail = await client.testRuns.get('run-id');
const rerun = await client.testRuns.rerun('run-id');

​
Create a sandbox run

const sandbox = await client.sandboxRuns.create({
  repo: 'myorg/myrepo',
  branch: 'feature/checkout',
  twins: ['stripe', 'slack'],
  ttlMinutes: 60,
});

const detail = await client.sandboxRuns.get(sandbox.sandboxId);
const logs = await client.sandboxRuns.logs(sandbox.sandboxId);

​
Create a twin run

const result = await client.twinRuns.create({
  twins: ['stripe', 'slack'],
  ttlMinutes: 60,
  scenarioId: 'scenario-id',  // optional
});

const status = await client.twinRuns.get(result.runId);
await client.twinRuns.extend(result.runId, { ttlMinutes: 30 });
await client.twinRuns.lock(result.runId);
await client.twinRuns.teardown(result.runId);

​
Run a saved test

const tests = await client.tests.list({ repoFullName: 'myorg/myrepo' });
const test = await client.tests.get('test-id');
const run = await client.tests.run('test-id', { startUrl: 'https://staging.myapp.com' });

​
Legacy validation runs

Test a live URL with browser validation and optional digital twins. 
const run = await client.runs.createUrlRun({
  url: 'https://staging.myapp.com',
  prompt: 'Test the checkout flow',                          // optional
  twins: ['stripe', 'slack'],                                // optional
  credentials: { email: 'test@example.com', password: 'pass' },  // optional
  runnerMode: 'visual',                                      // optional
  sessionId: 'abc-123',                                      // optional
});
// run.runId, run.status, run.sessionId

​
Create a PR run

Validate code changes from a branch or pull request. 
const run = await client.runs.createPrRun({
  repo: 'myorg/myrepo',
  branch: 'feature/checkout',                                // optional
  prUrl: 'https://github.com/org/repo/pull/42',              // optional
  twins: ['stripe'],                                         // optional
  contextNotes: 'Changed the payment flow',                  // optional
  scenarioPrompt: 'Customer with active subscription',       // optional
});

​
Agent run migration

The current package still exposes client.runs.createAgentRun(...), but it targets the removed /validate/agent-run endpoint. Use client.runs.createUrlRun(...) for deployed URLs, client.runs.createPrRun(...) for normal PR validation, or call POST /validate/pr-run with run_type: "agent_run" when you need a sandbox-style branch run.

​
Get run details

const detail = await client.runs.get('run-id');
console.log(detail.status);         // "completed", "running", "failed", etc.
console.log(detail.resultsJson);    // step results array
console.log(detail.stepSummaries);  // grouped summaries
console.log(detail.eventLogJson);   // timeline events

​
Stream results

Stream live results via server-sent events: 
for await (const event of client.runs.streamResults('run-id')) {
  console.log(event);
}

​
Wait for completion

Block until the run reaches a terminal status (completed, failed, or cancelled): 
const detail = await client.runs.wait('run-id', {
  pollInterval: 2500,  // ms between polls (default 2500)
  timeout: 600000,     // max ms to wait (default 600000)
});

​
Cancel a run

await client.runs.cancel('run-id');
client.runs is the legacy namespace over /validate/... and /runs/.... New work should prefer client.testRuns, client.tests, client.sandboxRuns, and client.twinRuns.