@msalaam/xray-qe-toolkit 1.2.0 → 1.3.0

package/README.md

@@ -11,6 +11,7 @@
 - [Installation](#installation)
 - [AI Setup (Optional)](#ai-setup-optional)
 - [Quick Start](#quick-start)
+- [Playwright Quick Start](#playwright-quick-start)
 - [CLI Commands](#cli-commands)
   - [init](#xray-qe-init)
   - [gen-tests](#xray-qe-gen-tests)
@@ -421,23 +422,51 @@ npx xqt create-execution --summary "Feature XYZ" --issue QE-123
 
 Import test results into Xray Cloud. Supports JUnit XML and Playwright JSON formats. Designed for CI — no human interaction.
 
-**JUnit XML (JUnit, Newman, etc.):**
+#### Format Comparison
+
+| Feature | JUnit XML | Playwright JSON |
+|---------|-----------|----------------|
+| **Update existing tests** | ❌ No - always creates new tests | ✅ Yes - via annotations |
+| **Test key mapping** | ❌ Not supported | ✅ `test.info().annotations` |
+| **Attachments/Evidence** | ❌ Not supported | ✅ Supported |
+| **Best for** | Newman, generic test runners | Playwright tests |
+| **Recommendation** | ⚠️ Use only for tools without test keys | ✅ **Recommended for Playwright** |
+
+#### JUnit XML (Newman, generic test runners)
+
+⚠️ **Important:** JUnit XML **cannot update existing Xray tests** - it will always create new test cases. Only use this for Newman or test runners that don't support test keys.
+
 ```bash
 npx xqt import-results --file results.xml --testExecKey QE-123
 ```
 
-**Playwright JSON:**
+#### Playwright JSON (Recommended)
+
+✅ **Updates existing tests** via annotations. Use this format to link results to your existing Xray test cases.
+
 ```bash
 # Generate JSON report in Playwright
 npx playwright test --reporter=json > playwright-results.json
 
-# Import to Xray (links to existing tests or creates new ones)
+# Import to Xray (updates existing tests via annotations)
 npx xqt import-results --file playwright-results.json --testExecKey QE-123
 
 # Create new Test Execution automatically
 npx xqt import-results --file playwright-results.json --summary "Regression Suite"
 ```
 
+**Required test code:**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('Verify API endpoint', async ({ request }) => {
+  // THIS LINE links to existing Xray test
+  test.info().annotations.push({ type: 'xray', description: 'PROJ-123' });
+  
+  // Your test code...
+});
+```
+
 | Option                      | Description                                       | Required |
 |-----------------------------|---------------------------------------------------|----------|
 | `--file <path>`             | Path to results file (.xml or .json)             | Yes      |
@@ -449,22 +478,28 @@ npx xqt import-results --file playwright-results.json --summary "Regression Suit
 
 **Mapping Playwright Tests to Xray:**
 
-To link Playwright test results to existing Xray test cases, use annotations or include test keys in titles:
+To link Playwright test results to existing Xray test cases, **you must use annotations**:
 
 ```typescript
-// Option 1: Using annotations (recommended)
+// ✅ CORRECT - Updates existing test PROJ-123
 test('User login flow', async ({ page }) => {
   test.info().annotations.push({ type: 'xray', description: 'PROJ-123' });
   // ... test code
 });
 
-// Option 2: Include test key in title
+// ✅ Alternative - Include test key in title
 test('[PROJ-456] User registration validates email', async ({ page }) => {
   // ... test code
 });
+
+// ❌ WRONG - Creates new test every time
+test('User login flow', async ({ page }) => {
+  // Missing annotation - will create duplicate test!
+  // ... test code
+});
 ```
 
-If no test key is found, a new test will be created in Xray with the test title as the summary.
+**Without annotations:** A new test will be created in Xray with the test title as the summary (not recommended for existing tests).
 
 ---
 
@@ -720,33 +755,176 @@ Use this checklist to align a new team's board and Xray configuration with the t
 └─────────────────────────────────────────────────────────────────────────┘
 ```
 
-### Playwright Integration Workflow
+## Playwright Quick Start
 
-For teams using Playwright for API or E2E testing:
+### Complete Setup for Updating Existing Xray Tests
+
+This is the **recommended workflow** for teams using Playwright with existing Xray test cases.
+
+#### Step 1: Install Playwright (in your test repo)
 
 ```bash
-# 1. Write Playwright tests with Xray annotations
-# tests/login.spec.ts
-test('User login with valid credentials', async ({ page }) => {
-  test.info().annotations.push({ type: 'xray', description: 'PROJ-123' });
-  // ... test implementation
+npm install --save-dev @playwright/test
+```
+
+#### Step 2: Configure Playwright
+
+Create `playwright.config.ts` in your test repo:
+
+```typescript
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  reporter: [
+    ['html'],  // For local viewing
+    ['json', { outputFile: 'playwright-results.json' }],  // For Xray import
+  ],
+  
+  use: {
+    baseURL: process.env.API_BASE_URL || 'https://your-api.com',
+    extraHTTPHeaders: {
+      'Authorization': `Bearer ${process.env.API_TOKEN}`,
+      'X-API-Key': process.env.API_KEY || '',
+    },
+  },
 });
+```
 
-# 2. Run tests and generate JSON report
-npx playwright test --reporter=json > playwright-results.json
+#### Step 3: Write Tests with Xray Annotations
 
-# 3. Import results to Xray (links to existing tests or creates new)
-npx xqt import-results --file playwright-results.json --testExecKey PROJ-456
+⚠️ **Critical:** Every test MUST have an annotation to update existing Xray tests.
 
-# Or create new execution automatically
-npx xqt import-results --file playwright-results.json --summary "Playwright Regression"
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Regression Tests', () => {
+  
+  test('Verify API returns 200 for valid request', async ({ request }) => {
+    // THIS LINE links to your existing Xray test
+    test.info().annotations.push({ type: 'xray', description: 'APIEE-7131' });
+    
+    const response = await request.post('/api/verify', {
+      data: { userId: '123', action: 'validate' }
+    });
+    
+    // Attach response as evidence for Xray
+    test.info().attach('response-evidence', {
+      body: JSON.stringify({
+        status: response.status(),
+        headers: response.headers(),
+        body: await response.json()
+      }, null, 2),
+      contentType: 'application/json'
+    });
+    
+    expect(response.status()).toBe(200);
+  });
+  
+  test('Verify API returns 400 for invalid data', async ({ request }) => {
+    test.info().annotations.push({ type: 'xray', description: 'APIEE-7132' });
+    // ... test implementation
+  });
+  
+});
 ```
 
-**Benefits:**
-- Automatically maps Playwright tests to Xray test cases using annotations or `[TEST-123]` in titles
-- Creates new test cases in Xray if no mapping found
-- Supports Playwright retries, worker info, and detailed error reporting
-- Works in CI/CD pipelines for continuous test reporting
+#### Step 4: Map All Your Tests
+
+Based on your `xray-mapping.json`, add annotations to each test:
+
+```typescript
+// If your xray-mapping.json shows:
+// "TC-001": { "key": "APIEE-7131", "id": "1879092" }
+// "TC-002": { "key": "APIEE-7132", "id": "1879095" }
+
+test('Test Case 1', async ({ request }) => {
+  test.info().annotations.push({ type: 'xray', description: 'APIEE-7131' });
+  // ...
+});
+
+test('Test Case 2', async ({ request }) => {
+  test.info().annotations.push({ type: 'xray', description: 'APIEE-7132' });
+  // ...
+});
+```
+
+#### Step 5: Run Locally
+
+```bash
+# Run tests
+npx playwright test
+
+# View HTML report
+npx playwright show-report
+
+# Upload to Xray (updates existing tests)
+npx xqt import-results --file playwright-results.json --testExecKey APIEE-6811
+```
+
+#### Step 6: Configure CI/CD
+
+**Azure Pipelines:**
+
+```yaml
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: '18.x'
+
+  - script: npm ci
+    displayName: 'Install dependencies'
+
+  - script: npx playwright test
+    displayName: 'Run Playwright tests'
+    continueOnError: true
+
+  - script: |
+      npx xqt import-results \
+        --file playwright-results.json \
+        --testExecKey APIEE-6811
+    displayName: 'Upload results to Xray'
+    env:
+      XRAY_ID: $(XRAY_ID)
+      XRAY_SECRET: $(XRAY_SECRET)
+      JIRA_PROJECT_KEY: $(JIRA_PROJECT_KEY)
+      JIRA_URL: $(JIRA_URL)
+      JIRA_API_TOKEN: $(JIRA_API_TOKEN)
+      JIRA_EMAIL: $(JIRA_EMAIL)
+```
+
+**GitHub Actions:**
+
+```yaml
+steps:
+  - uses: actions/setup-node@v3
+    with:
+      node-version: '18'
+
+  - run: npm ci
+
+  - run: npx playwright test
+
+  - run: |
+      npx xqt import-results \
+        --file playwright-results.json \
+        --testExecKey APIEE-6811
+    env:
+      XRAY_ID: ${{ secrets.XRAY_ID }}
+      XRAY_SECRET: ${{ secrets.XRAY_SECRET }}
+      JIRA_PROJECT_KEY: ${{ secrets.JIRA_PROJECT_KEY }}
+      JIRA_URL: ${{ secrets.JIRA_URL }}
+      JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
+      JIRA_EMAIL: ${{ secrets.JIRA_EMAIL }}
+```
+
+### Benefits
+
+✅ **Updates existing tests** - No duplicate test creation  
+✅ **Automatic mapping** - Via annotations in test code  
+✅ **Evidence attachments** - Screenshots, responses, traces  
+✅ **Detailed reporting** - Retries, worker info, error details  
+✅ **CI/CD ready** - Standard workflow for automation  
+✅ **Single source of truth** - Test code + Xray together
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msalaam/xray-qe-toolkit",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Full QE workflow toolkit for Xray Cloud integration — test management, Postman generation, CI pipeline scaffolding, and browser-based review gates for API regression projects.",
   "type": "module",
   "bin": {