testrail-integration/README.md

TestRail API's

# testrail-integration tool


# Please use below version to support only testrail APi's without cucumber
# You can try with the new version also
```text

npm i testrail-integration@0.1.7

```


#Upcoming features
- Going to support Mocha integration  


## Highlights

- It supports CommonJS, ES, ECMACScript and TypeScript
- Supports all Testrail api's that are available 
- Pretty easy to use this library for JS and non JavaScript developers
- It supports Cucumber, Mocha and other frameworks as well
- It helps integration testing with all testing frameworks
- Handled all exceptions, so no need to use try catch blocks
- Well managed responses
- Interfaces already implemented, so use it directly
- more customized options for step results
- async and awaits are supported
- Actively maintained

-Please check API reference: https://www.gurock.com/testrail/docs/api
 
 

## Please refer below git urls for Cucumber Integration with testrail 
 - it supports Protractor , WebdriverIO and other tools which supports cucumber framework 
```text
Testrail integrations with CUCUMBER scenarios by just adding cucumber tags   ex: @c1234 @Bug-DSS-3467
```
- https://github.com/automatekitbox/testrail-api-integration/blob/main/README.md
- https://github.com/automatekitbox/testrail-api-integration/blob/main/cucumbertestrail.png


#Tip
```text
 Always update test result after execution of test case
 Use After hook 
 You will not miss previous testcase results if something aborts in the middle of test execution
```

#Handling right error messages
```json
{
 "message": "Response code 400 (Bad Request)",
 "name": "HTTPError",
 "host": "inc1.testrail.io",
 "url": "https://inc1.testrail.io/index.php?/api/v2/add_result_for_case/1/156789",
 "path": "/index.php?/api/v2/add_result_for_case/1/156789",
 "body": "\"{\\\"error\\\":\\\"Field :case_id is not a valid test case.\\\"}\""
}

```
# Ex: handle error with catch 
```js
 try {
      await testrail.getCased(caseId);
     } catch ( err) {
       console.log( err);
     }
```
## Sample code for JS and  TS(typescript)
- Refer interfaces to know what data needs to be passed otherwise use implemented interfaces directly
- https://github.com/automatekitbox/testrail-api-integration/blob/main/testrail.interface.ts
- Sample code
```js
 const {INewTestResultImpl } = require("testrail-integration");
 const content = new INewTestResultImpl();
     content.comment = "FIRST COMMENT";
     content.version = "Build#1";
     content.defects = "DSS-123";

```

# getTests(run_id: number)

```js
 const { TestRailClient } = require("testrail-integration");

(async () => {
      const options = {
        username: "abc@gmail.com",
        password: "pwd",
        url: "https://my.testrail.io"
      }
      const client = new TestRailClient(options);
      const res = await client.getTests(1);
      console.log(JSON.stringify(res));
})();
```

# TypeScript
```typescript jsx
import {TestRailClient} from "testrail-integration";

      const options = {
        username: "abc@gmail.com",
        password: "pwd",
        url: "https://my.testrail.io"
      }
      const client = new TestRailClient(options);
      const res = await client.getTests(1);
      console.log(JSON.stringify(res));
```
# addResultForCase(runId: number, caseId: number, content: INewTestResult)
```js
 const { TestRailClient } = require("testrail-integration");

(async () => {
      const options = {
        username: "abc@gmail.com",
        password: "pwd",
        url: "https://my.testrail.io"
      }
      const client = new TestRailClient(options);
      const content = {
        comment: "FIRST COMMENT",
        version: "Build#1",
        defects: "DSS-123",
        status_id: 5 //fail
      }
      const testResult = await client.addResultForCase(1,  2, content );
      console.log("Test Results property wise" + testResult.status_id +  testResult.comment + testResult.defects);
      console.log("Test Results" + JSON.stringify(testResult));
})();
```
# using Interface - better approach

```js
 const { TestRailClient, INewTestResultImpl } = require("testrail-integration");

(async () => {
      const options = {
        username: "abc@gmail.com",
        password: "pwd",
        url: "https://my.testrail.io"
      }
      const client = new TestRailClient(options);
//Using Interface implentation 
     const content = new INewTestResultImpl();
     content.comment = "FIRST COMMENT";
     content.version = "Build#1";
     content.defects = "DSS-123";
     status_id: 1; //pass
     const testResult = await client.addResultForCase(1,  2, content );
     console.log("Test Results property wise" + testResult.status_id +  testResult.comment + testResult.defects);
     console.log("Test Results" +  JSON.stringify(res1));
})();
```
## addResultsForCases(runId: number, results: INewTestResults[]) ==> update test result for multiple cases
- Sending content directly
```js
 const { TestRailClient } = require("testrail-integration");

(async () => {
      const options = {
        username: "abc@gmail.com",
        password: "pwd",
        url: "https://my.testrail.io"
      }
      const client = new TestRailClient(options);
      const content = [{
        case_id: 4,
        comment: "FIRST COMMENT",
        version: "Build#1",
        status_id: 1 //pass
      }, {
                 comment: "SECOND COMMENT",
                 version: "Build#1",
                 defects: "DSS-124",
                 status_id: 5 //fail
               } ]
      const res1 = await client.addResultsForCases(1, content );
      console.log("Test Results property wise for each case" + res1[0].status_id + res1[1].status_id );
      console.log("Test Results" + JSON.stringify(res1));
})();
```

# Using Interface to update multiple testcase results
```js
 const { TestRailClient, INewTestResultsImpl } = require("testrail-integration");

(async () => {
          const options = {
            username: "abc@gmail.com",
            password: "pwd",
            url: "https://my.testrail.io"
          }
          const client = new TestRailClient(options);
          const newTestResults =  [];
           const firstCaseResult =  new INewTestResultsImpl();
           firstCaseResult.case_id = 1;
           firstCaseResult.comment = "ARRAY!";
           firstCaseResult.status_id = 5;

           newTestResults.push(firstCaseResult);

           const secondCaseResult =  new INewTestResultsImpl();
           secondCaseResult.case_id = 19;
           secondCaseResult.comment = "ARRAY!";
           secondCaseResult.status_id = 5;

           secondCaseResult.push(secondCaseResult);

           const res = await client.addResultsForCases(1,  newTestResults );
           console.log("Test Results" + JSON.stringify(res));
})();
```
## addRun(projectId: number, content: INewTestRun):
- Provide suite_id if it is applicable
Note: Free trail , we will not see suites, so we create testcases without suite
```js
//Free Trial testrail
      const myNewRun = { name: "My TESTRUN!", description: "MY NEW RUN ONE" };
      const addRun = await client.addRun(1, myNewRun);

//Official testrail, your testcases belongs to suite, so suite_id is mandatory
      const myNewRun = { suite_id: 2, name: "My TESTRUN!", description: "MY NEW RUN ONE" };
      const newRunResult = await client.addRun(1, myNewRun);
      console.log("New Run Details" + JSON.stringify(newRunResult));
```


# //----- ADD RUNS  AND Cases   
- supported wrapper to get run_id 
>  getRunId(projectId: number, runName: string): <number>

>   addRun(projectId: number, content: INewTestRun)

>   getRun(runId: number)

>   getRuns(projectId: number)

>   updateRun(runId: number, content: INewTestRun)

> getCase(caseId: number): returns <ICase> 

> getCases(projectId: number, caseFilters: ICaseFilters)

> addCase(sectionId: number, content: ICase)

>  updateCase(caseId: number, content: ICaseUpdate)

>  deleteCase(caseId: number)

>   deleteCases(projectId: number, suiteId: number, soft: number = 1, caseIds: number[])


# // ----- Case Fields -----
> getCaseFields()
  
#  // ----- Case Types -----
> getCaseTypes()
  
 # // ----- Configurations -----
> getConfigs(project_id: number)
  
> addConfigGroup(project_id: number, content: IConfigurationUpdate)
  
> addConfig(config_group_id: number, content: IConfigurationUpdate)
  
> updateConfigGroup(config_group_id: number, content: IConfigurationUpdate)
  
> updateConfig(config_id: number, content: IConfigurationUpdate)
  
> deleteConfigGroup(config_group_id: number)

> deleteConfig(config_id: number)
  
#  // ----- Milestones -----
  
> getMilestone(milestone_id: number)
  
> getMilestones(project_id: number, filters: IMilestoneFilters)
  
> addMilestone(project_id: number, content: INewMilestone)
  
> updateMilestone(milestone_id: number, content: IMilestoneUpdate)

> deleteMilestone(milestone_id: number)
  
#  // ----- Plans -----
  
> getPlan(plan_id: number)
  
> getPlans(project_id: number, filters: any)
  
> addPlan(project_id: number, content: any)
  
> addPlanEntry(plan_id: number, content: any)
  
> updatePlan(plan_id: number, content: any)
  
> updatePlanEntry(plan_id: number, entry_id: number, content: any)
  
> closePlan(plan_id: number)

> deletePlan(plan_id: number)
  
> deletePlanEntry(plan_id: number, entry_id: number)
  
#  // ----- Priorities -----
  
> getPriorities()
  
#  // ----- Projects -----
  
> getProject(project_id: number)
  
> getProjects(filters: IProjectFilters)

> addProject(content: IProjectUpdate)
  
> updateProject(project_id: number, content: IProjectUpdate)
  
> deleteProject(project_id: number)
  
#      // ----- Results -----
  
> getResults(test_id: number, filters: ITestResultFilters)

> getResultsForCase(run_id: number, case_id: number, filters: ITestResultFilters)

> getResultsForRun(run_id: number, filters: ITestResultsForRunFilters)
  
> addResult(test_id: number, content: INewTestResult)
  
> addResults(run_id: number, content: INewTestResult[])
  
#  // ----- Result Fields -----
> getResultFields()
 #     // ----- Sections -----
  
> getSection(section_id: number)
  
> getSections(project_id: number, filters: any)
  
> addSection(project_id: number, content: INewSection)
  
> updateSection(section_id: number, content: ISectionUpdate)
  
> deleteSection(section_id: number)
 # // ----- Statuses -----
  
> getStatuses()
  
#  // ----- Suites -----
> getSuite(suite_id: number)
  
> getSuites(project_id: number)
  
> addSuite(project_id: number, content: INewSuite)
  
> updateSuite(suite_id: number, content: INewSuite)
  
> deleteSuite(suite_id: number)
      
  
#  // ----- Templates -----
  
> getTemplates(project_id: number)
## ----- Tests -----
  
> getTest(test_id: number)
  
> getTests(run_id: number, filters?: { status_id?: number | number[] })
  
 ## ----- Users -----
  
> getUser(user_id: number)
> getUserByEmail(email: string)
> getUsers()

#### Publishing changes
Document is in progress!
Queries at letautomate@gmail.com



## License

Please see [LICENSE.md](LICENSE.md).