{"id":13051,"library":"cypress-testrail-simple","title":"Cypress TestRail Simple Reporter","description":"cypress-testrail-simple is a Cypress plugin designed for straightforward integration with TestRail, enabling the simple upload of Cypress test results. The current stable version is `3.3.63`, with a frequent release cadence, often issuing bug fixes and dependency updates every few days to weeks, indicating active maintenance. This library distinguishes itself by offering a simple, environment variable-driven configuration for TestRail integration, making it easy to set up for CI/CD pipelines. It provides programmatic hooks for Cypress's `setupNodeEvents` to automatically send test outcomes to a specified TestRail project and suite. Additionally, it offers `npx` commands for managing TestRail runs, such as `testrail-start-run`, which can initiate a new run, optionally filtering by specific test case IDs extracted from Cypress spec files.","status":"active","version":"3.3.63","language":"javascript","source_language":"en","source_url":"https://github.com/bahmutov/cypress-testrail-simple","tags":["javascript","cypress","testrail","plugin","reporter","cypress-plugin"],"install":[{"cmd":"npm install cypress-testrail-simple","lang":"bash","label":"npm"},{"cmd":"yarn add cypress-testrail-simple","lang":"bash","label":"yarn"},{"cmd":"pnpm add cypress-testrail-simple","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a Cypress plugin and requires Cypress to function.","package":"cypress","optional":false}],"imports":[{"note":"The plugin is imported as a CommonJS module from a specific path and immediately invoked within Cypress's Node `setupNodeEvents` function. It's not a standard default or named ESM import.","wrong":"import plugin from 'cypress-testrail-simple'","symbol":"plugin","correct":"await require('cypress-testrail-simple/src/plugin')(on, config)"},{"note":"This is a CLI command provided by the package, not a JavaScript function intended for direct import within application code. It's executed via `npx`.","wrong":"import { startRun } from 'cypress-testrail-simple/bin/start-run'","symbol":"testrail-start-run","correct":"npx testrail-start-run"}],"quickstart":{"code":"const { defineConfig } = require('cypress');\n\nmodule.exports = defineConfig({\n  e2e: {\n    // Ensure your Cypress tests run in a way that matches TestRail structure\n    // For example, tagging tests with 'Cxxx' for case IDs.\n    setupNodeEvents(on, config) {\n      // This configures the TestRail plugin\n      require('cypress-testrail-simple/src/plugin')(on, config);\n      return config;\n    },\n  },\n  // Add environment variables or ensure they are set in your CI environment\n  // For local testing, you might use an 'env' object or a .env file.\n  env: {\n    TESTRAIL_HOST: process.env.TESTRAIL_HOST || 'https://your-instance.testrail.io',\n    TESTRAIL_USERNAME: process.env.TESTRAIL_USERNAME || 'your_username',\n    TESTRAIL_PASSWORD: process.env.TESTRAIL_PASSWORD || 'your_api_key',\n    TESTRAIL_PROJECTID: process.env.TESTRAIL_PROJECTID || '1',\n    TESTRAIL_SUITEID: process.env.TESTRAIL_SUITEID || '' // Optional\n  }\n});\n\n// Example of how to start a test run before running Cypress (e.g., in CI)\n// In your CI script, you would typically run:\n// const runId = require('child_process').execSync('npx testrail-start-run --name \"Cypress CI Run\"').toString().trim();\n// console.log(`Started TestRail run: ${runId}`);\n// then pass this runId to Cypress if needed, though the plugin often handles associating results.","lang":"javascript","description":"This quickstart demonstrates how to configure `cypress-testrail-simple` in `cypress.config.js` for Cypress v10+ and how to set up the necessary environment variables for TestRail integration."},"warnings":[{"fix":"For Cypress v10+, integrate the plugin within the `e2e.setupNodeEvents` or `component.setupNodeEvents` function in `cypress.config.js`. For older versions, use `cypress/plugins/index.js`.","message":"Cypress v10 introduced a new configuration file structure (`cypress.config.js` instead of `cypress/plugins/index.js`). Users migrating older Cypress projects must update their plugin integration accordingly.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure all required `TESTRAIL_` environment variables are set in your execution environment (e.g., CI, local shell, or via `cypress.env` in `cypress.config.js`). API keys are preferred over passwords for `TESTRAIL_PASSWORD`.","message":"The plugin relies heavily on environment variables (`TESTRAIL_HOST`, `TESTRAIL_USERNAME`, `TESTRAIL_PASSWORD`, `TESTRAIL_PROJECTID`, `TESTRAIL_SUITEID`) for configuration. If these are not correctly set, the plugin will not be able to interact with TestRail.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use `require('cypress-testrail-simple/src/plugin')` as shown in the documentation for integrating the plugin into `setupNodeEvents`.","message":"The plugin is imported from a specific sub-path (`cypress-testrail-simple/src/plugin`) rather than the package root. Incorrect paths will lead to module not found errors.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install -D cypress-testrail-simple` or `yarn add -D cypress-testrail-simple`. Double-check the path in `cypress.config.js` matches `require('cypress-testrail-simple/src/plugin')`.","cause":"The package is not installed, or the import path is incorrect.","error":"Error: Cannot find module 'cypress-testrail-simple/src/plugin'"},{"fix":"Verify `TESTRAIL_USERNAME` and `TESTRAIL_PASSWORD` (or API key) environment variables are correct and have appropriate permissions for the TestRail instance.","cause":"Incorrect TestRail credentials (username, password, or API key) provided via environment variables.","error":"TestRail API error: Authentication failed, please check your username and password or API key."},{"fix":"Confirm that `TESTRAIL_PROJECTID` matches a valid project ID in your TestRail instance and that the configured user has access to it.","cause":"The `TESTRAIL_PROJECTID` environment variable is set to a non-existent or inaccessible project ID.","error":"TestRail API error: Project ID is invalid."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"testrail"}