Azure DevOps Client

Description

This project contains a client for interacting with the Azure DevOps API, specifically designed for automated management of test runs and test results. The AzureDevOpsClient class allows executing CRUD operations with the following Azure DevOps elements:

• Test Cases
• Test Runs
• Test Results

Installation

Prerequisites

• Node.js (version 14 or higher)
• npm or yarn
• Access to an Azure DevOps project
• Azure DevOps Personal Access Token (PAT) with read/write permissions on Test Plans

Dependencies

npm install dotenv

Environment Variables

Create a .env file in the project root with the following variables:

AZURE_DEVOPS_BASE_URL=https://dev.azure.com/your-organization/your-project
AZURE_DEVOPS_PAT=your-personal-access-token
TEST_PLAN_ID=12345

Usage

Import

const { AzureDevOpsClient } = require('./apis/azureDevOpsClient.js');

Initialization

// Create a client instance with the test suite ID
const testSuiteId = "67890";
const azureClient = new AzureDevOpsClient(testSuiteId);

Usage Examples

1. Register a Complete Test Run

// Test information
const testInfo = {
    title: "Automation-12345-Login functionality test",
    status: "PASSED" // or "FAILED"
};

// Register the test run
try {
    await azureClient.registerTestRun(testInfo);
    console.log("Test run registered successfully");
} catch (error) {
    console.error("Error registering test run:", error.message);
}

2. Get Test Points

try {
    const response = await azureClient.getTestPoints();
    await azureClient.verifyStatusResponseCode(response, 200, 'GetTestPoints');
    const jsonResponse = await azureClient.getResponseAsJson(response);
    console.log("Test Points:", jsonResponse.value);
} catch (error) {
    console.error("Error getting test points:", error.message);
}

3. Create a Test Run Manually

const testRunData = {
    type: "Normal",
    name: "My Test Run",
    comment: "Automated test",
    plan: {
        id: process.env.TEST_PLAN_ID
    },
    pointIds: [123456] // Test point IDs
};

try {
    const response = await azureClient.createTestRun(testRunData);
    await azureClient.verifyStatusResponseCode(response, 200, 'CreateTestRun');
    const result = await azureClient.getResponseAsJson(response);
    console.log("Test Run created:", result.id);
} catch (error) {
    console.error("Error creating test run:", error.message);
}

4. Update Test Result

const testResultData = [{
    id: 100000,
    outcome: "Passed", // or "Failed"
    comment: "Test result is satisfactory"
}];

const testRunId = "987654";

try {
    const response = await azureClient.updateTestResult(testResultData, testRunId);
    await azureClient.verifyStatusResponseCode(response, 200, 'UpdateTestResult');
    console.log("Test result updated");
} catch (error) {
    console.error("Error updating result:", error.message);
}

5. Search Test Point by Test Case ID

const testCaseId = "12345";

try {
    const testPointId = await azureClient.getTestPointByTestCaseId(testCaseId);
    if (testPointId) {
        console.log(`Test Point found: ${testPointId}`);
    } else {
        console.log("Test Point not found");
    }
} catch (error) {
    console.error("Error searching test point:", error.message);
}

6. Create Test Result Attachment

const attachmentData = {
    fileName: "screenshot.png",
    comment: "Test execution screenshot",
    attachmentType: "GeneralAttachment"
};

const testRunId = "987654";
const testResultId = "100000"; // Optional, defaults to '100000'

try {
    const response = await azureClient.createTestResultAttachment(
        attachmentData, 
        testRunId, 
        testResultId
    );
    await azureClient.verifyStatusResponseCode(response, 200, 'CreateAttachment');
    console.log("Attachment created successfully");
} catch (error) {
    console.error("Error creating attachment:", error.message);
}

Test Case Title Format

The test case title must follow this format:

[Prefix]-[Numeric_ID]-[Test_Title]

Example:

Automation-12345-Login functionality test

Where:

• Automation: Identifier prefix
• 12345: Numeric ID of the test case in Azure DevOps
• Login functionality test: Test description

Available Methods

Main Methods

| Method | Description | Parameters | |--------|-------------|------------| | registerTestRun(testInfo) | Registers a complete test run | testInfo: object with title and status | | getTestPoints() | Gets all test points from the suite | None | | createTestRun(data) | Creates a new test run | data: object with test run data | | updateTestResult(data, testRunId) | Updates test result | data: result data, testRunId: run ID | | createTestResultAttachment(data, testRunId, testResultId) | Creates attachment for test result | data: attachment data, testRunId: run ID, testResultId: result ID (optional) | | getTestPointByTestCaseId(testCaseId) | Searches test point by case ID | testCaseId: test case ID |

Utility Methods

| Method | Description | Parameters | |--------|-------------|------------| | verifyStatusResponseCode(response, expectedCode, endpointName) | Verifies HTTP status code | response: HTTP response, expectedCode: expected code, endpointName: endpoint name | | getResponseAsJson(response) | Converts response to JSON | response: HTTP response | | getResponseAsText(response) | Converts response to text | response: HTTP response | | verifyTestTitleFormat(title) | Verifies title format | title: title to verify | | toBase64(str) | Converts string to Base64 | str: input string |

Error Handling

The class uses TypeError for validation errors. It's recommended to use try-catch blocks:

try {
    await azureClient.registerTestRun(testInfo);
} catch (error) {
    if (error instanceof TypeError) {
        console.error("Validation error:", error.message);
    } else {
        console.error("Unexpected error:", error);
    }
}

Project Structure

├── apis/
│   ├── azureDevOpsClient.js
│   ├── package.json
│   └── azureDevOps/
│       ├── testPoints/
│       ├── testResultAttachments/
│       ├── testResults/
│       └── testRuns/
├── .env
└── README.md

Azure DevOps Configuration

Getting Personal Access Token (PAT)

1. Go to Azure DevOps → User Settings → Personal Access Tokens
2. Create a new token with the following permissions:
   • Test Management: Read & Write
   • Work Items: Read

Getting Required IDs

• Test Plan ID: Available in the test plan URL
• Test Suite ID: Available in the test suite URL
• Organization/Project: Part of the Azure DevOps base URL

API Response Examples

Test Points Response

{
    "value": [
        {
            "id": 1,
            "testCase": {
                "id": "12345",
                "name": "Login Test"
            },
            "configuration": {
                "id": "1",
                "name": "Windows 10"
            }
        }
    ]
}

Test Run Response

{
    "id": 987654,
    "name": "My Test Run",
    "state": "InProgress",
    "isAutomated": false,
    "plan": {
        "id": "12345"
    }
}

Best Practices

1. Environment Variables: Always use environment variables for sensitive data like PATs
2. Error Handling: Implement proper error handling for all async operations
3. Logging: Use console logging for debugging and monitoring
4. Validation: Validate test case title format before processing
5. Status Codes: Always verify HTTP response status codes

Common Issues and Solutions

Issue: "tetsPlanId parameter is required"

Solution: Ensure TEST_PLAN_ID is set in your .env file

Issue: "Invalid testCaseID, check the test case title format"

Solution: Verify the test case title follows the format: Prefix-NumericID-Title

Issue: "TestPoint not found"

Solution: Ensure the test case ID exists in the specified test suite

Issue: Authentication errors

Solution: Verify your PAT has the correct permissions and is properly encoded

Contributing

To contribute to the project:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-functionality)
3. Commit your changes (git commit -am 'Add new functionality')
4. Push to the branch (git push origin feature/new-functionality)
5. Create a Pull Request

License

This project is licensed under the ISC License.

Author

Hector S. Medina Acosta

Important Notes

• Ensure environment variables are properly configured before using the class
• Test case IDs must exist in Azure DevOps
• Personal Access Token must have the necessary permissions
• All methods are asynchronous and should be used with await or .then()
• The client automatically handles Base64 encoding for authentication