lawrencehan650/testrail-jest-reporter

Custom Jest reporter for Testrail synchronization

Jest to TestRail Reporter

This package allows you to use Jest and report your test results to TestRail.
Please use with combination with the default reporter

Install

npm i testrail-jest-reporter --save-dev

Jest configurations

As per Jest's documentation, the Reporter must be specified in the jest-config.js or package.json file as part of the reporters array.

• This file should be created in your project's root folder.
• Parameter is defined as 'project_id', which is the id of your project on TestRail.
• Specify the TestRail server url as parameter 'baseUrl' (recommended).
• Specify the TestRail Milestone name as parameter 'milestone' (recommended).
• Specify the TestRail suite mode id as parameter 'suite_mode' (recommended). If that parameter is not specified, the Reporter will get this automatically.

  single repository for all cases - suite_mode:1
  single repository with baseline support - suite_mode:2
  multiple test suites to manage cases - suite_mode:3
  

• There is no 'pending' or 'skipped' test result status in the TestRail results default
  statuses. You can add your custom status to the TestRail and specify it id as parameter
  '"statuses":{"pending": "7"}' (recommended).

Usage

// this is the part of the jest-config.js
module.exports = {
  ...,
  reporters: [
    "default",
    [
        "testrail-jest-reporter", 
        { project_id: 1, 
            baseUrl: 'http://localhost', 
            milestone: '<milestone_name>',
            suite_mode: 3,
            statuses: {pending: 7}
        },
    ]
  ], 
    ...
};

// this is the "jest" part of the package.json
{
  "jest": {
    "reporters": [
      "default",
        [
            "testrail-jest-reporter",
            { 
                "project_id": "1",
                "baseUrl": 'http://localhost',
                "milestone": '<milestone_name>',
                "suite_mode": "3",
                "statuses": {"pending": "7"}
            }
        ]
    ]
  }
}

TestRail configurations

The testrail.conf.js file needs to be created in your project's root folder.

• It must contain your TestRail username (email address) and password (or API key).
• This file needs to have all 2 parameters correctly filled.
• It may contain the URL of your TestRail server as a baseUrl parameter, or
  it can be specified in Jest configuration
• You can specify custom regex expresion (default: /[C][?\d]{3,6}/gm)

Use TestRail Milestone

The first version of the Reporter requires you to use a milestone.

• Use TestRail Milestone to versioning your tests.
• testrail.conf.js file needs to have Milestone name filled. Or
  it can be specified in Jest configuration

Example

module.exports = {
    'baseUrl': 'http://localhost',
    'user': 'user@example.com',
    'pass': 'some-password',
    'milestone': '<milestone_name>',
    'regex': /[C][?\d]{3,6}/gm
}

Important: If you use a public repository, please, secure your sensitive data.

Enable TestRail API

In order to use TestRail API, it needs to be enabled by an administrator
in your own TestRail Site Settings. Also, if you want to use API authentication instead of your password,
enable session authentication for API in the TestRail Site Settings,
and add an API key in your User settings (This is recommended).

Add TestRail tests Runs

You can add a TestRail tests Runs or tests Plan with all tests you want to automate.
If you don't, the Reporter will publish Jest tests results into the new TestRail test Run.
Each time the Jest runs tests the Reporter parse all TestRail tests Plans
and tests Runs of the Milestone to collect testcases. The Reporter collects only unique testcases,
if you have several tests Runs with one testcase then The Reporter push the test result only to one of that Runs.

Example tests

The Case ID from TestRail may be added to it() description each test result you want to push to TestRail. You can specify several cases in one it() description.

Usage

describe("Tests suite", () => {
  // "C123" this is Case ID from Test Rail
  it("C123 test success", async () => {
    expect(1).toBe(1);
  });

  it("Test fail C124 C125", async () => {
    expect(1).toBe(0);
  });

  xit("Another success test", async () => {
    expect(1).toBe(1);
  });
});

Note: The Case ID is a unique and permanent ID of every test case (e.g. C125), and shouldn't be confused with a Test Case ID,
which is assigned to a test case when a new run is created (e.g. T325).

Note: The first and second it() test result will be reported, and the last - not.

Roadmap

This version:

• Add new tests Run if there are testcases that are not present in any of the existing TestRail tests Runs. >> Done in 1.1.0
• Add new test Runs if the Milestone not specified.
• Add new TestRail Milestone if the specified Milestone not present in the Project.
• Also need to write more tests. >> Done in 1.0.4
• Added ability to specify several case_ids in one test description >> Done in 1.0.6
• Added JSON validator to API interface >> Done in 1.0.7
• Migrate to GOT

Version 2:

• Add the Reporter CLI.

Version 3:

• Add ability to parse code annotations.
• Add new TestRail testcase if it() description not specified by Case ID.
• Add maintenance the TestRail test Plan and test Configurations.

License

This project is licensed under the MIT License - see the LICENSE file for details.