Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TestRail
✓ import { TestRail } from 'testrail-js-api';
✗ const TestRail = require('testrail-js-api');
The TestRail class is the primary named export for ESM and TypeScript usage. CommonJS users often incorrectly assign the entire module.exports object when a named export is expected.
AddRunPayload
✓ import type { AddRunPayload } from 'testrail-js-api';
✗ import { AddRunPayload } from 'testrail-js-api';
Type imports like `AddRunPayload` should ideally use `import type` for better tree-shaking and clear distinction between runtime values and compile-time types in TypeScript.
TestRailResponse
✓ import type { TestRailResponse } from 'testrail-js-api';
The library methods return a promise that resolves to an object with `response` and `value` properties. `TestRailResponse` is an example of a type that defines this structure.
Demonstrates how to instantiate the TestRail client, create a new test run, and add a test result for a specific test case, including basic error handling.
import { TestRail, AddRunPayload } from 'testrail-js-api';
const host = process.env.TESTRAIL_HOST ?? 'https://your-testrail.com';
const user = process.env.TESTRAIL_USER ?? 'your_username';
const apiKey = process.env.TESTRAIL_API_KEY ?? 'your_api_key';
async function createTestRunAndAddResult() {
const testrail = new TestRail(host, user, apiKey);
const projectId = 1; // Replace with your TestRail Project ID
try {
const runPayload: AddRunPayload = {
suite_id: 2, // Replace with your Test Suite ID
name: `Automated Test Run - ${new Date().toISOString()}`,
description: 'Test run created via testrail-js-api',
include_all: true,
};
console.log('Creating new test run...');
const { value: run } = await testrail.addRun(projectId, runPayload);
console.log(`Test Run created: ID ${run?.id}, URL: ${run?.url}`);
if (run?.id) {
// Example: Add a passing result to a test case in the new run
const testCaseId = 3; // Replace with a Test Case ID from your suite
const resultPayload = { status_id: 1, comment: 'Test passed successfully via API.' }; // 1 for Passed
console.log(`Adding result to Test Case ${testCaseId} in Run ${run.id}...`);
await testrail.addResultForCase(run.id, testCaseId, resultPayload);
console.log(`Result added for Test Case ${testCaseId}.`);
}
} catch (error: any) {
console.error('An error occurred:', error.message);
if (error.response?.data) {
console.error('TestRail API Error Details:', error.response.data);
}
}
}
createTestRunAndAddResult();
Errors
Common errors & fixes
TestRail API Error: Authentication failed or Access denied
Incorrect TestRail host URL, invalid username, or an expired/wrong API key used during client initialization. The user may also lack API access permissions.
fixVerify the `host`, `user`, and `apiKey` credentials against your TestRail site settings. Ensure the user account has 'API access' enabled and correct project permissions.
TestRail API Error: The requested resource does not exist or you do not have the permissions to access it.
An invalid ID (e.g., project ID, suite ID, run ID, case ID) was provided for an API call, or the authenticated user lacks necessary permissions for the specific resource or action.
fixDouble-check all IDs passed to API methods for correctness. Confirm the API user has sufficient permissions within TestRail for the target project and the operations being attempted.
TypeError: testrail.addRun is not a function
The `TestRail` constructor was not properly imported or instantiated. This often happens in CommonJS when attempting `const { TestRail } = require('testrail-js-api')` if `TestRail` is the default export, or `const TestRail = require('testrail-js-api')` if it's a named export.
fixFor ESM/TypeScript, use `import { TestRail } from 'testrail-js-api';`. For CommonJS, use `const { TestRail } = require('testrail-js-api');` and then `new TestRail(...)`. Audit
Dependencies
No dependency data recorded yet.