@keber/qa-framework 1.0.4

package/examples/module-example/suppliers/suppliers-create.spec.ts

@@ -0,0 +1,148 @@
+/**
+ * examples/module-example/suppliers/suppliers-create.spec.ts
+ *
+ * Example Playwright E2E spec for the fictional "Suppliers" module.
+ * Demonstrates all required keber/qa-framework patterns:
+ *   - EXEC_IDX for test data uniqueness
+ *   - P0 priority tagging
+ *   - Skip pattern with DEF reference
+ *   - Fast-fail textContent assertions
+ *   - Auth via storageState (set up by global-setup.ts)
+ *
+ * This file is for REFERENCE ONLY. Copy it, adapt selectors, and remove
+ * all fictional data before using in a real project.
+ */
+
+import { test, expect } from '@playwright/test';
+
+// EXEC_IDX: unique per minute-window — prevents data collisions between runs
+const EXEC_IDX = Math.floor(Date.now() / 60_000) % 100_000;
+
+test.describe('Suppliers > Create @P0', () => {
+
+  /**
+   * [TC-SUP-CR-001] Create supplier — happy path @P0
+   * Verifies the complete create flow for a valid supplier.
+   */
+  test('[TC-SUP-CR-001] Create supplier — happy path @P0', async ({ page }) => {
+    const supplierName = `QA-Supplier-${EXEC_IDX}`;
+    const supplierRut  = `${EXEC_IDX}-K`;
+    const supplierEmail = `qa-supplier-${EXEC_IDX}@example.com`;
+
+    // Navigate to suppliers module
+    await page.goto('/suppliers');
+    await expect(page.locator('.supplier-grid')).toBeVisible();
+
+    // Open create modal
+    await page.locator('button:has-text("New Supplier")').click();
+    await expect(page.locator('.supplier-modal')).toBeVisible();
+
+    // Fill form
+    await page.locator('#supplier-name').fill(supplierName);
+    await page.locator('#supplier-rut').fill(supplierRut);
+    await page.locator('#supplier-email').fill(supplierEmail);
+    await page.locator('#supplier-type').selectOption('Nacional');
+
+    // Save
+    await page.locator('button:has-text("Save")').click();
+
+    // Assert success
+    const toast = page.locator('.toast.toast-success');
+    await expect(toast).toBeVisible({ timeout: 5_000 });
+    const toastText = await toast.textContent();
+    expect(toastText).toContain('Supplier saved');
+
+    // Assert record appears in grid
+    await expect(page.locator(`.supplier-grid:has-text("${supplierName}")`)).toBeVisible();
+  });
+
+  /**
+   * [TC-SUP-CR-002] Create supplier — required fields validation @P0
+   * Verifies that the form prevents submission when required fields are empty.
+   */
+  test('[TC-SUP-CR-002] Create supplier — required fields validation @P0', async ({ page }) => {
+    await page.goto('/suppliers');
+    await page.locator('button:has-text("New Supplier")').click();
+    await expect(page.locator('.supplier-modal')).toBeVisible();
+
+    // Attempt save with empty form
+    await page.locator('button:has-text("Save")').click();
+
+    // Assert validation messages appear
+    await expect(page.locator('.field-error:has-text("Name is required")')).toBeVisible();
+    await expect(page.locator('.field-error:has-text("RUT is required")')).toBeVisible();
+
+    // Assert form was NOT submitted (modal still open)
+    await expect(page.locator('.supplier-modal')).toBeVisible();
+    const toast = page.locator('.toast.toast-success');
+    await expect(toast).not.toBeVisible();
+  });
+
+  /**
+   * [TC-SUP-CR-003] Create supplier — duplicate RUT rejected @P0
+   *
+   * NOTE: test.skip active — DEF-001: Duplicate RUT check not enforced server-side.
+   *       Reactivate when ADO #99001 is resolved.
+   */
+  test('[TC-SUP-CR-003] Create supplier — duplicate RUT rejected @P0', async ({ page }) => {
+    test.skip(true,
+      'DEF-001: Duplicate RUT validation not enforced. Reactivate when ADO #99001 is resolved.'
+    );
+
+    // --- SKIPPED: steps below will not run until DEF-001 is fixed ---
+    await page.goto('/suppliers');
+
+    // Create first supplier
+    await page.locator('button:has-text("New Supplier")').click();
+    await page.locator('#supplier-name').fill(`QA-Dup-${EXEC_IDX}`);
+    await page.locator('#supplier-rut').fill('12345678-9');
+    await page.locator('#supplier-email').fill(`qa-dup-${EXEC_IDX}@example.com`);
+    await page.locator('button:has-text("Save")').click();
+    await expect(page.locator('.toast.toast-success')).toBeVisible();
+
+    // Attempt to create duplicate
+    await page.locator('button:has-text("New Supplier")').click();
+    await page.locator('#supplier-name').fill(`QA-Dup2-${EXEC_IDX}`);
+    await page.locator('#supplier-rut').fill('12345678-9'); // same RUT
+    await page.locator('#supplier-email').fill(`qa-dup2-${EXEC_IDX}@example.com`);
+    await page.locator('button:has-text("Save")').click();
+
+    await expect(page.locator('.toast.toast-error:has-text("RUT already exists")')).toBeVisible();
+  });
+
+});
+
+test.describe('Suppliers > List @P1', () => {
+
+  /**
+   * [TC-SUP-LS-001] List loads and displays supplier grid @P1
+   */
+  test('[TC-SUP-LS-001] List loads and displays supplier grid @P1', async ({ page }) => {
+    await page.goto('/suppliers');
+
+    // Grid must render without console errors
+    await expect(page.locator('.supplier-grid')).toBeVisible();
+
+    // Search input present
+    await expect(page.locator('#supplier-search')).toBeVisible();
+
+    // Export button present
+    await expect(page.locator('button:has-text("Export")')).toBeVisible();
+  });
+
+  /**
+   * [TC-SUP-LS-002] Unauthenticated user redirected to login @P0
+   */
+  test('[TC-SUP-LS-002] Unauthenticated user redirected to login @P0', async ({ browser }) => {
+    // Create a fresh context with NO stored auth state
+    const ctx  = await browser.newContext({ storageState: undefined });
+    const page = await ctx.newPage();
+
+    await page.goto(`${process.env.QA_BASE_URL}/suppliers`);
+
+    // Should redirect to login
+    await expect(page).toHaveURL(/\/login/);
+    await ctx.close();
+  });
+
+});

package/integrations/ado-powershell/README.md

@@ -0,0 +1,75 @@
+# Integration — ADO PowerShell Scripts
+
+PowerShell scripts for Azure DevOps Test Plan management.
+All scripts are parameterized and project-agnostic.
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/inject-ado-ids.ps1` | Prepend ADO Work Item IDs to spec file test titles |
+| `scripts/create-testplan-from-mapping.ps1` | Create ADO Test Cases from a TC mapping JSON file |
+| `scripts/sync-ado-titles.ps1` | Sync spec file test titles back to ADO WI titles |
+| `pipelines/azure-pipeline-qa.yml` | CI pipeline template for running Playwright + ADO sync |
+
+## Prerequisites
+
+- PowerShell 7+ (recommended) or Windows PowerShell 5.1
+- Azure DevOps Personal Access Token (PAT) with `Work Items: Read & Write` scope
+- PAT stored as `$env:AZURE_TOKEN` or passed via `-Token` parameter
+
+## Quick start
+
+```powershell
+# 1. Generate ado-ids.json mapping (from your TC mapping file)
+.\scripts\create-testplan-from-mapping.ps1 `
+  -OrgUrl      "https://dev.azure.com/your-org" `
+  -ProjectName "YourProject" `
+  -PlanId      22304 `
+  -MappingFile "qa/08-azure-integration/tc-mapping.json" `
+  -Token       $env:AZURE_TOKEN
+
+# 2. Inject ADO IDs into spec files (idempotent)
+.\scripts\inject-ado-ids.ps1 `
+  -SpecDir     "qa/07-automation/e2e" `
+  -MappingFile "qa/08-azure-integration/ado-ids.json"
+
+# 3. Run tests (ADO reporter publishes results automatically)
+npx playwright test
+
+# 4. (Optional) Sync titles back to ADO
+.\scripts\sync-ado-titles.ps1 `
+  -OrgUrl      "https://dev.azure.com/your-org" `
+  -ProjectName "YourProject" `
+  -MappingFile "qa/08-azure-integration/ado-ids.json" `
+  -Token       $env:AZURE_TOKEN
+```
+
+## Security rules
+
+- NEVER hardcode tokens in script files
+- NEVER commit `.env` files or generated `*.json` files that contain tokens
+- Always pass `-Token` as a parameter from `$env:AZURE_TOKEN` or a CI secret variable
+- PAT scope: minimum `Work Items: Read & Write`, `Test Management: Read & Write`
+
+## File: tc-mapping.json (input)
+
+```json
+{
+  "planId": 22304,
+  "suiteId": 22305,
+  "testCases": [
+    { "localId": "TC-SUP-CR-001", "title": "Create supplier @P0", "specFile": "suppliers/create.spec.ts" },
+    { "localId": "TC-SUP-CR-002", "title": "Create supplier - required fields @P0", "specFile": "suppliers/create.spec.ts" }
+  ]
+}
+```
+
+## File: ado-ids.json (output after create-testplan)
+
+```json
+[
+  { "localId": "TC-SUP-CR-001", "adoWiId": 22957, "specFile": "suppliers/create.spec.ts" },
+  { "localId": "TC-SUP-CR-002", "adoWiId": 22958, "specFile": "suppliers/create.spec.ts" }
+]
+```

package/integrations/ado-powershell/pipelines/azure-pipeline-qa.yml

@@ -0,0 +1,133 @@
+# -----------------------------------------------------------------------
+# keber/qa-framework — Azure Pipeline QA Template
+# -----------------------------------------------------------------------
+# Parameterized CI pipeline for running Playwright E2E tests and
+# optionally syncing results to Azure DevOps Test Plans.
+#
+# Required Pipeline Library Variable Group: "QA-Variables"
+#   QA_BASE_URL          — Target application URL for QA environment
+#   QA_USER_EMAIL        — Default test user email
+#   QA_USER_PASSWORD     — Default test user password (secret)
+#   AZURE_TOKEN          — ADO Personal Access Token (secret)
+#   ADO_ORG_URL          — https://dev.azure.com/your-org
+#   ADO_PROJECT_NAME     — ADO project name
+#   ADO_PLAN_ID          — Test Plan ID
+# -----------------------------------------------------------------------
+
+trigger:
+  branches:
+    include:
+      - main
+      - qa
+      - release/*
+
+pr:
+  branches:
+    include:
+      - main
+
+variables:
+  - group: QA-Variables
+  - name: NODE_VERSION
+    value: '20.x'
+  - name: QA_DIR
+    value: 'qa/07-automation'
+  - name: ADO_SYNC_DISABLED
+    value: 'false'
+
+pool:
+  vmImage: 'ubuntu-latest'
+
+stages:
+  # -----------------------------------------------------------------------
+  # Stage 1: Install & Setup
+  # -----------------------------------------------------------------------
+  - stage: Setup
+    displayName: 'Install Dependencies'
+    jobs:
+      - job: Install
+        displayName: 'npm install + Playwright browsers'
+        steps:
+          - task: NodeTool@0
+            inputs:
+              versionSpec: $(NODE_VERSION)
+            displayName: 'Use Node.js $(NODE_VERSION)'
+
+          - script: |
+              cd $(QA_DIR)
+              npm ci
+              npx playwright install chromium --with-deps
+            displayName: 'Install npm deps and Playwright Chromium'
+
+          - task: CacheBeta@1
+            inputs:
+              key: 'playwright | "$(Agent.OS)" | $(QA_DIR)/package-lock.json'
+              path: '~/.cache/ms-playwright'
+            displayName: 'Cache Playwright browsers'
+
+  # -----------------------------------------------------------------------
+  # Stage 2: E2E Tests
+  # -----------------------------------------------------------------------
+  - stage: E2E
+    displayName: 'E2E Tests'
+    dependsOn: Setup
+    jobs:
+      - job: PlaywrightTests
+        displayName: 'Run Playwright suite'
+        timeoutInMinutes: 60
+        steps:
+          - task: NodeTool@0
+            inputs:
+              versionSpec: $(NODE_VERSION)
+
+          - script: |
+              cd $(QA_DIR)
+              npm ci
+              npx playwright install chromium --with-deps
+            displayName: 'Restore dependencies'
+
+          - script: |
+              cd $(QA_DIR)
+              npx playwright test --grep @P0
+            displayName: 'Run P0 smoke suite'
+            env:
+              QA_BASE_URL:       $(QA_BASE_URL)
+              QA_USER_EMAIL:     $(QA_USER_EMAIL)
+              QA_USER_PASSWORD:  $(QA_USER_PASSWORD)
+              AZURE_TOKEN:       $(AZURE_TOKEN)
+              ADO_ORG_URL:       $(ADO_ORG_URL)
+              ADO_PROJECT_NAME:  $(ADO_PROJECT_NAME)
+              ADO_PLAN_ID:       $(ADO_PLAN_ID)
+              ADO_SYNC_DISABLED: $(ADO_SYNC_DISABLED)
+              CI:                'true'
+
+          - script: |
+              cd $(QA_DIR)
+              npx playwright test --grep "@P1|@P2"
+            displayName: 'Run P1/P2 regression suite'
+            condition: succeededOrFailed()
+            env:
+              QA_BASE_URL:       $(QA_BASE_URL)
+              QA_USER_EMAIL:     $(QA_USER_EMAIL)
+              QA_USER_PASSWORD:  $(QA_USER_PASSWORD)
+              AZURE_TOKEN:       $(AZURE_TOKEN)
+              ADO_ORG_URL:       $(ADO_ORG_URL)
+              ADO_PROJECT_NAME:  $(ADO_PROJECT_NAME)
+              ADO_PLAN_ID:       $(ADO_PLAN_ID)
+              CI:                'true'
+
+          - task: PublishTestResults@2
+            condition: always()
+            inputs:
+              testResultsFormat: 'JUnit'
+              testResultsFiles:  '$(QA_DIR)/test-results/junit*.xml'
+              mergeTestResults:  true
+              testRunTitle:      'Playwright E2E — $(Build.SourceBranchName)'
+            displayName: 'Publish test results'
+
+          - task: PublishBuildArtifacts@1
+            condition: always()
+            inputs:
+              pathToPublish: '$(QA_DIR)/playwright-report'
+              artifactName:  'playwright-report'
+            displayName: 'Publish Playwright HTML report'

package/integrations/ado-powershell/scripts/create-testplan-from-mapping.ps1

@@ -0,0 +1,114 @@
+<#
+.SYNOPSIS
+    Creates Azure DevOps Test Cases from a local tc-mapping.json file.
+
+.DESCRIPTION
+    Reads a tc-mapping.json file containing local TC definitions and creates
+    corresponding Test Case Work Items in a specified ADO Test Plan/Suite.
+    Outputs ado-ids.json with the resulting WI IDs for use by inject-ado-ids.ps1.
+
+.PARAMETER OrgUrl
+    Azure DevOps organization URL (e.g. https://dev.azure.com/your-org).
+
+.PARAMETER ProjectName
+    ADO project name.
+
+.PARAMETER PlanId
+    ADO Test Plan ID.
+
+.PARAMETER SuiteId
+    ADO Test Suite ID. If omitted, uses the plan's root suite.
+
+.PARAMETER MappingFile
+    Path to tc-mapping.json input file.
+
+.PARAMETER OutputFile
+    Path to write ado-ids.json output. Default: ado-ids.json in same dir as MappingFile.
+
+.PARAMETER Token
+    ADO Personal Access Token. Prefer passing via $env:AZURE_TOKEN.
+
+.EXAMPLE
+    .\create-testplan-from-mapping.ps1 `
+        -OrgUrl      "https://dev.azure.com/your-org" `
+        -ProjectName "YourProject" `
+        -PlanId      22304 `
+        -MappingFile "qa/08-azure-integration/tc-mapping.json" `
+        -Token       $env:AZURE_TOKEN
+#>
+[CmdletBinding(SupportsShouldProcess)]
+param(
+    [Parameter(Mandatory)] [string] $OrgUrl,
+    [Parameter(Mandatory)] [string] $ProjectName,
+    [Parameter(Mandatory)] [int]    $PlanId,
+    [int]                           $SuiteId = 0,
+    [Parameter(Mandatory)] [string] $MappingFile,
+    [string]                        $OutputFile = '',
+    [Parameter(Mandatory)] [string] $Token
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# Build auth header
+$b64   = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$Token"))
+$headers = @{
+    'Authorization' = "Basic $b64"
+    'Content-Type'  = 'application/json'
+}
+
+# Load mapping
+if (-not (Test-Path $MappingFile)) { Write-Error "Not found: $MappingFile"; exit 1 }
+$mapping = Get-Content $MappingFile -Raw | ConvertFrom-Json
+
+$apiBase = "$OrgUrl/$ProjectName/_apis"
+$suiteId = if ($SuiteId -gt 0) { $SuiteId } else { $mapping.suiteId }
+
+Write-Host "[create-testplan] Creating $($mapping.testCases.Count) test cases in Plan $PlanId / Suite $suiteId"
+
+$results = @()
+
+foreach ($tc in $mapping.testCases) {
+    $body = @{
+        op    = 'add'
+        path  = '/fields/System.Title'
+        value = "[$($tc.localId)] $($tc.title)"
+    } | ConvertTo-Json -AsArray
+
+    $createUrl = "$apiBase/wit/workitems/`$Test Case?api-version=7.1"
+
+    if ($PSCmdlet.ShouldProcess($tc.localId, "Create ADO Test Case")) {
+        try {
+            $wi = Invoke-RestMethod `
+                -Method  Patch `
+                -Uri     $createUrl `
+                -Headers ($headers + @{ 'Content-Type' = 'application/json-patch+json' }) `
+                -Body    $body
+
+            $wiId = $wi.id
+            Write-Host "  [CREATED] $($tc.localId) → WI #$wiId"
+
+            # Add to suite
+            $suiteUrl = "$apiBase/testplan/Plans/$PlanId/Suites/$suiteId/TestCase?api-version=7.1"
+            $suiteBody = @(@{ workItem = @{ id = $wiId } }) | ConvertTo-Json
+            Invoke-RestMethod -Method Post -Uri $suiteUrl -Headers $headers -Body $suiteBody | Out-Null
+
+            $results += [PSCustomObject]@{
+                localId  = $tc.localId
+                adoWiId  = $wiId
+                specFile = $tc.specFile
+                title    = $tc.title
+            }
+        } catch {
+            Write-Warning "  [FAILED] $($tc.localId) — $($_.Exception.Message)"
+        }
+    }
+}
+
+# Write output
+$outFile = if ($OutputFile) { $OutputFile } else {
+    Join-Path (Split-Path $MappingFile) 'ado-ids.json'
+}
+$results | ConvertTo-Json -Depth 5 | Set-Content $outFile
+Write-Host ""
+Write-Host "[create-testplan] Done. $($results.Count) WIs created. Output: $outFile"

package/integrations/ado-powershell/scripts/inject-ado-ids.ps1

@@ -0,0 +1,96 @@
+<#
+.SYNOPSIS
+    Prepends Azure DevOps Work Item IDs to Playwright spec file test titles.
+
+.DESCRIPTION
+    Reads ado-ids.json (produced by create-testplan-from-mapping.ps1) and
+    updates every matching test() / test.skip() call in the spec files to
+    include the ADO WI ID as a prefix.
+
+    This operation is IDEMPOTENT: if the ID is already present, it is not
+    duplicated.
+
+.PARAMETER SpecDir
+    Root directory containing Playwright spec files (.spec.ts).
+    Searched recursively.
+
+.PARAMETER MappingFile
+    Path to ado-ids.json — array of { localId, adoWiId, specFile }.
+
+.EXAMPLE
+    .\inject-ado-ids.ps1 `
+        -SpecDir     "qa/07-automation/e2e" `
+        -MappingFile "qa/08-azure-integration/ado-ids.json"
+
+.NOTES
+    Does NOT require a network connection or ADO token.
+    Commit the modified spec files after running.
+#>
+[CmdletBinding(SupportsShouldProcess)]
+param(
+    [Parameter(Mandatory)]
+    [string] $SpecDir,
+
+    [Parameter(Mandatory)]
+    [string] $MappingFile
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# Load mapping
+if (-not (Test-Path $MappingFile)) {
+    Write-Error "Mapping file not found: $MappingFile"
+    exit 1
+}
+$mapping = Get-Content $MappingFile -Raw | ConvertFrom-Json
+
+Write-Host "[inject-ado-ids] Loaded $($mapping.Count) mapping entries from $MappingFile"
+
+$updated = 0
+$skipped = 0
+
+foreach ($entry in $mapping) {
+    $adoId   = $entry.adoWiId
+    $localId = $entry.localId
+
+    # Find spec files matching this entry
+    $pattern = if ($entry.specFile) { $entry.specFile } else { "**/*.spec.ts" }
+    $files   = Get-ChildItem -Path $SpecDir -Recurse -Filter "*.spec.ts" |
+               Where-Object { $_.FullName -like "*$($entry.specFile)*" }
+
+    foreach ($file in $files) {
+        $content = Get-Content $file.FullName -Raw
+
+        # Match test titles containing the localId but NOT already prefixed with adoId
+        # Pattern: test('...[TC-x-x-NNN]...') where [NNN_ADOID] not yet present
+        $adoPrefix   = "[$adoId]"
+        $escapedId   = [regex]::Escape($localId)
+
+        # Check if already injected (idempotent guard)
+        if ($content -match [regex]::Escape($adoPrefix)) {
+            Write-Verbose "[$localId] ADO WI $adoId already present in $($file.Name) — skipping"
+            $skipped++
+            continue
+        }
+
+        # Replace: test('ORIGINAL_TITLE') → test('[ADOID] ORIGINAL_TITLE')
+        # Matches both single and double quotes, test() and test.skip()
+        $newContent = $content -replace `
+            "(?<=(test(?:\.skip)?\s*\()(['""]))\s*(?=.*\Q$localId\E)", `
+            "$adoPrefix "
+
+        if ($newContent -ne $content) {
+            if ($PSCmdlet.ShouldProcess($file.FullName, "Inject ADO WI $adoId for $localId")) {
+                Set-Content -Path $file.FullName -Value $newContent -NoNewline
+                Write-Host "  [UPDATED] $($file.Name) — injected [$adoId] for $localId"
+                $updated++
+            }
+        } else {
+            Write-Verbose "  [NO MATCH] $localId not found by pattern in $($file.Name)"
+        }
+    }
+}
+
+Write-Host ""
+Write-Host "[inject-ado-ids] Done. Updated: $updated | Skipped (already present): $skipped"

package/integrations/ado-powershell/scripts/sync-ado-titles.ps1

@@ -0,0 +1,93 @@
+<#
+.SYNOPSIS
+    Syncs Playwright spec file test titles back to Azure DevOps Work Item titles.
+
+.DESCRIPTION
+    After test titles are updated in spec files (e.g., after a spec refactor),
+    this script reads ado-ids.json and updates ADO WI titles to match the
+    current spec file titles.
+
+.PARAMETER OrgUrl
+    Azure DevOps organization URL.
+
+.PARAMETER ProjectName
+    ADO project name.
+
+.PARAMETER MappingFile
+    Path to ado-ids.json (output of create-testplan-from-mapping.ps1).
+
+.PARAMETER SpecDir
+    Root directory of Playwright spec files (.spec.ts). Searched recursively.
+
+.PARAMETER Token
+    ADO Personal Access Token. Prefer $env:AZURE_TOKEN.
+
+.EXAMPLE
+    .\sync-ado-titles.ps1 `
+        -OrgUrl      "https://dev.azure.com/your-org" `
+        -ProjectName "YourProject" `
+        -MappingFile "qa/08-azure-integration/ado-ids.json" `
+        -SpecDir     "qa/07-automation/e2e" `
+        -Token       $env:AZURE_TOKEN
+#>
+[CmdletBinding(SupportsShouldProcess)]
+param(
+    [Parameter(Mandatory)] [string] $OrgUrl,
+    [Parameter(Mandatory)] [string] $ProjectName,
+    [Parameter(Mandatory)] [string] $MappingFile,
+    [Parameter(Mandatory)] [string] $SpecDir,
+    [Parameter(Mandatory)] [string] $Token
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$b64     = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$Token"))
+$headers = @{
+    'Authorization' = "Basic $b64"
+    'Content-Type'  = 'application/json-patch+json'
+}
+
+$mapping = Get-Content $MappingFile -Raw | ConvertFrom-Json
+$apiBase = "$OrgUrl/$ProjectName/_apis"
+
+$synced  = 0
+$skipped = 0
+
+foreach ($entry in $mapping) {
+    $adoId   = $entry.adoWiId
+    $specFile = Get-ChildItem -Path $SpecDir -Recurse -Filter "*.spec.ts" |
+                Where-Object { $_.FullName -like "*$($entry.specFile)*" } |
+                Select-Object -First 1
+
+    if (-not $specFile) {
+        Write-Warning "  [NOT FOUND] $($entry.specFile) — skipping WI $adoId"
+        $skipped++
+        continue
+    }
+
+    # Extract title from test() line that contains the adoId prefix
+    $content = Get-Content $specFile.FullName -Raw
+    $match   = [regex]::Match($content, "test(?:\.skip)?\s*\(\s*['""](\[$adoId\][^'""]+)['""]")
+
+    if (-not $match.Success) {
+        Write-Verbose "  [NO MATCH] WI $adoId title not found in $($specFile.Name)"
+        $skipped++
+        continue
+    }
+
+    $newTitle = $match.Groups[1].Value.Trim()
+    $patchUrl = "$apiBase/wit/workitems/$($adoId)?api-version=7.1"
+    $body     = @(
+        @{ op = 'replace'; path = '/fields/System.Title'; value = $newTitle }
+    ) | ConvertTo-Json -AsArray
+
+    if ($PSCmdlet.ShouldProcess("WI #$adoId", "Update title to: $newTitle")) {
+        Invoke-RestMethod -Method Patch -Uri $patchUrl -Headers $headers -Body $body | Out-Null
+        Write-Host "  [SYNCED] WI #$adoId → $newTitle"
+        $synced++
+    }
+}
+
+Write-Host ""
+Write-Host "[sync-ado-titles] Done. Synced: $synced | Skipped: $skipped"