testmo-api-client

Testmo API Client

Official TypeScript SDK for the Testmo API. Manage automation runs, threads, and test results programmatically.

Installation

npm install testmo-api-client

Quick Start

import { TestmoClient } from 'testmo-api-client';

const client = new TestmoClient({
  baseUrl: 'https://your-org.testmo.net',
  apiToken: process.env.TESTMO_API_TOKEN!
});

// Create an automation run
const { id: runId } = await client.automationRuns.create(projectId, {
  name: 'CI Build #123',
  source: 'backend',
  tags: ['nightly', 'regression']
});

// Create a thread and submit test results
const { id: threadId } = await client.threads.create(runId);

await client.threads.append(threadId, {
  tests: [
    { name: 'test_login', status: 'passed', elapsed: 1500000 },
    { name: 'test_checkout', status: 'failed', fields: [
      { name: 'Error', type: 4, value: 'Timeout', is_highlight: true }
    ]}
  ]
});

// Complete thread and run
await client.threads.complete(threadId);
await client.automationRuns.complete(runId, { measure_elapsed: true });

API Reference

TestmoClient

new TestmoClient({
  baseUrl: string,     // Your Testmo instance URL
  apiToken: string,    // API token for authentication
  timeout?: number     // Request timeout in ms (default: 30000)
})

Automation Runs

List runs

const runs = await client.automationRuns.list(projectId, {
  page: 1,
  per_page: 100,
  status: '3',           // Filter by status (2=success, 3=failure, 4=running)
  created_after: '2024-01-01T00:00:00.000Z',
  expands: 'automation_sources,configs,users'
});

Get a run

const run = await client.automationRuns.get(runId, {
  expands: 'automation_sources,users'
});

Create a run

const { id } = await client.automationRuns.create(projectId, {
  name: 'Run Name',
  source: 'frontend',     // Auto-created if doesn't exist
  config: 'Chrome',       // Optional configuration
  milestone: 'v2.0',      // Optional milestone
  tags: ['smoke', 'ci'],
  artifacts: [{
    name: 'build-log.txt',
    url: 'https://storage.example.com/logs/build.txt',
    mime_type: 'text/plain',
    size: 1024
  }],
  fields: [{
    name: 'Build Number',
    type: 1,
    value: '12345'
  }],
  links: [{
    name: 'CI Build',
    url: 'https://ci.example.com/build/123'
  }]
});

Append to a run

await client.automationRuns.append(runId, {
  artifacts: [{ name: 'log.txt', url: 'https://...' }],
  fields: [{ name: 'Duration', type: 1, value: '5m' }],
  links: [{ name: 'Report', url: 'https://...' }]
});

Complete a run

await client.automationRuns.complete(runId, {
  measure_elapsed: true  // Auto-calculate execution time
});

Threads

Create a thread

const { id: threadId } = await client.threads.create(runId, {
  elapsed_observed: 600000000,  // 10 minutes in microseconds
  artifacts: [{ name: 'thread-log.txt', url: 'https://...' }]
});

Submit test results

await client.threads.append(threadId, {
  elapsed_observed: 120000000,
  tests: [
    {
      key: 'unique-test-hash',      // Optional unique identifier
      name: 'test_user_creation',
      folder: 'Users',
      status: 'passed',
      elapsed: 60000000,            // Microseconds
      file: 'users.test.js',
      line: 100,
      assertions: 5,
      artifacts: [{
        name: 'screenshot.png',
        url: 'https://storage.example.com/screenshot.png'
      }]
    },
    {
      name: 'test_user_deletion',
      folder: 'Users', 
      status: 'failed',
      fields: [{
        name: 'Error',
        type: 4,
        value: 'AssertionError: expected 200 but got 500',
        meta: { type: 'AssertionError' },
        is_highlight: true
      }]
    }
  ]
});

Complete a thread

await client.threads.complete(threadId, {
  elapsed_observed: 600000000,
  elapsed_computed: 580000000
});

Error Handling

import { TestmoApiError, TestmoNetworkError, TestmoConfigError } from 'testmo-api-client';

try {
  await client.automationRuns.get(999999);
} catch (error) {
  if (error instanceof TestmoApiError) {
    console.error(`API Error: ${error.statusCode} - ${error.message}`);
    console.error('Response:', error.response);
  } else if (error instanceof TestmoNetworkError) {
    console.error(`Network Error: ${error.message}`);
  } else if (error instanceof TestmoConfigError) {
    console.error(`Config Error: ${error.message}`);
  }
}

Types

All TypeScript types are exported for your convenience:

import type {
  AutomationRun,
  TestResult,
  Artifact,
  Field,
  Link,
  PaginatedResponse,
  CreateAutomationRunParams,
  AppendToThreadParams,
} from 'testmo-api-client';

Field Types

Type	Description
1	String
2	Integer
3	Boolean
4	Text/Multiline

Test Status Values

Status	Description
2	Success
3	Failure
4	Running

Requirements

• Node.js >= 18.0.0 (uses native fetch)

License

MIT © MAkhamis