@keber/qa-framework 1.9.1 → 1.11.3

package/CHANGELOG.md

@@ -7,29 +7,101 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
-## [1.0.0] - 2026-03-04
+## [1.11.0] - 2026-06-24
 
 ### Added
 
-- **Framework scaffold** — initial `qa/` directory tree with 9 numbered folders (00–08)
-- **6-file submodule template set** — `00-inventory` through `05-test-scenarios`
-- **Agent instructions** — 7 purpose-specific Markdown instruction files for IDE agents
-- **Standards** — naming conventions, bug report template, test case template, test data guidelines
-- **Automation scaffold** — generalized Playwright `playwright.config.ts`, `global-setup.ts`, `.env.example`, `fixtures/auth.ts`
-- **Optional integrations** — stubs and READMEs for Playwright, `playwright-azure-reporter`, and ADO PowerShell
-- **CLI entry point** — `qa-framework init`, `generate`, `validate` commands
-- **Documentation** — architecture, comparison matrix, generalization decisions, installation guide, usage-with-agent guide, spec-driven philosophy, folder structure guide
-- **Migration notes** — `MIGRATION-NOTES.md` for projects moving from embedded to package-based framework
+- **`templates/automation-scaffold/fixtures/base.ts`** — new fixture with TTL-aware session
+  refresh. Replaces the plain `@playwright/test` import in long-running suites where the
+  server-side session may expire before the suite finishes.
+- **`templates/automation-scaffold/global-setup.ts`** — hardened login flow:
+  - `resolveVar()` with source logging (`param` / `env:KEY` / `default`)
+  - Login retry loop (up to 3 attempts) with crash-page detection and recovery
+  - `resolveAuthUsers()` — derives which users to authenticate from `QA_AUTH_USER` env var
+    or from configured `storageState` paths in `playwright.config.ts`
+  - `dismissOnboardingFlow()` — configurable via `QA_DISMISS_ONBOARDING_LABELS`
+    (comma-separated button labels); no-op by default
+  - Support for a second test user (`.auth/user-2.json`) via `QA_USER2_EMAIL` /
+    `QA_USER2_PASSWORD`
+- **`templates/automation-scaffold/playwright.config.ts`** — exports `SESSION_TTL_MS`
+  (default 2 h, overridable via `QA_SESSION_TTL_MS`); commented-out parallel 2-user variant
+  (`chromium-user1` / `chromium-user2`).
+- **`templates/automation-scaffold/.env.example`** — new variables: `QA_SESSION_TTL_MS`,
+  `QA_AUTH_USER`, `QA_USER2_EMAIL`, `QA_USER2_PASSWORD`, `QA_DISMISS_ONBOARDING_LABELS`,
+  `PLAYWRIGHT_SERVICE_URL`.
+- **`templates/integration-scaffold/`** — new scaffold for API testing with Playwright
+  `APIRequestContext`. Includes `package.json`, `playwright.config.ts`, `global-setup.ts`
+  (token-based or browser-login auth), `tests/example.spec.ts`, `README.md`, `.env.example`.
+  Deployed to `qa/07-automation/integration/` on `init` and `upgrade`.
+- **`templates/memory/`** — three semi-guided operational memory templates:
+  `ci-pipeline-findings.md`, `e2e-stabilization-patterns.md`, `data-volatility-strategies.md`.
+  Seeded into `qa/memory/` on `init` and `upgrade`.
+- **`qa/06-defects/disputed/`** — third defect state for cases where QA has evidence but the
+  business or dev team disputes the expected behavior. Created on `init` and `upgrade`.
+- **`integrations/ado-powershell/pipelines/azure-pipeline-qa.yml`** — operational hardening:
+  - `suiteFilter` pipeline parameter (default `all`); auto-overridden to `all` on scheduled runs
+  - Bash array (`GREP_ARGS`) for safe grep pattern expansion with bracket characters
+  - `PublishTestResults@2` scoped to exact XML path instead of `**/*.xml`
+  - `publishRunAttachments: false` on both E2E and API stages
+  - Artifact names suffixed with `$(System.JobAttempt)` to prevent collision on retries
+  - `QA_AUTH_USER` documented as commented example for the 2-job parallel model
+- **`integrations/playwright/README.md`** — new section: Visual AI helper optional pattern.
+- **`templates/qa-readme.md`** — new fields: `ADO Project`, `Last Run` summary table,
+  `Flaky Tests` inline annotation convention.
+
+### Changed
+
+- **`scripts/init.js`** — `fixtures/base.ts` added to e2e scaffold copy list; integration
+  scaffold replaces the `integration/README.md` placeholder; memory template files seeded
+  from `templates/memory/` via `fs.readFileSync`.
+- **`scripts/upgrade.js`** — integration scaffold, `disputed/` defect folder, and memory
+  templates are all seeded idempotently on upgrade for existing projects.
+- **`docs/folder-structure-guide.md`** — `06-defects/` updated to document `disputed/`.
+- **`templates/defect-report.md`** — `Status` field extended with `Disputed` value.
+- **`qa/memory/INDEX.md`** template updated to pre-populate rows for the three new memory
+  template files.
 
-### Source repositories
+---
+
+## [1.10.0] - 2026-05-19
 
-This version was bootstrapped from analysis of two existing embedded QA implementations:
+### Added
 
-- `redacted-repo` (Repo A) — ASP.NET MVC 5 + jQuery + toastr + Sprint-based E2E
-- `redacted-repo` (Repo B) — Blazor WebAssembly + Radzen + full ADO pipeline integration
+- **`integrations/ado-powershell/pipelines/azure-pipeline-qa.yml`** — pipeline template
+  significantly expanded:
+  - New **Stage 3: API Integration Tests** — separate stage for `qa/07-automation/integration`,
+    with its own `PublishTestResults` and `PublishPipelineArtifact` tasks.
+  - **Cross-project repository checkout** via `resources.repositories` block; each stage
+    now performs an explicit `checkout: source`.
+  - **Smoke test step** in the E2E stage — validates `QA_BASE_URL` is reachable via `curl`
+    before running the suite.
+  - **Commented placeholder** for `AzureCLI@2` login task (Playwright Workspaces / Entra ID)
+    in both E2E and API stages, with `PLAYWRIGHT_SERVICE_URL` env var placeholder.
+  - Optional nightly schedule block (commented out).
+  - `PublishPipelineArtifact` tasks for HTML report and trace artifacts in both stages.
+- **`integrations/playwright-azure-reporter/README.md`** — fully rewritten:
+  - Variables split into local (PAT) vs CI/CD (`SYSTEM_ACCESSTOKEN`) sections.
+  - Config snippet updated to use `ADO_ORG`, `ADO_PROJECT`, `orgUrl` constructed from
+    `ADO_ORG`, and `SYSTEM_ACCESSTOKEN ?? AZURE_TOKEN` token fallback.
+  - New **Playwright Workspaces reporter** section (`@azure/playwright` +
+    `playwright.service.config.ts` + Entra ID authentication notes).
+  - Troubleshooting table expanded with pipeline-specific `401` scenario.
 
-All project-specific content (URLs, ADO IDs, user credentials, module names, form selectors)
-has been removed or parameterized. See `docs/comparison-matrix.md` and `docs/generalization-decisions.md`.
+### Changed
+
+- **`azure-pipeline-qa.yml`** — variable names aligned with current conventions:
+  `AZURE_TOKEN` / `ADO_ORG_URL` / `ADO_PROJECT_NAME` replaced by `ADO_ORG` / `ADO_PROJECT`;
+  `ADO_PLAN_ID` split into `ADO_E2E_PLAN_ID` / `ADO_API_PLAN_ID`; `SYSTEM_ACCESSTOKEN`
+  replaces PAT for ADO reporter authentication.
+- **`azure-pipeline-qa.yml`** — E2E job `timeoutInMinutes` increased from 60 to 90.
+- **`azure-pipeline-qa.yml`** — trigger reduced to `main` only (removed `qa` and
+  `release/*` branches); trigger rationale documented in comments.
+- **`azure-pipeline-qa.yml`** — E2E test run consolidated from two `@grep`-tag steps
+  (P0 + P1/P2) into a single `--grep-invert "_inspect|_diag"` run with `continueOnError: true`.
+- **`azure-pipeline-qa.yml`** — cache target changed from `~/.cache/ms-playwright` to
+  `node_modules` per workspace; `cacheHitVar` added to both cache tasks.
+- **`azure-pipeline-qa.yml`** — `pool` block moved above `variables` for readability;
+  `ADO_SYNC_DISABLED` variable removed.
 
 ---
 
@@ -258,3 +330,18 @@ See `MIGRATION-NOTES.md` — section "Upgrading from a version that used `.githu
 
 ---
 
+## [1.0.0] - 2026-03-04
+
+### Added
+
+- **Framework scaffold** — initial `qa/` directory tree with 9 numbered folders (00–08)
+- **6-file submodule template set** — `00-inventory` through `05-test-scenarios`
+- **Agent instructions** — 7 purpose-specific Markdown instruction files for IDE agents
+- **Standards** — naming conventions, bug report template, test case template, test data guidelines
+- **Automation scaffold** — generalized Playwright `playwright.config.ts`, `global-setup.ts`, `.env.example`, `fixtures/auth.ts`
+- **Optional integrations** — stubs and READMEs for Playwright, `playwright-azure-reporter`, and ADO PowerShell
+- **CLI entry point** — `qa-framework init`, `generate`, `validate` commands
+- **Documentation** — architecture, comparison matrix, generalization decisions, installation guide, usage-with-agent guide, spec-driven philosophy, folder structure guide
+- **Migration notes** — `MIGRATION-NOTES.md` for projects moving from embedded to package-based framework
+
+---

package/README.md

@@ -1,7 +1,7 @@
 # qa-framework
 
 > Reusable, installable, agent-oriented QA framework for spec-driven automated testing.
-> Current version: **v1.9.0**
+> Current version: **v1.10.0**
 
 ---
 

package/docs/folder-structure-guide.md

@@ -260,10 +260,16 @@ Each skill folder contains:
 ├── README.md
 ├── open/
 │   └── DEF-{NNN}-{slug}.md
+├── disputed/
+│   └── DEF-{NNN}-{slug}.md
 └── resolved/
     └── DEF-{NNN}-{slug}.md
 ```
 
+- `open/` - confirmed defect, fix pending
+- `disputed/` - QA has evidence but business or dev team disputes the expected behavior; pending functional decision
+- `resolved/` - closed by fix or formal decision
+
 **Decision guide**:
 - ADO enabled → use ADO Work Items. `06-defects/` contains lightweight references only
 - ADO disabled → use this folder as primary defect tracker

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

@@ -1,133 +1,345 @@
 # -----------------------------------------------------------------------
-# keber/qa-framework — Azure Pipeline QA Template
+# keber/qa-framework - Azure Pipeline QA Template
 # -----------------------------------------------------------------------
-# Parameterized CI pipeline for running Playwright E2E tests and
-# optionally syncing results to Azure DevOps Test Plans.
+# Parameterized CI pipeline for running Playwright E2E and API tests and
+# syncing results to Azure DevOps Test Plans via SYSTEM_ACCESSTOKEN.
+#
+# Cross-project repository: the test repo lives in a different ADO project.
+# Update 'resources.repositories.name' to match your org/project/repo.
 #
 # 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
+# Create this group in ADO -> Pipelines -> Library and add the following:
+#
+#   QA_BASE_URL          - Target application URL  (e.g. https://app-qa.example.com)
+#   QA_USER_EMAIL        - Test user email / RUT
+#   QA_USER_PASSWORD     - Test user password                        [secret]
+#   ADO_ORG              - ADO organization slug  (e.g. my-org)
+#   ADO_PROJECT          - ADO project name        (e.g. my-project)
+#   ADO_E2E_PLAN_ID      - Test Plan ID for the E2E suite
+#   ADO_API_PLAN_ID      - Test Plan ID for the API/integration suite
+#
+#   NOTE on multiple Plan IDs: ADO variable groups store plain strings - there
+#   is no array type. Use one variable per suite (ADO_E2E_PLAN_ID / ADO_API_PLAN_ID).
+#   If the project has only one suite, a single ADO_PLAN_ID variable is enough.
+#   Results are reported to ADO via System.AccessToken (OAuth); no PAT required.
 # -----------------------------------------------------------------------
 
+# Cross-project repository - update <ADO_SOURCE_PROJECT>/<REPO_NAME> as needed
+resources:
+  repositories:
+    - repository: source
+      type: git
+      name: <ADO_SOURCE_PROJECT>/<REPO_NAME>   # e.g. my-qa-project/my-repo
+      ref: refs/heads/main
+
+# Trigger: push and PR to main.
+# The test repo is decoupled from the app repo, so branch triggers are minimal.
 trigger:
   branches:
     include:
       - main
-      - qa
-      - release/*
 
 pr:
   branches:
     include:
       - main
 
+# Optional scheduled run - uncomment and adjust if a nightly regression is needed:
+# schedules:
+#   - cron: '0 6 * * 1-5'   # 06:00 UTC Mon-Fri (03:00 CLT / 02:00 CLST)
+#     displayName: Nightly regression
+#     branches:
+#       include:
+#         - main
+#     always: true
+
+# -----------------------------------------------------------------------
+# Pipeline parameters
+# -----------------------------------------------------------------------
+# suiteFilter controls which tests run when the pipeline is triggered manually
+# or from a PR. Scheduled runs always override this to 'all' automatically
+# (see the "Resolve suite filter" step in each test job).
+#
+# Default is 'all' so a plain manual run executes the full suite.
+# Override at queue time to run a subset (e.g. 'smoke', '[P0]', 'login').
+#
+# The value is passed to Playwright via --grep. Special regex characters such
+# as '[' and ']' are escaped by the bash array pattern in the run step, so
+# values like '[P0]' are safe.
+parameters:
+  - name: suiteFilter
+    displayName: 'Test suite filter (grep pattern, or "all" to skip filtering)'
+    type: string
+    default: 'all'
+
+pool:
+  vmImage: 'ubuntu-latest'
+
 variables:
   - group: QA-Variables
   - name: NODE_VERSION
     value: '20.x'
-  - name: QA_DIR
+  - name: E2E_DIR
     value: 'qa/07-automation/e2e'
-  - name: ADO_SYNC_DISABLED
-    value: 'false'
-
-pool:
-  vmImage: 'ubuntu-latest'
+  - name: API_DIR
+    value: 'qa/07-automation/integration'
 
 stages:
   # -----------------------------------------------------------------------
-  # Stage 1: Install & Setup
+  # Stage 1: Install & cache dependencies
   # -----------------------------------------------------------------------
   - stage: Setup
     displayName: 'Install Dependencies'
     jobs:
       - job: Install
-        displayName: 'npm install + Playwright browsers'
+        displayName: 'npm ci + Playwright browsers'
         steps:
+          - checkout: source
+            displayName: 'Checkout source repo'
+
           - task: NodeTool@0
             inputs:
               versionSpec: $(NODE_VERSION)
             displayName: 'Use Node.js $(NODE_VERSION)'
 
           - script: |
-              cd $(QA_DIR)
+              cd $(E2E_DIR)
               npm ci
               npx playwright install chromium --with-deps
-            displayName: 'Install npm deps and Playwright Chromium'
+            displayName: 'Install E2E deps and Playwright Chromium'
+
+          - task: CacheBeta@1
+            inputs:
+              key: 'e2e | "$(Agent.OS)" | $(E2E_DIR)/package-lock.json'
+              path: '$(E2E_DIR)/node_modules'
+              cacheHitVar: 'CACHE_RESTORED_E2E'
+            displayName: 'Cache E2E node_modules'
+
+          - script: |
+              cd $(API_DIR)
+              npm ci
+            displayName: 'Install API deps'
 
           - task: CacheBeta@1
             inputs:
-              key: 'playwright | "$(Agent.OS)" | $(QA_DIR)/package-lock.json'
-              path: '~/.cache/ms-playwright'
-            displayName: 'Cache Playwright browsers'
+              key: 'api | "$(Agent.OS)" | $(API_DIR)/package-lock.json'
+              path: '$(API_DIR)/node_modules'
+              cacheHitVar: 'CACHE_RESTORED_API'
+            displayName: 'Cache API node_modules'
 
   # -----------------------------------------------------------------------
-  # Stage 2: E2E Tests
+  # Stage 2: E2E Tests (Playwright/Chromium)
+  # -----------------------------------------------------------------------
+  # Single-job configuration. For parallel execution with two test users,
+  # split this into two jobs and set QA_AUTH_USER per job:
+  #
+  #   - job: E2E_User1
+  #     variables:
+  #       QA_AUTH_USER: '1'
+  #     ...
+  #   - job: E2E_User2
+  #     variables:
+  #       QA_AUTH_USER: '2'
+  #     ...
+  #
+  # Each job must use a distinct Playwright project (--project=chromium-user1 /
+  # --project=chromium-user2) to avoid session conflicts between parallel users.
   # -----------------------------------------------------------------------
   - stage: E2E
-    displayName: 'E2E Tests'
+    displayName: 'E2E Tests (Playwright/Chromium)'
     dependsOn: Setup
     jobs:
-      - job: PlaywrightTests
-        displayName: 'Run Playwright suite'
-        timeoutInMinutes: 60
+      - job: PlaywrightE2E
+        displayName: 'Run E2E suite'
+        timeoutInMinutes: 90
         steps:
+          - checkout: source
+            displayName: 'Checkout source repo'
+
           - task: NodeTool@0
             inputs:
               versionSpec: $(NODE_VERSION)
+            displayName: 'Use Node.js $(NODE_VERSION)'
 
           - script: |
-              cd $(QA_DIR)
+              cd $(E2E_DIR)
               npm ci
               npx playwright install chromium --with-deps
-            displayName: 'Restore dependencies'
+            displayName: 'Restore E2E dependencies'
+
+          - script: |
+              echo "QA_BASE_URL = $(QA_BASE_URL)"
+              HTTP_CODE=$(curl -o /dev/null -s -w "%{http_code}" --max-time 30 "$(QA_BASE_URL)")
+              echo "HTTP response: $HTTP_CODE"
+              if [ "$HTTP_CODE" -lt 200 ] || [ "$HTTP_CODE" -ge 400 ]; then
+                echo "##[error]Smoke test failed - $(QA_BASE_URL) returned HTTP $HTTP_CODE"
+                exit 1
+              fi
+              echo "Smoke test passed (HTTP $HTTP_CODE)"
+            displayName: 'Smoke test - verify QA_BASE_URL is reachable'
+
+          # ---------------------------------------------------------------
+          # Playwright Workspaces (Azure App Testing)
+          # Enable once the ADO service connection is configured.
+          # Prerequisite: the service connection must have the Contributor
+          # role on the workspace in Azure Portal (Access control IAM).
+          # ---------------------------------------------------------------
+          # - task: AzureCLI@2
+          #   displayName: 'Login to Azure (Playwright Workspaces)'
+          #   inputs:
+          #     azureSubscription: '<AZURE_SERVICE_CONNECTION_NAME>'
+          #     scriptType: bash
+          #     scriptLocation: inlineScript
+          #     inlineScript: echo "Authenticated via Entra ID"
 
           - script: |
-              cd $(QA_DIR)
-              npx playwright test --grep @P0
-            displayName: 'Run P0 smoke suite'
+              # Scheduled runs always execute the full suite, regardless of the
+              # suiteFilter parameter. This prevents accidental partial runs in
+              # nightly regressions when the parameter was changed by a prior
+              # manual queue.
+              SUITE_FILTER="${{ parameters.suiteFilter }}"
+              if [ "$(Build.Reason)" = "Schedule" ]; then
+                SUITE_FILTER="all"
+                echo "Scheduled run detected - overriding suiteFilter to 'all'"
+              fi
+              echo "Effective suiteFilter: $SUITE_FILTER"
+
+              # Build --grep args as a bash array to safely handle patterns that
+              # contain special regex characters such as '[' and ']'. Inline
+              # string interpolation would break those patterns at the shell level.
+              GREP_ARGS=()
+              if [ "$SUITE_FILTER" != "all" ]; then
+                GREP_ARGS=(--grep "$SUITE_FILTER")
+              fi
+
+              cd $(E2E_DIR)
+              npx playwright test --project=chromium --ignore-snapshots \
+                --grep-invert "_inspect|_diag" "${GREP_ARGS[@]}"
+            displayName: 'Run E2E tests'
+            continueOnError: true
             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'
+              QA_BASE_URL:        $(QA_BASE_URL)
+              QA_USER_EMAIL:      $(QA_USER_EMAIL)
+              QA_USER_PASSWORD:   $(QA_USER_PASSWORD)
+              ADO_ORG:            $(ADO_ORG)
+              ADO_PROJECT:        $(ADO_PROJECT)
+              ADO_PLAN_ID:        $(ADO_E2E_PLAN_ID)
+              SYSTEM_ACCESSTOKEN: $(System.AccessToken)
+              CI:                 'true'
+              # QA_AUTH_USER: '1'  # Set explicitly when running parallel jobs (user-1 / user-2 model)
+              # PLAYWRIGHT_SERVICE_URL: $(PLAYWRIGHT_SERVICE_URL)  # Playwright Workspaces endpoint - enable together with the login task
+
+          # publishRunAttachments is false because screenshots and traces are
+          # already uploaded as pipeline artifacts below. Setting it to true
+          # would double-publish the same files.
+          - task: PublishTestResults@2
+            condition: always()
+            inputs:
+              testResultsFormat:     'JUnit'
+              testResultsFiles:      'test-results/junit-results.xml'
+              searchFolder:          $(E2E_DIR)
+              mergeTestResults:      true
+              publishRunAttachments: false
+              failTaskOnFailedTests: true
+              testRunTitle:          '[Auto E2E] $(Build.BuildNumber)'
+            displayName: 'Publish E2E test results (JUnit)'
+
+          # Artifact names include $(System.JobAttempt) to avoid name collisions
+          # when the job is retried. ADO rejects duplicate artifact names within
+          # the same pipeline run, so without the suffix a retry always fails at
+          # the publish step.
+          - task: PublishPipelineArtifact@1
+            condition: always()
+            inputs:
+              targetPath: '$(E2E_DIR)/playwright-report'
+              artifact:   'e2e-playwright-report-attempt-$(System.JobAttempt)'
+            displayName: 'Publish E2E HTML report'
+
+          - task: PublishPipelineArtifact@1
+            condition: always()
+            inputs:
+              targetPath: '$(E2E_DIR)/test-results'
+              artifact:   'e2e-test-results-attempt-$(System.JobAttempt)'
+            displayName: 'Publish E2E trace artifacts'
+
+  # -----------------------------------------------------------------------
+  # Stage 3: API Integration Tests
+  # -----------------------------------------------------------------------
+  - stage: API
+    displayName: 'API Integration Tests'
+    dependsOn: E2E
+    jobs:
+      - job: PlaywrightAPI
+        displayName: 'Run API suite'
+        timeoutInMinutes: 30
+        steps:
+          - checkout: source
+            displayName: 'Checkout source repo'
+
+          - task: NodeTool@0
+            inputs:
+              versionSpec: $(NODE_VERSION)
+            displayName: 'Use Node.js $(NODE_VERSION)'
 
           - script: |
-              cd $(QA_DIR)
-              npx playwright test --grep "@P1|@P2"
-            displayName: 'Run P1/P2 regression suite'
-            condition: succeededOrFailed()
+              cd $(API_DIR)
+              npm ci
+            displayName: 'Restore API dependencies'
+
+          # ---------------------------------------------------------------
+          # Playwright Workspaces (Azure App Testing)
+          # Enable once the ADO service connection is configured.
+          # ---------------------------------------------------------------
+          # - task: AzureCLI@2
+          #   displayName: 'Login to Azure (Playwright Workspaces)'
+          #   inputs:
+          #     azureSubscription: '<AZURE_SERVICE_CONNECTION_NAME>'
+          #     scriptType: bash
+          #     scriptLocation: inlineScript
+          #     inlineScript: echo "Authenticated via Entra ID"
+
+          - script: |
+              # API integration tests do not use suite tags - always run all.
+              cd $(API_DIR)
+              npx playwright test --grep-invert "_inspect|_diag"
+            displayName: 'Run API integration tests'
+            continueOnError: true
             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'
+              QA_BASE_URL:        $(QA_BASE_URL)
+              QA_USER_EMAIL:      $(QA_USER_EMAIL)
+              QA_USER_PASSWORD:   $(QA_USER_PASSWORD)
+              ADO_ORG:            $(ADO_ORG)
+              ADO_PROJECT:        $(ADO_PROJECT)
+              ADO_PLAN_ID:        $(ADO_API_PLAN_ID)
+              SYSTEM_ACCESSTOKEN: $(System.AccessToken)
+              CI:                 'true'
+              # PLAYWRIGHT_SERVICE_URL: $(PLAYWRIGHT_SERVICE_URL)  # Playwright Workspaces endpoint - enable together with the login task
 
+          # publishRunAttachments is false because trace artifacts are already
+          # uploaded as pipeline artifacts below.
           - 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'
+              testResultsFormat:     'JUnit'
+              testResultsFiles:      'test-results/junit-results.xml'
+              searchFolder:          $(API_DIR)
+              mergeTestResults:      true
+              publishRunAttachments: false
+              failTaskOnFailedTests: true
+              testRunTitle:          '[Auto API] $(Build.BuildNumber)'
+            displayName: 'Publish API test results (JUnit)'
+
+          # Artifact names include $(System.JobAttempt) to prevent collision on retries.
+          - task: PublishPipelineArtifact@1
+            condition: always()
+            inputs:
+              targetPath: '$(API_DIR)/playwright-report'
+              artifact:   'api-playwright-report-attempt-$(System.JobAttempt)'
+            displayName: 'Publish API HTML report'
 
-          - task: PublishBuildArtifacts@1
+          - task: PublishPipelineArtifact@1
             condition: always()
             inputs:
-              pathToPublish: '$(QA_DIR)/playwright-report'
-              artifactName:  'playwright-report'
-            displayName: 'Publish Playwright HTML report'
+              targetPath: '$(API_DIR)/test-results'
+              artifact:   'api-test-results-attempt-$(System.JobAttempt)'
+            displayName: 'Publish API trace artifacts'