Registry / testing / testrail-api-client

testrail-api-client

JSON →
library1.0.37jsnpmunverified

The `testrail-api-client` package provides a JavaScript and TypeScript binding for the TestRail API v2, enabling programmatic interaction with a TestRail instance. Currently at version 1.0.37, it sees frequent patch releases for bug fixes and dependency updates, notably for `axios`. This client differentiates itself through its explicit support for both CommonJS and ES module environments, though documentation leans towards CommonJS. It also offers convenient auto-configuration via environment variables. The library streamlines common TestRail operations such as creating and closing test runs, retrieving test cases and results, and adding results, making it suitable for integrating with automated testing workflows.

npm install testrail-api-client
INSTALL
IMPORT
SIG · TESTRAIL-API-CLIEN
T
testrail-api-client
testingjavascriptv1.0.37
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

TestRailClient
import TestRailClient from 'testrail-api-client';
import { TestRailClient } from 'testrail-api-client';
The primary client constructor is exported as the default in ESM, not a named export. Use for creating a new client with custom options.
TestRailClient (CommonJS Constructor)
const TestRailClient = require('testrail-api-client').default;
const TestRailClient = require('testrail-api-client');
When using CommonJS, access the client constructor via the `.default` property for passing custom configuration options.
Client (Pre-configured/Factory)
const client = require('testrail-api-client');
const client = new require('testrail-api-client')();
This import pattern is commonly used with CommonJS when environment variables (TESTRAIL_DOMAIN, TESTRAIL_USERNAME, TESTRAIL_APIKEY/TESTRAIL_PASSWORD) are set, providing an already configured client instance.

This quickstart demonstrates how to initialize the TestRail client using environment variables and then perform common actions like creating a test run and adding results for specific test cases.

import TestRailClient from 'testrail-api-client'; // Configure client using environment variables or direct options const TESTRAIL_DOMAIN = process.env.TESTRAIL_DOMAIN ?? ''; const TESTRAIL_USERNAME = process.env.TESTRAIL_USERNAME ?? ''; const TESTRAIL_APIKEY = process.env.TESTRAIL_APIKEY ?? ''; // or TESTRAIL_PASSWORD if (!TESTRAIL_DOMAIN || !TESTRAIL_USERNAME || !TESTRAIL_APIKEY) { console.error('Missing TestRail environment variables: TESTRAIL_DOMAIN, TESTRAIL_USERNAME, TESTRAIL_APIKEY/TESTRAIL_PASSWORD'); process.exit(1); } const client = new TestRailClient({ domain: TESTRAIL_DOMAIN, username: TESTRAIL_USERNAME, password: TESTRAIL_APIKEY // TestRail often uses API Key as 'password' for programmatic access }); const projectId = 1; // Replace with your TestRail project ID const runName = 'Automated Test Run ' + new Date().toISOString(); const runDescription = 'Test run created via testrail-api-client example.'; const caseIds = [1, 2, 3]; // Optional: Array of TestRail case IDs to include in the run client.addRun(runName, runDescription, projectId, undefined, caseIds) .then((runId) => { console.log(`Successfully created Test Run with ID: ${runId}`); // Example: Add results for cases in the newly created run const results = [ { case_id: 1, status_id: 1, comment: 'Passed after successful execution.' }, // 1 = Passed { case_id: 2, status_id: 5, comment: 'Failed due to an assertion error.' } // 5 = Failed ]; return client.addResultsForCases(runId, results); }) .then(() => { console.log('Results added for cases.'); // Example: Close the run (uncomment to enable) // return client.closeRun(runId); }) .catch((error) => { console.error('An error occurred:', error.message || error); if (error.response && error.response.data) { console.error('TestRail API Error Details:', error.response.data); } });
Debug
Known issues
gotchaSince version 1.0.28, the client has functionality to ignore SSL certificate errors, particularly for self-signed certificates. While convenient for internal development environments, enabling this in production or insecure settings can pose a significant security risk by making connections vulnerable to man-in-the-middle attacks.
fix
Ensure that if you are using custom SSL certificates, they are properly configured and trusted by the Node.js environment. Avoid ignoring SSL errors in production to maintain secure communication. The feature is likely controlled by an option in the client constructor or an environment variable, but details are not explicitly documented; consult the source for 'ignore SSL' configuration.
affects: >=1.0.28
gotchaWhen initializing the client using CommonJS `require`, there are two patterns shown in the README, which can lead to confusion. `require('testrail-api-client')` attempts to initialize the client using environment variables, while `require('testrail-api-client').default` explicitly provides the constructor for custom options. Using the wrong one when environment variables are not set will result in errors.
fix
For explicit configuration, always use `const TestRailClient = require('testrail-api-client').default;` and then `new TestRailClient(options)`. If relying on environment variables for auto-configuration, `const client = require('testrail-api-client');` is appropriate.
affects: >=1.0.0
breakingThe package underwent changes related to `axios` versions (updates and downgrades). While usually backward compatible, major changes in `axios` or specific versions it targets could potentially introduce subtle breaking changes in HTTP request handling or error structures for consumers, especially if custom `axios` interceptors or configurations are used elsewhere in the application.
fix
Always test after updating to new patch versions that modify `axios` dependencies. If experiencing unexpected HTTP errors or request failures, check the changelog for `axios` specific notes and consider pinning a specific `testrail-api-client` version if compatibility issues arise.
affects: >=1.0.30
gotchaThe client relies heavily on environment variables (TESTRAIL_DOMAIN, TESTRAIL_USERNAME, TESTRAIL_APIKEY/TESTRAIL_PASSWORD) for its default initialization when `require('testrail-api-client')` is used without custom options. Failure to set these variables will result in authentication or connection errors, potentially without clear initial error messages about missing configuration.
fix
Ensure `TESTRAIL_DOMAIN`, `TESTRAIL_USERNAME`, and either `TESTRAIL_APIKEY` or `TESTRAIL_PASSWORD` are set as environment variables before running the application, or initialize the client explicitly with configuration options: `new TestRailClient({ domain: '...', username: '...', password: '...' });`.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Request failed with status code 401
Incorrect TestRail domain, username, or API key/password, or the user lacks sufficient permissions.
fix
Double-check `TESTRAIL_DOMAIN`, `TESTRAIL_USERNAME`, and `TESTRAIL_APIKEY` (or `TESTRAIL_PASSWORD`) environment variables or the options passed to the `TestRailClient` constructor. Verify credentials in TestRail's 'My Settings' and ensure the user has API access and project permissions.
Error: self-signed certificate in certificate chain
Attempting to connect to a TestRail instance using a self-signed SSL certificate without proper trust configuration in the Node.js environment.
fix
If this is a controlled environment (e.g., local development), you might allow self-signed certificates (though not recommended for production). Set the `TESTRAIL_IGNORE_SSL` environment variable to `true` (if the library supports it, otherwise check for a constructor option) or set `NODE_TLS_REJECT_UNAUTHORIZED='0'` (use with extreme caution). The best fix is to configure Node.js to trust the certificate or use a properly signed certificate.
TypeError: TestRailClient is not a constructor
Attempting to instantiate `TestRailClient` from `require('testrail-api-client')` directly without `.default` in CommonJS, or incorrectly importing a named export in ESM.
fix
For CommonJS, use `const TestRailClient = require('testrail-api-client').default;`. For ESM, use `import TestRailClient from 'testrail-api-client';`.
Error: Missing TestRail environment variables: TESTRAIL_DOMAIN, TESTRAIL_USERNAME, TESTRAIL_APIKEY/TESTRAIL_PASSWORD
The client was initialized without explicit options and required environment variables for auto-configuration were not found.
fix
Ensure `TESTRAIL_DOMAIN`, `TESTRAIL_USERNAME`, and either `TESTRAIL_APIKEY` or `TESTRAIL_PASSWORD` are set as environment variables before running the application, or initialize the client explicitly with configuration options: `new TestRailClient({ domain: '...', username: '...', password: '...' });`.
Upgrade
Version history
1.0.37latest on npm
Audit
Dependencies
axiosrequiredCore HTTP client for making API requests to TestRail.
Agent activity
34 hits · last 30 days
node
28
OpenAI (training)
1
Resources