@keber/qa-framework 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -33,6 +33,37 @@ has been removed or parameterized. See `docs/comparison-matrix.md` and `docs/gen
 
 ---
 
+## [1.9.0] - 2026-05-15
+
+### Changed
+
+- **`create-testplan-from-mapping.ps1` refactored** — removed all ADO-specific logic (auth headers,
+  `Invoke-RestMethod` calls, XML step construction). The script now delegates to `New-AdoTestCase`
+  and `Add-AdoTestCaseToSuite` from `@keber/ado-powershell`, keeping `qa-framework` free of
+  ADO implementation details. Requires `@keber/ado-powershell` ≥ 1.3.0.
+- **Script parameters simplified** — `-OrgUrl`, `-ProjectName`, and `-Token` removed from
+  `create-testplan-from-mapping.ps1`. Caller is responsible for loading the ADO session via
+  `. .github/skills/ado-powershell/load.ps1` before invoking the script.
+- **`tc-mapping.json` schema extended** — added optional `steps` (string array) and
+  `expectedResult` (string) fields per test case. When present, steps are sent to ADO as
+  `Microsoft.VSTS.TCM.Steps`; all steps except the last are `ActionStep`, the last is
+  `ValidateStep` with `expectedResult`.
+- **`qa-ado-integration` SKILL.md updated** — Step 3 now specifies exactly how to parse the
+  Tabla de Pruebas columns (`Steps` split on `<br>`, strip numbering prefix) to produce
+  `tc-mapping.json` with steps.
+
+### Added
+
+- **Guard in `create-testplan-from-mapping.ps1`** — fails fast with a clear message if
+  `New-AdoTestCase` is not available (ADO session not loaded).
+
+### Requires
+
+- `@keber/ado-powershell` ≥ **1.3.0** — adds `$ExpectedResult` parameter to `New-AdoTestCase`
+  and `ValidateStep` support in the generated TCM steps XML.
+
+---
+
 ## [1.8.0] - 2026-05-07
 
 ### Changed

package/README.md

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

package/integrations/ado-powershell/README.md

@@ -15,19 +15,20 @@ All scripts are parameterized and project-agnostic.
 ## 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
+- `@keber/ado-powershell` skill installed and loaded (provides `New-AdoTestCase`, `Add-AdoTestCaseToSuite`, etc.)
+- Azure DevOps Personal Access Token (PAT) with `Work Items: Read & Write` and `Test Management: Read & Write` scopes
+- PAT and org/project set as env vars: `ADO_PAT`, `ADO_ORG`, `ADO_PROJECT`
 
 ## Quick start
 
 ```powershell
-# 1. Generate ado-ids.json mapping (from your TC mapping file)
+# 0. Load the ADO skill (initialises session from env vars)
+. .github/skills/ado-powershell/load.ps1
+
+# 1. Create Test Cases in ADO from tc-mapping.json
 .\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
+  -MappingFile "qa/08-azure-integration/tc-mapping.json"
 
 # 2. Inject ADO IDs into spec files (idempotent)
 .\scripts\inject-ado-ids.ps1 `
@@ -59,12 +60,36 @@ npx playwright test
   "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" }
+    {
+      "localId": "TC-SUP-CR-001",
+      "title": "Create supplier @P0",
+      "specFile": "suppliers/create.spec.ts",
+      "steps": [
+        "Navigate to /suppliers/new",
+        "Fill in required fields: Name, RUT, Email",
+        "Click 'Save'"
+      ],
+      "expectedResult": "Supplier is created and appears in the list with status Active"
+    },
+    {
+      "localId": "TC-SUP-CR-002",
+      "title": "Create supplier - required fields @P0",
+      "specFile": "suppliers/create.spec.ts",
+      "steps": [
+        "Navigate to /suppliers/new",
+        "Leave required fields empty",
+        "Click 'Save'"
+      ],
+      "expectedResult": "Validation errors appear for each required field; record is not saved"
+    }
   ]
 }
 ```
 
+> **`steps`** (optional): Array of step strings. Each entry becomes one ADO step. All steps except the last are `ActionStep`; the last is `ValidateStep` and receives `expectedResult`.
+> **`expectedResult`** (optional): Overall expected result, applied to the last step. If omitted, the last step has an empty expected result.
+> If `steps` is absent or empty, the Test Case is created with title only (no steps).
+
 ## File: ado-ids.json (output after create-testplan)
 
 ```json

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

@@ -7,17 +7,16 @@
     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.
+    Requires an active ADO session. Call:
+        . .github/skills/ado-powershell/load.ps1
+    before running this script. The session is initialised automatically by
+    load.ps1 when ADO_ORG, ADO_PROJECT and ADO_PAT env vars are set.
 
 .PARAMETER PlanId
     ADO Test Plan ID.
 
 .PARAMETER SuiteId
-    ADO Test Suite ID. If omitted, uses the plan's root suite.
+    ADO Test Suite ID. If omitted, uses the suiteId from tc-mapping.json.
 
 .PARAMETER MappingFile
     Path to tc-mapping.json input file.
@@ -25,43 +24,33 @@
 .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
+    . .github/skills/ado-powershell/load.ps1
     .\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
+        -MappingFile "qa/08-azure-integration/tc-mapping.json"
 #>
 [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
+    [string]                        $OutputFile = ''
 )
 
 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'
+# Verify ADO session is available
+if (-not (Get-Command 'New-AdoTestCase' -ErrorAction SilentlyContinue)) {
+    Write-Error "ADO session not loaded. Run: . .github/skills/ado-powershell/load.ps1"
+    exit 1
 }
 
 # 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"
@@ -69,29 +58,25 @@ Write-Host "[create-testplan] Creating $($mapping.testCases.Count) test cases in
 $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"
+    $steps          = if ($tc.PSObject.Properties['steps'])          { $tc.steps          } else { @() }
+    $expectedResult = if ($tc.PSObject.Properties['expectedResult']) { $tc.expectedResult  } else { ''  }
 
     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
+            $splatArgs = @{
+                Title   = "[$($tc.localId)] $($tc.title)"
+                Confirm = $false
+            }
+            if ($steps.Count -gt 0) {
+                $splatArgs.Steps          = $steps
+                $splatArgs.ExpectedResult = $expectedResult
+            }
 
+            $wi   = New-AdoTestCase @splatArgs
             $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
+            Add-AdoTestCaseToSuite -PlanId $PlanId -SuiteId $suiteId -TestCaseIds @($wiId) -Confirm:$false
 
             $results += [PSCustomObject]@{
                 localId  = $tc.localId

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keber/qa-framework",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Reusable spec-driven QA framework for IDE-agent-assisted automated testing. Installable as an npm package. Provides structure, templates, agent instructions, and optional integrations for Playwright and Azure DevOps.",
   "keywords": [
     "qa",

package/scripts/init.js

@@ -341,6 +341,40 @@ cd qa/07-automation/e2e && npm install && npx playwright install chromium
 const nextStepsPath = path.join(qaRoot, 'AGENT-NEXT-STEPS.md');
 writeIfMissing(nextStepsPath, nextStepsContent);
 
+// --- Print post-install summary ---
+const playwrightInstalled = fs.existsSync(path.join(cwd, 'node_modules', '@playwright', 'test'));
+const adoQaInstalledFinal = fs.existsSync(path.join(cwd, 'node_modules', '@keber', 'ado-qa'));
+const azureReporterInstalled = fs.existsSync(path.join(cwd, 'node_modules', '@alex_neo', 'playwright-azure-reporter'));
+
+console.log('');
+console.log('  @keber/qa-framework — scaffold complete');
+console.log('  ----------------------------------------');
+console.log('  Installed:');
+console.log('    qa/                    QA directory structure + spec templates');
+console.log('    .github/skills/        QA agent skills (8 stages)');
+console.log('    .github/instructions/  qa-framework.instructions.md');
+console.log('');
+console.log('  Optional integrations:');
+if (playwrightInstalled) {
+  console.log('    [ok] Playwright              @playwright/test');
+} else {
+  console.log('    [ ] Playwright               npm install @playwright/test');
+  console.log('                                 cd qa/07-automation/e2e && npm install && npx playwright install chromium');
+}
+if (adoQaInstalledFinal) {
+  console.log('    [ok] ADO integration         @keber/ado-qa');
+} else {
+  console.log('    [ ] ADO integration          npm install @keber/ado-qa');
+}
+if (azureReporterInstalled) {
+  console.log('    [ok] ADO Playwright reporter (installed)');
+} else {
+  console.log('    [ ] ADO Playwright reporter  npm install @alex_neo/playwright-azure-reporter');
+}
+console.log('');
+console.log('  Next: edit qa/qa-framework.config.json, then read qa/AGENT-NEXT-STEPS.md');
+console.log('');
+
 // -----------------------------------------------------------------------
 // Helpers
 // -----------------------------------------------------------------------

package/templates/automation-scaffold/package.json

@@ -19,6 +19,6 @@
     "dotenv": "^16.0.0"
   },
   "optionalDependencies": {
-    "@alex_neo/playwright-azure-reporter": "^2.0.0"
+    "@alex_neo/playwright-azure-reporter": "^1.20.0"
   }
 }

package/templates/temp-script.ps1

@@ -0,0 +1,74 @@
+function New-AdoTestCase {
+    <#
+    .SYNOPSIS
+      Creates a Test Case work item with optional steps.
+      Wraps New-AdoWorkItem -Type 'Test Case' and handles TCM-specific fields.
+
+    .PARAMETER Title        Title of the Test Case (mandatory).
+    .PARAMETER Steps        Ordered array of plain-text action strings.
+                            Encoded as the XML format required by Microsoft.VSTS.TCM.Steps.
+    .PARAMETER Priority     1 (Critical) | 2 (High) | 3 (Medium) | 4 (Low).
+    .PARAMETER ExtraFields  Hashtable of additional TCM or custom fields.
+
+    .EXAMPLE
+        New-AdoTestCase -Title 'Verify login with valid credentials' `
+            -Steps @('Navigate to /login', 'Enter username and password', 'Click Sign In') `
+            -Priority '2' -AssignedTo 'qa@contoso.com' -Tags 'login; smoke'
+    #>
+    [CmdletBinding(SupportsShouldProcess, ConfirmImpact='Low')]
+    param(
+        [Parameter(Mandatory)][string]$Title,
+        [string]$Description,
+        [string]$AssignedTo,
+        [string]$AreaPath,
+        [string]$IterationPath,
+        [string]$Tags,
+        [ValidateSet('Design','Ready','Closed')]
+        [string]$State,
+        [string[]]$Steps,
+        [ValidateSet('1','2','3','4')]
+        [string]$Priority,
+        [hashtable]$ExtraFields = @{},
+        [string]$Org     = $script:AdoSession.Org,
+        [string]$Project = $script:AdoSession.Project,
+        [string]$ApiV    = $script:AdoSession.ApiV,
+        [hashtable]$Headers = $script:AdoSession.Headers
+    )
+
+    $extra = $ExtraFields.Clone()
+
+    if ($Priority) {
+        $extra['Microsoft.VSTS.Common.Priority'] = $Priority
+    }
+
+    if ($Steps -and $Steps.Count -gt 0) {
+        $stepsXml   = '<steps id="0" last="{0}">' -f $Steps.Count
+        $stepIndex  = 1
+        foreach ($action in $Steps) {
+            $escaped  = [System.Security.SecurityElement]::Escape($action)
+            $stepsXml += '<step id="{0}" type="ActionStep"><parameterizedString isformatted="true">{1}</parameterizedString><parameterizedString isformatted="true"/></step>' -f $stepIndex, $escaped
+            $stepIndex++
+        }
+        $stepsXml += '</steps>'
+        $extra['Microsoft.VSTS.TCM.Steps'] = $stepsXml
+    }
+
+    $splatArgs = @{
+        Type        = 'Test Case'
+        Title       = $Title
+        ExtraFields = $extra
+        Org         = $Org
+        Project     = $Project
+        ApiV        = $ApiV
+        Headers     = $Headers
+    }
+    if ($Description)   { $splatArgs.Description   = $Description   }
+    if ($AssignedTo)    { $splatArgs.AssignedTo    = $AssignedTo    }
+    if ($AreaPath)      { $splatArgs.AreaPath      = $AreaPath      }
+    if ($IterationPath) { $splatArgs.IterationPath = $IterationPath }
+    if ($Tags)          { $splatArgs.Tags          = $Tags          }
+    if ($State)         { $splatArgs.State         = $State         }
+
+    # WhatIf / Confirm propagate automatically via $WhatIfPreference / $ConfirmPreference
+    return New-AdoWorkItem @splatArgs
+}