Testmo API Update: Analytics, Reporting & Integrations

We are announcing a major update for Testmo's REST API today that introduces many new endpoints to access and read Testmo's major entities, making it easier to implement custom integrations, analytics use cases and custom reporting.

Testmo's existing API (and tooling) already makes it very easy to integrate test automation and submit results from any automation tool. Today's API update focuses on additional read endpoints to access Testmo's data so you can query it for custom integrations, display results in internal dashboard tools, run custom reports, retrieve data during CI pipeline runs & more.

Introducing new REST API Endpoints
Accessing & Using Testmo's REST API
Testmo REST API Examples
Analytics Integration & Custom Reporting
Summary & Future API Plans

Start Testing with Testmo Free

#1 Unified Modern Test Management Software

Start Free Trial See All Features

Introducing new REST API Endpoints

Testmo's new API endpoints make it easy to access & read data from your Testmo projects so you can query your milestones, test runs, sessions & automation runs along with their metrics and statistics. See below for an overview of new API categories and links to our updated API documentation with more details.

Projects: Get one or multiple/all projects from your Testmo instance along with useful metrics and statistics for your projects. The projects are always returned for the current user context accessing the API.
Milestones: Get the details for one milestone or all milestones of a project, optionally including the milestone statistics for linked test runs and sessions.
Runs: Retrieve the test runs of a project. Get a single test run or all active or closed runs, along with aggregated statistics and test numbers of your runs.
Sessions: Retrieve the exploratory test sessions of a project. Get a single session or all active or closed sessions, along with result statistics of the session notes.
Automation Runs: Get one or all automation runs for your projects, including aggregated statistics of the test results and the overall test run status.
Automation Sources: Query the details of the test automation sources of your projects, including average & aggregated source statistics and metrics.
Users: Retrieve details about users in your Testmo instance. The API provides endpoints for regular users, and extended endpoints for site admins.
Groups: Query details about user groups in your Testmo instance. These API endpoints are limited to site admins.
Roles: Query details about user roles in your Testmo instance. These API endpoints are limited to site admins.

Accessing & Using Testmo's REST API

Testmo's REST API is easy to access from many tools, platforms, programming languages and reporting tools, as it's a standard HTTP API that follows many common best practices. So if you are already familiar with using REST APIs, you will be able to get up and running with Testmo's API quickly.

In this section we are looking at the different options on how to use the API, as well as explaining some additional concepts that are useful to understand when working with our API.

Using the HTTP API directly

Testmo's REST API is easy to use with any tool or programming language via simple HTTP requests. The following example uses the popular curl command line tool to access the new /projects endpoint to list all projects for the current user. Make sure to generate an API key from your profile page in Testmo to use the API. Testmo returns all results as standard JSON responses. Please refer to the API documentation for all supported parameters.

# Set API token and use `curl` get all projects
$ TESTMO_TOKEN=********
$ curl -H "Authorization: Bearer $TESTMO_TOKEN" \
	https://<testmo-name>.testmo.net/api/v1/projects

# Response returned by Testmo
{
    "page": 1,
    "prev_page": null,
    "next_page": 2,
    "last_page": 2,
    "per_page": 100,
    "total": 150,
    "result": [
        {
            "id": 1,
            "name": "Spotlight",
            "note": null,
            "is_completed": true,
            "milestone_count": 10,
            "milestone_active_count": 3,
            "milestone_completed_count": 7,
            ..
            "created_at": "..",
            "created_by": 2,
            "updated_at": null,
            "updated_by": null,
            "completed_at": ".."
        },
        ..
    ],
    "expands": {
        ..
    }
}

Testmo's REST API is easy to use with standard HTTP libraries and tools

Node.js & JavaScript package

You can use Testmo's API with any tool and from any programming language by using simple HTTP requests. We also maintain the official Node.js @testmo/testmo-api package as a convenient wrapper of the API to make it a bit easier to use the API from Node.js / JavaScript projects (generated from our OpenAPI schema, see below).

We use this package ourselves for Testmo's test automation CLI tool, so it's always up-to-date. If you use Node.js in your projects, it's easy to get started with this package:

# Install the package for your project
npm install @testmo/testmo-api

// A simple script that uses the testmo-api package to retrieve all projects.
// Make sure to set the environment variables for the Testmo address & API token.
var testmo = require('@testmo/testmo-api');

// Configure API client
const client = new testmo.ApiClient();
client.basePath = process.env.TESTMO_HOST;
client.authentications['bearerAuth'].accessToken = process.env.TESTMO_TOKEN;

// Retrieve active projects for the current user
const api = new testmo.ProjectsApi(client);
const page = await api.getProjectPage({
  page: 1,
  perPage: 100,
  sort: 'projects:created_at',
  order: 'desc',
  isCompleted: 0,
  expands: 'users'
 });

console.log(page);

You can use the official @testmo/testmo-api package in Node.js projects

OpenAPI schema definition

We also maintain an OpenAPI schema definition for Testmo's REST API (often also referred to as Swagger specification).

Many tools support OpenAPI schema definitions so you can import or load the definition to make it easier to discover supported API endpoints, parameters and response fields.

Download the OpenAPI schema

If you would like to use the OpenAPI schema to import or load it into your API or reporting tool, please refer to Testmo's OpenAPI schema page.

Pagination, filters & expands

Our goal is to make the API as easy to use as possible and to support typical use cases efficiently, so we have thought a lot about how to handle pagination, filtering and how to retrieve additional relevant meta information with the responses. We also reviewed many popular APIs to adopt best practices and combine the best ideas from established APIs for Testmo.

Pagination: All our list API methods have pagination built in, so when you retrieve e.g. a list of projects, or runs, or milestones, the results are returned in pages, so you can easily retrieve a large number of entries by requesting additional pages. All API endpoints that use pagination support a common set of parameters that you can use to specify the entries per page & the page to retrieve.
Filters: Many of our list API methods support useful filters so you can retrieve exactly the entries you are interested in. For example, you might only want to retrieve automation runs for a specific milestone, which were run against a specific configuration, and only the runs that failed and were started this week. Testmo's API makes this and similar requests very easy.
Expands: We have adopted the concept of expands for the Testmo API, which allows you to retrieve related meta information and fields in responses without having to send additional API requests.

Example: If you are retrieving a list of test runs, you might also want information about the milestones the runs are linked to (e.g. to display the runs & their milestones in a list). You can simply tell Testmo to expand the milestone details, and Testmo will automatically include details about all milestones relevant for the runs in the response. Make sure to check out the various examples in the next section.

Testmo REST API Examples

The following API examples show various typical use cases to query and retrieve data from your Testmo projects. To see the full responses for the queries, we encourage you to try the API yourself. All you need is a Testmo account (a trial account is sufficient), a Testmo API key and an HTTP tool (such as curl). Also make sure to review our API documentation for more examples for the various API endpoints.

Projects

// Get the project with ID 5 and include user details
GET /api/v1/projects/5?expands=users

// Get latest 100 active projects
GET /api/v1/projects?is_completed=0

// Get latest 100 completed projects, ordered by completion date
GET /api/v1/projects?is_completed=1&sort=projects:completed_at

Milestones

// Get the milestone with ID 3 and include expands
GET /api/v1/milestones/3?expands=issues,milestone_types,users

// Get latest 100 milestones for project with ID 5
GET /api/v1/projects/5/milestones

// Get latest milestones created after a certain date & time
GET /api/v1/projects/5/milestones?created_after=2023-02-15T00:00:00.000Z

// Get milestones and include expands
GET /api/v1/projects/5/milestones?expands=issues,milestone_types,users

Runs & sessions

// Get a run or session and include expands
GET /api/v1/runs/1?expands=configs,issues,users
GET /api/v1/sessions/1?expands=configs,issues,users

// Get latest 100 active runs or sessions for project with ID 5
GET /api/v1/projects/5/runs?is_closed=0
GET /api/v1/projects/5/sessions?is_closed=0

// Get latest 100 closed runs, ordered by close date
GET /api/v1/projects/5/runs?is_closed=1&sort=runs:closed_at

// Get latest sessions created after a certain date & time
GET /api/v1/projects/5/sessions?created_after=2023-02-15T00:00:00.000Z

// Get runs or sessions and include expands
GET /api/v1/projects/5/runs?expands=configs,issues,users
GET /api/v1/projects/5/sessions?expands=configs,issues,users

Automation

// Get the automation run with ID 5 and include expands
GET /api/v1/automation/runs/5?expands=automation_sources,configs,users

// Get latest 15 failed automation runs for project with ID 5
GET /api/v1/projects/5/automation/runs?state=3&per_page=15

// Get automation runs and include expands
GET /api/v1/projects/5/automation/runs?expands=automation_sources,configs,users

// Get the automation source with ID 7
GET /api/v1/automation/sources/7

// Get latest 100 active automation sources and include user details
GET /api/v1/projects/5/automation/sources?is_retired=0&expands=users

Analytics, Dasboards & Custom Integrations

We've also designed and tested Testmo's extended API to work well with third-party analytics, business intelligence and custom dashboard reporting tools. This allows you to easily integrate your testing activities stored and managed in Testmo with your existing internal dashboards and reports. This includes common uses cases such as:

Internal dashboards: If your company maintains internal dashboards with important KPIs, you can now use Testmo's extended API to display & integrate your test related metrics together with other sources.
Business intelligence: Testmo's extended API can also be used to query information and combine your testing metrics with data points retrieved from other tools (such as issue trackers) in business intelligence tools.
Custom reporting: If you maintain custom reports for your development, testing and DevOps processes, you can now also include your Testmo data by querying our new API endpoints.
CI pipelines: The new API endpoints also allow for additional custom integrations from your CI pipelines, such as requesting the full statistics of test automation runs you've submitted during the CI run.
User directory auditing: Testmo's new user and group APIs can als be used for additional user auditing and verification with company user directories, registries and permission assignments.

Example dashboard integration using Testmo's extended API in a third-party reporting tool

Summary & Future API Plans

Testmo's new extended REST API with all new endpoints is now live for all Testmo accounts. You can also review our updated API documentation and we've released version 2.0 of our @testmo/testmo-api package with support for the latest API schema. If you aren't using Testmo yet, you can also register a free Testmo trial to get started.

We also plan to review supporting additional API endpoints in the future to retrieve and manage data in Testmo. Additionally, we have various other API, integration & reporting features in the pipeline, so stay tuned. If you are interested in specific additional API endpoints or integration features, please let us know.

PS: We regularly publish original software testing & QA research, including free guides, reports and news. To receive our next postings, you can subscribe to updates. You can also follow us on Twitter and Linkedin.