@virag8/azure-devops-test-publisher 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 viragkumar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# azure-devops-test-publisher
+
+Publish automated test results and failure screenshots from WebdriverIO (Mocha or Cucumber/BDD) — or any custom TypeScript test runner — directly to **Azure DevOps Test Plans**.
+
+## Features
+
+- **Single shared Test Run** — creates one Azure DevOps Test Run for the whole suite in the launcher process and shares its id with all parallel workers via an environment variable, so results from every spec land in the same run.
+- **Mocha support** — extracts the Azure DevOps test case id from a test title (e.g. `C1234 login works`) via the `afterTest` hook.
+- **Cucumber / BDD support** — extracts the test case id from a scenario's `@C1234` tag, falling back to the scenario name, via the `afterScenario` hook.
+- **Custom case id pattern** — override the default `C123`/`#123` matcher with your own regex (e.g. `TC-(\d+)`) via `caseIdPattern`.
+- **Automatic failure screenshots** — captures a browser screenshot and attaches it to the Azure DevOps result whenever a test/scenario fails (toggle with `screenshotOnFailure`).
+- **Run reuse** — publish into an existing run (`runId`), or keep a single run open across multiple publishes (`reuseTestRun` / `keepRunOpen`) instead of creating a new run every time.
+- **Point pre-fetch** — pass already-fetched test points via `PublishOptions.points` to skip a redundant Azure DevOps API call.
+- **Resilient publishing** — publish failures are caught and logged so a flaky Azure DevOps API never fails the test run itself.
+- **Standalone reporter service** — `AzureDevOpsReporterService` for custom/non-service integrations that just need `afterTest` + `onComplete` hooks.
+- **Quiet by default** — set `debug: true` to log raw Azure DevOps API payloads while troubleshooting.
+- **Fully typed** — ships with TypeScript declarations for all public options and result types.
+
+## Installation
+
+```bash
+npm install --save-dev @virag8/azure-devops-test-publisher
+```
+
+Requires Node.js 18 or newer.
+
+## Usage with WebdriverIO
+
+Register the service in `wdio.conf.js` / `wdio.conf.ts`:
+
+```js
+const {
+  AzureDevOpsWdioService,
+} = require("@virag8/azure-devops-test-publisher");
+
+exports.config = {
+  // ...
+  services: [
+    [
+      AzureDevOpsWdioService,
+      {
+        orgUrl: process.env.AZURE_ORG_URL,
+        token: process.env.AZURE_PAT,
+        projectName: "MyProject", // name or GUID
+        planId: 123,
+        suiteId: 456,
+        screenshotOnFailure: true, // optional, defaults to true
+      },
+    ],
+  ],
+};
+```
+
+The service creates the Test Run in `onPrepare`, collects results from every worker via `afterTest`/`afterScenario`, publishes them in `after`, and completes the run in `onComplete`.
+
+### Mocha specs
+
+Tag the test title with the Azure DevOps test case id:
+
+```js
+it("C1234 login", async () => { ... });
+```
+
+### Cucumber / BDD feature files
+
+Tag the scenario with `@C<testCaseId>`:
+
+```gherkin
+@C1234
+Scenario: User can log in
+  Given the user is on the login page
+  When they submit valid credentials
+  Then they should see the dashboard
+```
+
+If no tag is present, the case id is parsed from the scenario name instead.
+
+### Custom case id pattern
+
+```js
+{
+  caseIdPattern: /TC-(\d+)/, // matches "TC-1234" in titles or tags
+}
+```
+
+The pattern must contain exactly one capturing group for the numeric id.
+
+## Usage as a standalone reporter
+
+For custom runners that aren't WebdriverIO services, use `AzureDevOpsReporterService` directly:
+
+```ts
+import { AzureDevOpsReporterService } from "@virag8/azure-devops-test-publisher";
+
+const reporter = new AzureDevOpsReporterService({
+  orgUrl: process.env.AZURE_ORG_URL!,
+  token: process.env.AZURE_PAT!,
+  projectName: "MyProject",
+  planId: 123,
+  suiteId: 456,
+});
+
+await reporter.afterTest(
+  { title: "C1234 login", duration: 250 },
+  {},
+  { passed: true },
+);
+await reporter.onComplete();
+```
+
+## Using the low-level `AzureDevOpsService`
+
+Both the WDIO service and the reporter are built on `AzureDevOpsService`, which you can use directly for full control over run creation and result publishing:
+
+```ts
+import { AzureDevOpsService } from "@virag8/azure-devops-test-publisher";
+
+const ado = new AzureDevOpsService({
+  orgUrl: process.env.AZURE_ORG_URL!,
+  token: process.env.AZURE_PAT!,
+  projectName: "MyProject",
+  planId: 123,
+  suiteId: 456,
+});
+
+await ado.publishResults([
+  {
+    testCaseId: 1234,
+    outcome: "Passed",
+    durationInMs: 250,
+  },
+]);
+```
+
+## Configuration reference
+
+### `AzureDevOpsOptions`
+
+| Option          | Type       | Description                                                         |
+| --------------- | ---------- | ------------------------------------------------------------------- |
+| `orgUrl`        | `string`   | Azure DevOps organization URL.                                      |
+| `token`         | `string`   | Personal access token with Test Plan read/write permissions.        |
+| `projectName`   | `string`   | Azure DevOps project **name or id (GUID)** — both are accepted.     |
+| `planId`        | `number`   | Test plan id.                                                       |
+| `suiteId`       | `number`   | Test suite id within the plan.                                      |
+| `runName`       | `string?`  | Custom name for created runs.                                       |
+| `runId`         | `number?`  | Reuse this existing run instead of creating a new one.              |
+| `reuseTestRun`  | `boolean?` | Keep a single run open across multiple `publishResults` calls.      |
+| `caseIdPattern` | `RegExp?`  | Custom regex (one capturing group) for extracting the test case id. |
+| `debug`         | `boolean?` | Log raw Azure DevOps API payloads. Defaults to `false`.             |
+
+> **Note on `projectName`** — despite the name, this accepts either the project's display name (`"MyProject"`) or its GUID (`"b9e8c7cb-..."`). Prefer the GUID: it stays stable if the project is ever renamed, and it avoids URL-encoding issues with names that contain spaces. You can find it at `https://dev.azure.com/<org>/_apis/projects`.
+
+### `AzureDevOpsWdioOptions` (extends `AzureDevOpsOptions`)
+
+| Option                | Type       | Description                                                        |
+| --------------------- | ---------- | ------------------------------------------------------------------ |
+| `screenshotOnFailure` | `boolean?` | Attach a browser screenshot to failed results. Defaults to `true`. |
+
+### `PublishOptions`
+
+| Option        | Type           | Description                                                             |
+| ------------- | -------------- | ----------------------------------------------------------------------- |
+| `runId`       | `number?`      | Publish into this existing run instead of creating a new one.           |
+| `points`      | `TestPoint[]?` | Reuse already-fetched test points instead of calling `getPoints` again. |
+| `keepRunOpen` | `boolean?`     | Leave the run in progress so more results can be added later.           |
+
+## Development
+
+```bash
+npm run test:unit   # mocked unit tests
+npm run test:real   # integration tests against a real Azure DevOps org (requires env vars)
+npm run build        # compile to dist/
+```
+
+## License
+
+MIT

package/dist/azureService.d.ts

@@ -0,0 +1,17 @@
+import { AzureDevOpsOptions, PublishOptions, TestResultItem } from "./types";
+export declare class AzureDevOpsService {
+    private testApiPromise?;
+    private config;
+    private currentRunId?;
+    /** Whether a PAT was provided; when false, every public method is a no-op. */
+    private readonly enabled;
+    constructor(config: AzureDevOpsOptions);
+    /** Id of the run currently being published to, if any. */
+    get runId(): number | undefined;
+    private debug;
+    /** Creates an empty run covering every point of the configured suite. */
+    createRun(): Promise<number | undefined>;
+    publishResults(results: TestResultItem[], options?: PublishOptions): Promise<number | undefined>;
+    /** Marks a run as completed. Defaults to the run used by the last publish. */
+    completeRun(runId?: number | undefined): Promise<void>;
+}

package/dist/azureService.js

@@ -0,0 +1,229 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AzureDevOpsService = void 0;
+const azdev = __importStar(require("azure-devops-node-api"));
+class AzureDevOpsService {
+    testApiPromise;
+    config;
+    currentRunId;
+    /** Whether a PAT was provided; when false, every public method is a no-op. */
+    enabled;
+    constructor(config) {
+        this.config = config;
+        this.currentRunId = config.runId;
+        this.enabled = Boolean(config.token);
+        if (!this.enabled) {
+            console.warn("Azure DevOps PAT (token) not provided; Azure DevOps test result publishing is disabled.");
+            return;
+        }
+        const authHandler = azdev.getPersonalAccessTokenHandler(config.token);
+        const connection = new azdev.WebApi(config.orgUrl, authHandler);
+        this.testApiPromise = connection.getTestApi();
+    }
+    /** Id of the run currently being published to, if any. */
+    get runId() {
+        return this.currentRunId;
+    }
+    debug(message, payload) {
+        if (!this.config.debug)
+            return;
+        console.log(message, payload);
+    }
+    /** Creates an empty run covering every point of the configured suite. */
+    async createRun() {
+        if (!this.enabled)
+            return undefined;
+        const testApi = await this.testApiPromise;
+        const points = await testApi.getPoints(this.config.projectName, this.config.planId, this.config.suiteId);
+        const pointIds = points
+            .map((p) => p.id)
+            .filter((id) => typeof id === "number");
+        const configurationIds = Array.from(new Set(points
+            .map((p) => p.configuration?.id ? parseInt(p.configuration.id, 10) : null)
+            .filter((id) => id !== null)));
+        const testRun = await testApi.createTestRun({
+            name: this.config.runName ||
+                `Automated Test Run - ${new Date().toISOString()}`,
+            automated: true,
+            plan: { id: this.config.planId.toString() },
+            pointIds,
+            configurationIds,
+        }, this.config.projectName);
+        if (!testRun.id) {
+            throw new Error("Failed to create Test Run in Azure DevOps.");
+        }
+        this.currentRunId = testRun.id;
+        return testRun.id;
+    }
+    async publishResults(results, options = {}) {
+        if (!this.enabled)
+            return undefined;
+        const testApi = await this.testApiPromise;
+        // 1. Get test points matching the local test cases
+        const points = options.points ??
+            (await testApi.getPoints(this.config.projectName, this.config.planId, this.config.suiteId));
+        this.debug("Fetched test points:", points);
+        const targetCaseIds = new Set(results.map((r) => r.testCaseId));
+        const matchedPoints = points.filter((p) => p.testCase?.id && targetCaseIds.has(parseInt(p.testCase.id, 10)));
+        this.debug("Matched test points:", matchedPoints);
+        if (matchedPoints.length === 0) {
+            console.warn("No matching test points found in Azure DevOps for the given test cases.");
+            return;
+        }
+        const pointIds = matchedPoints.map((p) => p.id);
+        this.debug("Point IDs for the test run:", pointIds);
+        // Extract unique configuration IDs from matched points (or fallback to empty array/default)
+        const configurationIds = Array.from(new Set(matchedPoints
+            .map((p) => p.configuration?.id ? parseInt(p.configuration.id, 10) : null)
+            .filter((id) => id !== null)));
+        this.debug("Configuration IDs for the test run:", configurationIds);
+        // 2. Reuse the existing Test Run when asked, otherwise create a new one
+        const reusedRunId = options.runId ??
+            (this.config.reuseTestRun ? this.currentRunId : undefined) ??
+            this.config.runId;
+        let runId;
+        if (reusedRunId) {
+            runId = reusedRunId;
+            // Only add points that the run does not already hold a result for
+            const existingResults = await testApi.getTestResults(this.config.projectName, runId);
+            const existingCaseIds = new Set(existingResults.map((r) => r.testCase?.id));
+            const missingPoints = matchedPoints.filter((p) => !existingCaseIds.has(p.testCase.id));
+            if (missingPoints.length > 0) {
+                await testApi.addTestResultsToTestRun(missingPoints.map((p) => ({
+                    testPoint: { id: p.id.toString() },
+                    testCase: { id: p.testCase.id },
+                    configuration: p.configuration?.id
+                        ? { id: p.configuration.id }
+                        : undefined,
+                })), this.config.projectName, runId);
+            }
+        }
+        else {
+            const runName = this.config.runName ||
+                `Automated Test Run - ${new Date().toISOString()}`;
+            const testRun = await testApi.createTestRun({
+                name: runName,
+                automated: true,
+                plan: { id: this.config.planId.toString() },
+                pointIds: pointIds,
+                configurationIds: configurationIds,
+            }, this.config.projectName);
+            if (!testRun.id) {
+                throw new Error("Failed to create Test Run in Azure DevOps.");
+            }
+            runId = testRun.id;
+        }
+        this.currentRunId = runId;
+        // 3. Fetch automatically created results for the run
+        const runResults = await testApi.getTestResults(this.config.projectName, runId);
+        // 4. Map outcomes and error messages
+        this.debug("Run results fetched from Azure DevOps:", runResults);
+        const updatedResults = runResults
+            .filter((result) => results.some((r) => r.testCaseId.toString() === result.testCase?.id))
+            .map((result) => {
+            const match = results.find((r) => r.testCaseId.toString() === result.testCase?.id);
+            return {
+                ...result,
+                outcome: match ? match.outcome : "Inconclusive",
+                errorMessage: match?.errorMessage || "",
+                state: "Completed",
+                durationInMs: match?.durationInMs || 0,
+            };
+        });
+        // 5. Update test results in ADO
+        this.debug("Updating test results in Azure DevOps:", updatedResults);
+        const savedResults = await testApi.updateTestResults(updatedResults, this.config.projectName, runId);
+        this.debug("Saved test results:", savedResults);
+        // The real API doesn't always echo `testCase` back on the updated results,
+        // so fall back to the id->caseId mapping we already know from step 4.
+        const caseIdByResultId = new Map();
+        for (const result of updatedResults) {
+            if (result.id && result.testCase?.id) {
+                caseIdByResultId.set(result.id, result.testCase.id);
+            }
+        }
+        // 6. Upload Attachments
+        for (const savedResult of savedResults) {
+            if (!savedResult.id)
+                continue;
+            const caseId = savedResult.testCase?.id ?? caseIdByResultId.get(savedResult.id);
+            if (!caseId)
+                continue;
+            const matchedLocalResult = results.find((r) => r.testCaseId.toString() === caseId);
+            if (matchedLocalResult?.attachments &&
+                matchedLocalResult.attachments.length > 0) {
+                for (const attachment of matchedLocalResult.attachments) {
+                    const attachmentModel = {
+                        fileName: attachment.fileName,
+                        stream: attachment.base64Content,
+                        comment: attachment.comment || "Automated execution screenshot",
+                        attachmentType: attachment.attachmentType || "GeneralAttachment",
+                    };
+                    // Log metadata only; the base64 stream is far too large to print.
+                    this.debug("Uploading attachment:", {
+                        resultId: savedResult.id,
+                        caseId,
+                        fileName: attachmentModel.fileName,
+                        attachmentType: attachmentModel.attachmentType,
+                        base64Length: attachment.base64Content?.length ?? 0,
+                    });
+                    const savedAttachment = await testApi.createTestResultAttachment(attachmentModel, this.config.projectName, runId, savedResult.id);
+                    this.debug("Attachment uploaded:", savedAttachment);
+                }
+            }
+            else {
+                this.debug("No attachments to upload for case:", caseId);
+            }
+        }
+        // 7. Complete the Test Run unless more results are still to come
+        const keepRunOpen = options.keepRunOpen ?? this.config.reuseTestRun ?? false;
+        if (!keepRunOpen) {
+            await this.completeRun(runId);
+        }
+        return runId;
+    }
+    /** Marks a run as completed. Defaults to the run used by the last publish. */
+    async completeRun(runId = this.currentRunId) {
+        if (!this.enabled || !runId)
+            return;
+        const testApi = await this.testApiPromise;
+        await testApi.updateTestRun({ state: "Completed" }, this.config.projectName, runId);
+        if (runId === this.currentRunId) {
+            this.currentRunId = undefined;
+        }
+    }
+}
+exports.AzureDevOpsService = AzureDevOpsService;

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { AzureDevOpsWdioOptions } from "./types";
+export declare class AzureDevOpsReporterService {
+    private options;
+    private results;
+    private ado?;
+    constructor(options: AzureDevOpsWdioOptions);
+    afterTest(test: {
+        title: string;
+        duration: number;
+    }, _context: unknown, results: {
+        passed: boolean;
+        error?: Error;
+    }, browserInstance?: {
+        takeScreenshot: () => Promise<string>;
+    }): Promise<void>;
+    onComplete(): Promise<void>;
+    /** Completes the shared test run when `reuseTestRun` keeps it open. */
+    completeRun(): Promise<void>;
+    private extractTestCaseId;
+}
+export * from "./types";
+export * from "./azureService";
+export * from "./wdioService";

package/dist/index.js

@@ -0,0 +1,81 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AzureDevOpsReporterService = void 0;
+const azureService_1 = require("./azureService");
+const utils_1 = require("./utils");
+class AzureDevOpsReporterService {
+    options;
+    results = [];
+    ado;
+    constructor(options) {
+        this.options = options;
+    }
+    async afterTest(test, _context, results, browserInstance) {
+        const caseId = this.extractTestCaseId(test.title);
+        if (!caseId)
+            return;
+        const attachments = [];
+        if (!results.passed &&
+            browserInstance &&
+            this.options.screenshotOnFailure !== false) {
+            try {
+                const base64Png = await browserInstance.takeScreenshot();
+                attachments.push({
+                    fileName: `failure-C${caseId}.png`,
+                    base64Content: base64Png,
+                    comment: `Failure screenshot for test: ${test.title}`,
+                });
+            }
+            catch (err) {
+                console.error("Failed to capture browser screenshot:", err);
+            }
+        }
+        this.results.push({
+            testCaseId: caseId,
+            outcome: results.passed ? "Passed" : "Failed",
+            errorMessage: results.error?.message,
+            durationInMs: test.duration,
+            attachments,
+        });
+    }
+    async onComplete() {
+        if (this.results.length === 0)
+            return;
+        this.ado ??= new azureService_1.AzureDevOpsService(this.options);
+        await this.ado.publishResults(this.results);
+        this.results = [];
+    }
+    /** Completes the shared test run when `reuseTestRun` keeps it open. */
+    async completeRun() {
+        await this.ado?.completeRun();
+    }
+    extractTestCaseId(title) {
+        const caseId = (0, utils_1.extractTestCaseId)(title, this.options.caseIdPattern);
+        if (this.options.debug) {
+            console.log("Extracted case id from test title:", {
+                title,
+                pattern: String(this.options.caseIdPattern ?? "default C123/#123"),
+                caseId,
+            });
+        }
+        return caseId;
+    }
+}
+exports.AzureDevOpsReporterService = AzureDevOpsReporterService;
+__exportStar(require("./types"), exports);
+__exportStar(require("./azureService"), exports);
+__exportStar(require("./wdioService"), exports);

package/dist/types.d.ts

@@ -0,0 +1,43 @@
+import { TestPoint } from "azure-devops-node-api/interfaces/TestInterfaces";
+export interface AzureDevOpsOptions {
+    orgUrl: string;
+    token: string;
+    /** Project display name or its GUID; Azure DevOps accepts either. */
+    projectName: string;
+    planId: number;
+    suiteId: number;
+    runName?: string;
+    /** Reuse this already existing test run instead of creating a new one. */
+    runId?: number;
+    /** Publish every batch into a single run, created on the first publish. */
+    reuseTestRun?: boolean;
+    /** Custom regex (with a capturing group for the numeric id) used instead of the default `C123`/`#123` matcher. */
+    caseIdPattern?: RegExp;
+    /** Log Azure DevOps API payloads to the console. Off by default. */
+    debug?: boolean;
+}
+export interface PublishOptions {
+    /** Publish into this existing run instead of creating a new one. */
+    runId?: number;
+    /** Reuse already-fetched test points instead of calling `getPoints` again. */
+    points?: TestPoint[];
+    /** Leave the run in progress so more results can be added later. */
+    keepRunOpen?: boolean;
+}
+export interface AzureDevOpsWdioOptions extends AzureDevOpsOptions {
+    /** Attach a browser screenshot to failed results. Defaults to true. */
+    screenshotOnFailure?: boolean;
+}
+export interface TestAttachment {
+    fileName: string;
+    base64Content: string;
+    comment?: string;
+    attachmentType?: string;
+}
+export interface TestResultItem {
+    testCaseId: number;
+    outcome: "Passed" | "Failed" | "Inconclusive";
+    errorMessage?: string;
+    durationInMs?: number;
+    attachments?: TestAttachment[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Reads the Azure DevOps case id out of a test title tagged with `C123` or `#123`.
+ * Pass a custom `pattern` (with a capturing group for the numeric id) to override the default.
+ */
+export declare function extractTestCaseId(title: string, pattern?: RegExp): number | null;

package/dist/utils.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractTestCaseId = extractTestCaseId;
+/**
+ * Reads the Azure DevOps case id out of a test title tagged with `C123` or `#123`.
+ * Pass a custom `pattern` (with a capturing group for the numeric id) to override the default.
+ */
+function extractTestCaseId(title, pattern) {
+    const match = pattern
+        ? title.match(pattern)
+        : title.match(/C(\d+)/i) || title.match(/#(\d+)/);
+    if (!match?.[1])
+        return null;
+    const caseId = parseInt(match[1], 10);
+    return Number.isNaN(caseId) ? null : caseId;
+}

package/dist/wdioService.d.ts

@@ -0,0 +1,53 @@
+import { AzureDevOpsWdioOptions } from "./types";
+/** Shares the run id created in the launcher process with the worker processes. */
+export declare const RUN_ID_ENV_VAR = "AZURE_DEVOPS_TEST_RUN_ID";
+interface WdioTest {
+    title: string;
+    fullTitle?: string;
+}
+interface WdioTestResult {
+    passed: boolean;
+    duration?: number;
+    error?: Error;
+}
+interface CucumberPickleTag {
+    name: string;
+}
+/** Shape of the `world` argument WebdriverIO's Cucumber framework passes to `afterScenario`. */
+interface CucumberWorld {
+    pickle: {
+        name: string;
+        tags?: CucumberPickleTag[];
+    };
+}
+interface CucumberResult {
+    passed: boolean;
+    duration?: number;
+    error?: Error;
+}
+/**
+ * WebdriverIO service that creates a single Test Run in `onPrepare`, pushes every
+ * spec's results into that run, and completes it in `onComplete`.
+ */
+export declare class AzureDevOpsWdioService {
+    private options;
+    private results;
+    private service?;
+    constructor(options: AzureDevOpsWdioOptions);
+    onPrepare(): Promise<void>;
+    onComplete(): Promise<void>;
+    private debug;
+    afterTest(test: WdioTest, _context: unknown, results: WdioTestResult): Promise<void>;
+    /** Cucumber hook for BDD feature files; reads the case id from a `@C123` tag or the scenario name. */
+    afterScenario(world: CucumberWorld, result: CucumberResult): Promise<void>;
+    after(): Promise<void>;
+    /** Publishes everything collected so far into the shared run. */
+    publish(): Promise<void>;
+    private captureScreenshot;
+    private extractCucumberCaseId;
+    private resolveRunId;
+    private getService;
+}
+/** WebdriverIO looks for a `launcher` export to run `onPrepare`/`onComplete`. */
+export declare const launcher: typeof AzureDevOpsWdioService;
+export default AzureDevOpsWdioService;

package/dist/wdioService.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.launcher = exports.AzureDevOpsWdioService = exports.RUN_ID_ENV_VAR = void 0;
+const azureService_1 = require("./azureService");
+const utils_1 = require("./utils");
+/** Shares the run id created in the launcher process with the worker processes. */
+exports.RUN_ID_ENV_VAR = "AZURE_DEVOPS_TEST_RUN_ID";
+/**
+ * WebdriverIO service that creates a single Test Run in `onPrepare`, pushes every
+ * spec's results into that run, and completes it in `onComplete`.
+ */
+class AzureDevOpsWdioService {
+    options;
+    results = [];
+    service;
+    constructor(options) {
+        this.options = options;
+    }
+    // --- launcher process hooks ---
+    async onPrepare() {
+        const runId = await this.getService().createRun();
+        if (runId === undefined)
+            return;
+        process.env[exports.RUN_ID_ENV_VAR] = runId.toString();
+        console.log(`Azure DevOps test run created: ${runId}`);
+    }
+    async onComplete() {
+        const runId = this.resolveRunId();
+        if (!runId)
+            return;
+        await this.getService().completeRun(runId);
+        delete process.env[exports.RUN_ID_ENV_VAR];
+        console.log(`Azure DevOps test run completed: ${runId}`);
+    }
+    // --- worker process hooks ---
+    debug(message, payload) {
+        if (!this.options.debug)
+            return;
+        console.log(message, payload);
+    }
+    async afterTest(test, _context, results) {
+        const caseId = (0, utils_1.extractTestCaseId)(test.title, this.options.caseIdPattern);
+        this.debug("Extracted case id from test title:", {
+            title: test.title,
+            pattern: String(this.options.caseIdPattern ?? "default C123/#123"),
+            caseId,
+        });
+        if (!caseId)
+            return;
+        this.results.push({
+            testCaseId: caseId,
+            outcome: results.passed ? "Passed" : "Failed",
+            errorMessage: results.error?.message,
+            durationInMs: results.duration ?? 0,
+            attachments: await this.captureScreenshot(caseId, test, results),
+        });
+    }
+    /** Cucumber hook for BDD feature files; reads the case id from a `@C123` tag or the scenario name. */
+    async afterScenario(world, result) {
+        const caseId = this.extractCucumberCaseId(world);
+        if (!caseId)
+            return;
+        this.results.push({
+            testCaseId: caseId,
+            outcome: result.passed ? "Passed" : "Failed",
+            errorMessage: result.error?.message,
+            durationInMs: result.duration ?? 0,
+            attachments: await this.captureScreenshot(caseId, { title: world.pickle.name }, result),
+        });
+    }
+    async after() {
+        await this.publish();
+    }
+    /** Publishes everything collected so far into the shared run. */
+    async publish() {
+        if (this.results.length === 0)
+            return;
+        const pending = this.results;
+        this.results = [];
+        try {
+            await this.getService().publishResults(pending, {
+                runId: this.resolveRunId(),
+                keepRunOpen: true,
+            });
+        }
+        catch (err) {
+            console.error("Failed to publish results to Azure DevOps:", err);
+        }
+    }
+    async captureScreenshot(caseId, test, results) {
+        if (results.passed || this.options.screenshotOnFailure === false)
+            return [];
+        const browser = globalThis
+            .browser;
+        if (!browser?.takeScreenshot)
+            return [];
+        try {
+            return [
+                {
+                    fileName: `failure-C${caseId}.png`,
+                    base64Content: await browser.takeScreenshot(),
+                    comment: `Failure screenshot for test: ${test.fullTitle || test.title}`,
+                },
+            ];
+        }
+        catch (err) {
+            console.error("Failed to capture browser screenshot:", err);
+            return [];
+        }
+    }
+    extractCucumberCaseId(world) {
+        const pattern = this.options.caseIdPattern;
+        const tags = world.pickle.tags ?? [];
+        this.debug("Scanning scenario tags for case id:", {
+            scenario: world.pickle.name,
+            tags: tags.map((t) => t.name),
+            pattern: String(pattern ?? "default C123/#123"),
+        });
+        for (const tag of tags) {
+            const caseId = (0, utils_1.extractTestCaseId)(tag.name, pattern);
+            if (caseId) {
+                this.debug("Matched case id from tag:", { tag: tag.name, caseId });
+                return caseId;
+            }
+        }
+        const fromName = (0, utils_1.extractTestCaseId)(world.pickle.name, pattern);
+        this.debug("No tag matched; fell back to scenario name:", {
+            scenario: world.pickle.name,
+            caseId: fromName,
+        });
+        return fromName;
+    }
+    resolveRunId() {
+        const fromEnv = process.env[exports.RUN_ID_ENV_VAR];
+        const parsed = fromEnv ? parseInt(fromEnv, 10) : NaN;
+        return Number.isNaN(parsed) ? this.options.runId : parsed;
+    }
+    getService() {
+        this.service ??= new azureService_1.AzureDevOpsService(this.options);
+        return this.service;
+    }
+}
+exports.AzureDevOpsWdioService = AzureDevOpsWdioService;
+/** WebdriverIO looks for a `launcher` export to run `onPrepare`/`onComplete`. */
+exports.launcher = AzureDevOpsWdioService;
+exports.default = AzureDevOpsWdioService;

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@virag8/azure-devops-test-publisher",
+  "version": "1.0.0",
+  "description": "Upload test results and screenshots to Azure DevOps Test Plans from WebdriverIO or custom TS runners",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "license": "MIT",
+  "author": "virag <viragkumar58@gmail.com>",
+  "homepage": "https://github.com/viragkumar/azure-devops-test-publisher#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/viragkumar/azure-devops-test-publisher.git"
+  },
+  "bugs": {
+    "url": "https://github.com/viragkumar/azure-devops-test-publisher/issues"
+  },
+  "keywords": [
+    "webdriverio",
+    "wdio",
+    "wdio-service",
+    "ado",
+    "azure-devops",
+    "azure-test-plans",
+    "test-results",
+    "reporter",
+    "cucumber",
+    "mocha",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc",
+    "prepublishOnly": "npm run test:unit && npm run build",
+    "test:unit": "jest --config tests/jest.config.js",
+    "test:real": "jest --config tests/jest.real.config.js",
+    "test": "npm run test:unit"
+  },
+  "dependencies": {
+    "azure-devops-node-api": "^12.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.0.0",
+    "dotenv": "^17.4.2",
+    "jest": "^30.5.1",
+    "rimraf": "^5.0.0",
+    "ts-jest": "^29.4.12",
+    "typescript": "^5.0.0"
+  }
+}