@appliqation/automation-sdk 2.1.0 → 2.1.1

package/README.md

@@ -1,69 +1,174 @@
-# Appliqation Automation Integration SDK
+# Appliqation Automation SDK
 
-A powerful SDK for integrating test automation results with the Appliqation portal. Supports **Playwright** (v2.0+) with built-in reporters, plus **Cypress and Jest** (coming soon).
+A powerful SDK for integrating Playwright test results with the Appliqation test management portal.
 
-## ✨ Features
+**What it does:**
+- ✅ Automatically creates test runs in Appliqation
+- ✅ Handles browser authentication with JWT tokens
+- ✅ Reports test results (passed/failed/skipped) to your portal
+- ✅ Tracks browser, OS, and device information
+- ✅ Manages test case mappings via UUIDs
 
-- 🎯 **Modern Architecture** - API key authentication, run matrix management
-- 🔧 **Built-in Reporters** - Native Playwright integration (Cypress & Jest in progress)
-- 🆔 **Automatic Run Management** - Creates run matrices with browser/device/OS tracking
-- 📊 **Batch Operations** - Efficient batch result submission
-- 🔄 **Retry Logic** - Built-in retry mechanism for reliability
-- 📝 **Flexible Logging** - Configurable logging levels
-- 🛡️ **Error Handling** - Comprehensive error handling and validation
-- 🎨 **Custom Run Titles** - Set custom test run names via environment variables or config
+**Perfect for:**
+- QA teams running automated regression tests
+- CI/CD pipelines needing test result tracking
+- Teams using Appliqation for test management
 
-## 🚩 Framework Support Status
+---
 
-| Framework | Status | Reporter Available |
-|-----------|--------|-------------------|
-| Playwright | ✅ **Production Ready** | Yes - `@appliqation/playwright` |
-| Cypress | 🚧 **In Development** | Coming in v2.1.0 |
-| Jest | 🚧 **In Development** | Coming in v2.1.0 |
-| Others | ⏳ **Planned** | Use core SDK directly |
+## Prerequisites
 
-## 🚀 Quick Start
+Before you begin, ensure you have:
 
-### Installation
+1. **Node.js 16+** installed
+   ```bash
+   node --version  # Should be v16.0.0 or higher
+   ```
+
+2. **Playwright** installed in your project
+   ```bash
+   npm install @playwright/test
+   ```
+
+3. **Appliqation Account** with:
+   - Access to Appliqation portal
+   - API key (get from your project settings)
+   - Project key (get from your project settings)
+
+---
+
+## Quick Start
+
+Follow these steps in order to integrate the SDK with your Playwright tests.
+
+### Step 1: Install the SDK
+
+Navigate to your Playwright project and install the SDK:
 
 ```bash
-npm install @appliqation/automation-sdk
+npm install @appliqation/automation-sdk dotenv
 ```
 
-### Playwright (Recommended - Production Ready)
+**Why dotenv?** The SDK uses environment variables for configuration, and dotenv loads them from your `.env` file.
+
+---
 
-Add the Appliqation reporter to your `playwright.config.js`:
+### Step 2: Create .env File
+
+Create a `.env` file in your project root with your Appliqation credentials:
+
+**File:** `.env`
+```bash
+# IMPORTANT: No spaces around = signs, no trailing slashes on URLs
+
+APPLIQATION_BASE_URL=https://your-domain.appliqation.com
+APPLIQATION_API_KEY=appq_live_xxxxxxxxxxxxxxxxxxxx
+APPLIQATION_PROJECT_KEY=your-project-key-here
+APPLIQATION_ENVIRONMENT=Your-test-environment-name
+APPLIQATION_RUN_TITLE=Give-name-to-your-testrun
+```
+
+**How to get these values:**
+- `APPLIQATION_BASE_URL` - Your Appliqation portal URL (no trailing slash!)
+- `APPLIQATION_API_KEY` -     Found in your project settings
+- `APPLIQATION_PROJECT_KEY` - Found in your project settings
+- `APPLIQATION_ENVIRONMENT` - Environment name (Local, Staging, Production, etc. Found in your project settings)
+- 
+
+**⚠️ Add .env to .gitignore** to keep credentials secret:
+```bash
+echo ".env" >> .gitignore
+```
+
+---
+
+### Step 3: Update playwright.config.js
+
+Update your Playwright configuration to use the SDK's built-in features:
+
+**File:** `playwright.config.js`
 
 ```javascript
-const { AppliqationReporter } = require('@appliqation/automation-sdk/playwright');
+const { defineConfig } = require('@playwright/test');
+require('dotenv').config();  // Load .env variables
+
+// SDK configuration
+const appliqationConfig = {
+  baseUrl: process.env.APPLIQATION_BASE_URL,
+  apiKey: process.env.APPLIQATION_API_KEY,
+  projectKey: process.env.APPLIQATION_PROJECT_KEY,
+  environment: process.env.APPLIQATION_ENVIRONMENT,
+  title: process.env.APPLIQATION_RUN_TITLE, // Custom run title (optional)
+
+  // Optional settings
+  autoCreateRun: true,           // Automatically create run on test start
+  batchSubmit: true,             // Batch results for efficiency
+  batchSize: 50,                 // Results per batch
+  logOrphans: true,              // Log tests without UUID mappings
+  logLevel: 'INFO'               // INFO, DEBUG, ERROR
+};
+
+module.exports = defineConfig({
+  testDir: './tests',
+
+  // SDK's built-in global setup (handles auth + run creation)
+  globalSetup: require.resolve('@appliqation/automation-sdk/playwright/global-setup'),
+  globalTeardown: require.resolve('@appliqation/automation-sdk/playwright/global-teardown'),
+
+  use: {
+    baseURL: process.env.APPLIQATION_BASE_URL,
+
+    // Use SDK-managed authentication state
+    storageState: '.auth/jwt.json',
+
+    // Ignore HTTPS errors for local development
+    ignoreHTTPSErrors: true,
+  },
 
-module.exports = {
   reporter: [
-    ['list'],
-    [AppliqationReporter, {
-      baseUrl: process.env.APPLIQATION_BASE_URL,
-      apiKey: process.env.APPLIQATION_API_KEY,
-      projectKey: process.env.APPLIQATION_PROJECT_KEY,
-      scenarioId: parseInt(process.env.APPLIQATION_SCENARIO_ID),
-      environment: process.env.APPLIQATION_ENVIRONMENT || 'Local',
-      title: process.env.APPLIQATION_RUN_TITLE, // Custom run title (optional)
-      autoCreateRun: true
-    }]
+    ['list'],  // Console output
+    ['html'],  // HTML report
+
+    // Appliqation reporter for result submission
+    ['@appliqation/automation-sdk/playwright', appliqationConfig]
+  ],
+
+  projects: [
+    {
+      name: 'chromium',
+      use: {
+        browserName: 'chromium',
+        storageState: '.auth/jwt.json'  // Authenticated browser state
+      }
+    }
   ]
-};
+});
 ```
 
-Add UUIDs to your tests using the `mapAppqUuid` helper:
+**What this does:**
+- ✅ Loads environment variables from `.env`
+- ✅ Configures SDK with your credentials
+- ✅ Uses SDK's built-in `global-setup.js` to handle authentication automatically
+- ✅ Saves authenticated browser state to `.auth/jwt.json`
+- ✅ All tests use authenticated sessions (no login required!)
+- ✅ Reports results to Appliqation portal
+
+---
+
+### Step 4: Add UUIDs to Your Tests
+
+Map your automated tests to Appliqation test cases using `mapAppqUuid()`:
+
+**File:** `tests/example.spec.js`
 
 ```javascript
 const { test, expect } = require('@playwright/test');
 const { mapAppqUuid } = require('@appliqation/automation-sdk/utils');
 
 test('should login successfully', async ({ page }, testInfo) => {
-  // Map test to Appliqation test case
+  // Map this test to Appliqation test case UUID
   mapAppqUuid(testInfo, '1154-7a17b809-0ff9-4ba1-9322-4eb2a49abfc5');
 
-  // Your test code
   await page.goto('/login');
   await page.fill('#username', 'user@example.com');
   await page.fill('#password', 'password');
@@ -71,163 +176,594 @@ test('should login successfully', async ({ page }, testInfo) => {
 
   await expect(page).toHaveURL('/dashboard');
 });
-```
 
-**Alternative (Manual Annotation):**
-```javascript
-test('should login successfully', async ({ page }) => {
-  // Add UUID annotation manually
-  test.info().annotations.push({
-    type: 'appliqation-uuid',
-    description: '1154-7a17b809-0ff9-4ba1-9322-4eb2a49abfc5'
-  });
+test('should display user profile', async ({ page }, testInfo) => {
+  // Different test case, different UUID
+  mapAppqUuid(testInfo, '1154-8b28c910-1aa0-5cc2-a433-5fc6a4d82dc6');
 
-  // Your test code...
+  await page.goto('/profile');
+  await expect(page.locator('h1')).toContainText('My Profile');
 });
 ```
 
-That's it! Results are automatically reported to Appliqation. 🎉
+**How to get UUIDs:**
+1. Login to your Appliqation portal
+2. Navigate to your test cases
+3. Copy the UUID for each test case (format: `nid-uuid`)
+4. You can get UUID from downloading the CSV from the test scenario
 
-## 📋 Configuration
+**Important:**
+- ⚠️ Always include `testInfo` as second parameter: `async ({ page }, testInfo) =>`
+- ⚠️ Call `mapAppqUuid()` at the start of each test
+- ⚠️ UUID format must be: `nid-uuid` (e.g., `1154-7a17b809-...`)
 
-### Environment Variables (Recommended)
+---
 
-Create a `.env` file:
+### Step 5: Run Your Tests
 
-```env
-# Appliqation SDK Configuration - API KEY BASED AUTHENTICATION
-# To generate an API key, go to: http://your-appliqation-instance/admin/config/appliqation/api-keys
-APPLIQATION_BASE_URL=http://localhost:61285
-APPLIQATION_API_KEY=appq_live_xxxxxxxxxxxxx
-APPLIQATION_PROJECT_KEY=your-project-key-here
-APPLIQATION_SCENARIO_ID=1154
-APPLIQATION_ENVIRONMENT=Local
+Run your Playwright tests as normal:
+
+```bash
+npx playwright test
+```
+
+**What happens:**
+
+1. **Global Setup Runs** (once before all tests):
+   - Reads `.env` configuration
+   - Creates automation run in Appliqation portal
+   - Requests browser JWT token from portal
+   - Sets up authenticated browser session
+   - Saves authentication to `.auth/jwt.json`
+
+2. **Tests Execute**:
+   - Each test loads authenticated browser state
+   - No login required - JWT cookie already set!
+   - Tests run normally
+   - Results collected by SDK reporter
+
+3. **Results Submitted**:
+   - SDK batches results (50 per batch by default)
+   - Submits to Appliqation portal
+   - Logs any orphan tests (tests without UUIDs)
+
+4. **Global Teardown Runs** (once after all tests):
+   - Cleanup temporary files
+   - Log final summary
+
+**Check your results:**
+- Visit your Appliqation portal
+- Navigate to the scenario you configured
+- See test results in the run matrix!
 
-# Custom Run Title (optional) - Defaults to "Automation Run - {timestamp}" if not set
-# Examples:
-#   APPLIQATION_RUN_TITLE=Sprint 24 - Regression Tests
-#   APPLIQATION_RUN_TITLE=Nightly Build #123
-#   APPLIQATION_RUN_TITLE=Production Smoke Tests
-# APPLIQATION_RUN_TITLE=
+---
 
-# Logging
-LOG_LEVEL=INFO
+✅ **That's it!** Your tests are now integrated with Appliqation.
+
+---
+
+## How It Works
+
+Understanding the SDK's authentication and result submission flow helps troubleshoot issues.
+
+### Authentication & Test Execution Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    GLOBAL SETUP (Runs Once)                     │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                   │
+│  1. Read .env configuration                                     │
+│     ├─ APPLIQATION_API_KEY                                      │
+│     ├─ APPLIQATION_PROJECT_KEY                                  │
+│     ├─ APPLIQATION_BASE_URL                                     │
+│     └─ APPLIQATION_SCENARIO_ID                                  │
+│                   │                                              │
+│                   ▼                                              │
+│  2. Create automation run via API                               │
+│     POST /api/automation/run/create                             │
+│     ├─ Returns: run_id, api_token                               │
+│     └─ Saves to: process.env.APPLIQATION_RUN_ID                │
+│                   │                                              │
+│                   ▼                                              │
+│  3. Request browser JWT token                                   │
+│     POST /api/auth/jwt/browser                                  │
+│     ├─ Send: api_key                                            │
+│     └─ Returns: jwt_token, expires_in                           │
+│                   │                                              │
+│                   ▼                                              │
+│  4. Setup browser authentication                                │
+│     ├─ Launch headless browser                                  │
+│     ├─ Navigate to baseURL                                      │
+│     ├─ Set cookie: appliqation_jwt = jwt_token                 │
+│     ├─ Save storage state to: .auth/jwt.json                   │
+│     └─ Close browser                                            │
+│                                                                   │
+│  ✅ Setup complete - All tests will use authenticated state     │
+│                                                                   │
+└─────────────────────────────────────────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                   TEST EXECUTION (Per Worker)                   │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                   │
+│  For each test:                                                  │
+│                                                                   │
+│  1. Load storage state from .auth/jwt.json                      │
+│     └─ Browser starts with JWT cookie already set              │
+│                   │                                              │
+│                   ▼                                              │
+│  2. Run test code                                               │
+│     ├─ mapAppqUuid(testInfo, '1154-uuid-here')                 │
+│     ├─ Execute test steps (page.goto, clicks, etc.)            │
+│     └─ Collect result: passed/failed/skipped                    │
+│                   │                                              │
+│                   ▼                                              │
+│  3. Reporter collects result                                    │
+│     ├─ Extract UUID from test.info().annotations               │
+│     ├─ Capture browser/OS/device metadata                      │
+│     ├─ Add to batch queue                                       │
+│     └─ (Batch submitted when size reached or tests complete)   │
+│                                                                   │
+└─────────────────────────────────────────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    REPORTER (After All Tests)                   │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                   │
+│  1. Batch all test results                                      │
+│     └─ Group by 50 results per batch (configurable)            │
+│                   │                                              │
+│                   ▼                                              │
+│  2. Submit to portal                                            │
+│     POST /api/automation/result/batch                           │
+│     ├─ Send: run_id, results[], api_key                        │
+│     └─ Retry on failure (exponential backoff)                  │
+│                   │                                              │
+│                   ▼                                              │
+│  3. Handle orphan tests (tests without UUIDs)                  │
+│     POST /api/automation/orphans                                │
+│     └─ Logs tests that need UUID mapping                       │
+│                   │                                              │
+│                   ▼                                              │
+│  ✅ All results submitted to portal                             │
+│                                                                   │
+└─────────────────────────────────────────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                 GLOBAL TEARDOWN (Runs Once)                     │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                   │
+│  1. Cleanup temporary files (optional)                          │
+│  2. Log final summary                                           │
+│                                                                   │
+│  ✅ Test run complete                                           │
+│                                                                   │
+└─────────────────────────────────────────────────────────────────┘
 ```
 
-### Custom Run Titles
+**Key Points:**
+- Authentication happens **once** in global-setup
+- JWT token saved to `.auth/jwt.json`
+- All test workers reuse the same authenticated state
+- No per-test login required!
 
-You can customize the test run name in three ways:
+### SDK Architecture
 
-**1. Environment Variable (Recommended):**
-```bash
-APPLIQATION_RUN_TITLE="Sprint 24 - Regression Tests" npx playwright test
 ```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Playwright Test Suite                       │
+│                                                                   │
+│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐      │
+│  │  Test File 1  │    │  Test File 2  │    │  Test File 3  │      │
+│  │              │    │              │    │              │      │
+│  │ mapAppqUuid()│    │ mapAppqUuid()│    │ mapAppqUuid()│      │
+│  └──────────────┘    └──────────────┘    └──────────────┘      │
+│         │                    │                    │              │
+└─────────┼────────────────────┼────────────────────┼──────────────┘
+          │                    │                    │
+          └────────────────────┴────────────────────┘
+                               │
+                               ▼
+          ┌─────────────────────────────────────────┐
+          │     Appliqation SDK Reporter            │
+          │                                          │
+          │  • Collects test results                │
+          │  • Extracts UUIDs from annotations      │
+          │  • Batches submissions                  │
+          │  • Handles browser/OS/device metadata   │
+          └─────────────────────────────────────────┘
+                               │
+                               ▼
+          ┌─────────────────────────────────────────┐
+          │     Appliqation HTTP Client             │
+          │                                          │
+          │  • API key authentication               │
+          │  • Connection pooling                   │
+          │  • Exponential backoff retry            │
+          └─────────────────────────────────────────┘
+                               │
+                               ▼
+          ┌─────────────────────────────────────────┐
+          │     Appliqation Portal API              │
+          │                                          │
+          │  • Validates API key                    │
+          │  • Creates run matrices                 │
+          │  • Stores test results                  │
+          │  • Generates reports                    │
+          └─────────────────────────────────────────┘
+```
+
+### File Structure After Setup
+
+```
+your-playwright-project/
+├── .auth/                          # Auto-created by SDK global-setup
+│   └── jwt.json                    # Browser authentication state
+│
+├── .env                            # YOU CREATE THIS (Step 2)
+│   ├── APPLIQATION_API_KEY=appq_live_xxxxx
+│   ├── APPLIQATION_PROJECT_KEY=your-project-key
+│   ├── APPLIQATION_BASE_URL=https://your-domain.com
+│   ├── APPLIQATION_SCENARIO_ID=1154
+│   └── APPLIQATION_ENVIRONMENT=Local
+│
+├── playwright.config.js            # YOU UPDATE THIS (Step 3)
+│   ├── globalSetup: require.resolve('@appliqation/automation-sdk/playwright/global-setup')
+│   ├── globalTeardown: require.resolve('@appliqation/automation-sdk/playwright/global-teardown')
+│   ├── use: { storageState: '.auth/jwt.json' }
+│   └── reporter: ['@appliqation/automation-sdk/playwright', config]
+│
+├── tests/
+│   ├── login.spec.js               # YOUR TESTS (Step 4)
+│   │   ├── const { mapAppqUuid } = require('@appliqation/automation-sdk/utils');
+│   │   └── mapAppqUuid(testInfo, '1154-uuid-here');
+│   │
+│   └── checkout.spec.js
+│
+├── package.json
+│   └── dependencies:
+│       ├── @playwright/test
+│       ├── @appliqation/automation-sdk
+│       └── dotenv                  # Required for .env loading
+│
+└── node_modules/
+    └── @appliqation/automation-sdk/
+        └── playwright/
+            ├── global-setup.js     # SDK provides this!
+            ├── global-teardown.js  # SDK provides this!
+            └── index.js            # Reporter
+```
+
+---
+
+## Configuration Reference
+
+### Environment Variables (.env)
+
+All environment variables and their purposes:
+
+| Variable | Required | Description | Example |
+|----------|----------|-------------|---------|
+| `APPLIQATION_BASE_URL` | ✅ Yes | Your Appliqation portal URL (no trailing slash) | `https://portal.appliqation.com` |
+| `APPLIQATION_API_KEY` | ✅ Yes | API key from `/admin/config/appliqation/api-keys` | `appq_live_abc123xyz...` |
+| `APPLIQATION_PROJECT_KEY` | ✅ Yes | Project key from project settings | `my-project-key` |
+| `APPLIQATION_SCENARIO_ID` | ✅ Yes | Scenario node ID to track | `1154` |
+| `APPLIQATION_ENVIRONMENT` | ❌ No | Environment name (default: `Local`) | `Staging`, `Production` |
+| `APPLIQATION_RUN_TITLE` | ❌ No | Custom run title (default: auto-generated) | `Sprint 24 - Regression` |
+| `LOG_LEVEL` | ❌ No | Logging verbosity (default: `INFO`) | `DEBUG`, `ERROR` |
+
+### Reporter Options (playwright.config.js)
+
+All available options for the Appliqation reporter config:
 
-**2. Config File (playwright.config.js):**
 ```javascript
-[AppliqationReporter, {
-  // ...other config
-  title: "Sprint 24 - Regression Tests"
-}]
+const appliqationConfig = {
+  // Required
+  baseUrl: process.env.APPLIQATION_BASE_URL,
+  apiKey: process.env.APPLIQATION_API_KEY,
+  projectKey: process.env.APPLIQATION_PROJECT_KEY,
+  scenarioId: parseInt(process.env.APPLIQATION_SCENARIO_ID),
+
+  // Optional
+  environment: 'Local',              // Environment name
+  title: 'My Custom Run',            // Custom run title
+  autoCreateRun: true,               // Auto-create run (default: true)
+  batchSubmit: true,                 // Batch results (default: true)
+  batchSize: 50,                     // Results per batch (default: 50)
+  logOrphans: true,                  // Log tests without UUIDs (default: true)
+  logLevel: 'INFO',                  // INFO, DEBUG, ERROR (default: INFO)
+  rejectUnauthorized: false          // Allow self-signed certs (default: false)
+};
 ```
 
-**3. SDK Client (Programmatic):**
+**Common Configurations:**
+
+**CI/CD Pipeline:**
 ```javascript
-const client = new AppliqationClient({
-  baseUrl: 'https://your-instance.appliqation.com',
-  apiKey: 'appq_live_xxxxxxxxxxxxx',
-  projectKey: 'your-project-key',
-  title: 'Sprint 24 - Regression Tests'
-});
+{
+  environment: process.env.CI_ENVIRONMENT || 'CI',
+  title: `Build #${process.env.CI_BUILD_NUMBER}`,
+  logLevel: 'ERROR',  // Less verbose in CI
+  batchSize: 100      // Larger batches for speed
+}
 ```
 
-**Priority:** Config → Env Var → Default ("Automation Run - {timestamp}")
+**Local Development:**
+```javascript
+{
+  environment: 'Local',
+  logLevel: 'DEBUG',          // Detailed logs
+  logOrphans: true,           // See unmapped tests
+  rejectUnauthorized: false   // Allow local SSL
+}
+```
 
-## 🔧 Framework Integration Examples
+---
 
-### Playwright ✅ (Production Ready)
+## Adding Test Case UUIDs
 
-See Quick Start above for full Playwright integration. The reporter automatically:
-- Creates run matrices with browser/device/OS detection
-- Extracts UUIDs from test annotations
-- Batches and submits results
-- Handles orphan tests (tests without UUIDs)
+Map your automated tests to Appliqation test cases to track results.
 
-### Cypress 🚧 (Coming in v2.1.0)
+### Method: mapAppqUuid()
 
-Will work similarly to Playwright:
+**Import the utility:**
+```javascript
+const { mapAppqUuid } = require('@appliqation/automation-sdk/utils');
+```
 
+**Use in tests:**
 ```javascript
-// cypress.config.js
-const { CypressReporter } = require('@appliqation/automation-sdk/cypress');
+test('test description', async ({ page }, testInfo) => {
+  //                                        ^^^^^^^^ Required parameter!
 
-module.exports = defineConfig({
-  e2e: {
-    setupNodeEvents(on, config) {
-      CypressReporter(on, {
-        baseUrl: process.env.APPLIQATION_BASE_URL,
-        apiKey: process.env.APPLIQATION_API_KEY,
-        projectKey: process.env.APPLIQATION_PROJECT_KEY,
-        scenarioId: parseInt(process.env.APPLIQATION_SCENARIO_ID),
-        environment: process.env.APPLIQATION_ENVIRONMENT || 'Local',
-        title: process.env.APPLIQATION_RUN_TITLE
-      });
-    }
-  }
+  // Map to test case UUID
+  mapAppqUuid(testInfo, '1154-7a17b809-0ff9-4ba1-9322-4eb2a49abfc5');
+
+  // Your test code...
 });
 ```
 
+**Important:**
+- ⚠️ Always include `testInfo` as second parameter
+- ⚠️ UUID format: `nid-uuid` (e.g., `1154-abc123...`)
+- ⚠️ Get UUIDs from Appliqation portal test cases
+
+### Getting UUIDs from Portal
+
+1. Login to Appliqation portal
+2. Navigate to **Test Cases** section
+3. Open the test case you want to map
+4. Copy the UUID (shown in test case details)
+5. Use format: `nid-uuid` where:
+   - `nid` = Test case node ID (e.g., `1154`)
+   - `uuid` = Test case UUID (e.g., `7a17b809-0ff9-4ba1-9322-4eb2a49abfc5`)
+
+### What About Tests Without UUIDs?
+
+Tests without `mapAppqUuid()` calls are called **orphan tests**. The SDK will:
+- ✅ Still run them normally
+- ✅ Collect results
+- ✅ Log them separately (if `logOrphans: true`)
+- ❌ Won't report to portal (no UUID to map to)
+
+**Check orphan logs to see which tests need UUID mapping.**
+
+---
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+#### ❌ Error: "APPLIQATION_API_KEY is required"
+
+**Cause:** `.env` file not loaded or missing variable
+
+**Fix:**
+1. Verify `.env` file exists in project root
+2. Check variable name spelling (no typos!)
+3. Ensure `require('dotenv').config()` at top of `playwright.config.js`
+4. No spaces around `=` sign:
+   ```bash
+   # ❌ Wrong
+   APPLIQATION_API_KEY = appq_live_xxx
+
+   # ✅ Correct
+   APPLIQATION_API_KEY=appq_live_xxx
+   ```
+
+---
+
+#### ❌ Tests redirecting to login page (authentication failed)
+
+**Cause:** JWT authentication not working, storage state not loading
+
+**Fix:**
+1. Verify `globalSetup` configured correctly:
+   ```javascript
+   globalSetup: require.resolve('@appliqation/automation-sdk/playwright/global-setup')
+   ```
+
+2. Check `.auth/jwt.json` file exists after global-setup runs
+
+3. Verify all projects use storage state:
+   ```javascript
+   projects: [{
+     name: 'chromium',
+     use: { storageState: '.auth/jwt.json' }  // Must be set!
+   }]
+   ```
+
+4. Check `.env` has correct `APPLIQATION_BASE_URL` (no trailing slash):
+   ```bash
+   # ❌ Wrong
+   APPLIQATION_BASE_URL=https://portal.com/
+
+   # ✅ Correct
+   APPLIQATION_BASE_URL=https://portal.com
+   ```
+
+---
+
+#### ❌ Error: "testInfo is not defined"
+
+**Cause:** Missing `testInfo` parameter in test function
+
+**Fix:**
 ```javascript
-// Add UUID to tests
-it('should login successfully', { uuid: '1154-7a17b809-0ff9-4ba1-9322-4eb2a49abfc5' }, () => {
-  cy.visit('/login');
-  cy.get('#username').type('user@example.com');
-  cy.get('#password').type('password');
-  cy.get('#login-button').click();
-  cy.url().should('include', '/dashboard');
+// ❌ Wrong - missing testInfo
+test('my test', async ({ page }) => {
+  mapAppqUuid(testInfo, 'uuid-here');  // testInfo undefined!
+});
+
+// ✅ Correct - include testInfo
+test('my test', async ({ page }, testInfo) => {
+  mapAppqUuid(testInfo, 'uuid-here');
 });
 ```
 
-### Jest 🚧 (Coming in v2.1.0)
+---
+
+#### ❌ Error: "Invalid UUID format"
 
-Will work similarly to Playwright:
+**Cause:** UUID not in `nid-uuid` format
 
+**Fix:**
 ```javascript
-// jest.config.js
-const { JestReporter } = require('@appliqation/automation-sdk/jest');
-
-module.exports = {
-  reporters: [
-    'default',
-    [JestReporter, {
-      baseUrl: process.env.APPLIQATION_BASE_URL,
-      apiKey: process.env.APPLIQATION_API_KEY,
-      projectKey: process.env.APPLIQATION_PROJECT_KEY,
-      scenarioId: parseInt(process.env.APPLIQATION_SCENARIO_ID),
-      environment: process.env.APPLIQATION_ENVIRONMENT || 'Local',
-      title: process.env.APPLIQATION_RUN_TITLE
-    }]
-  ]
+// ❌ Wrong formats
+mapAppqUuid(testInfo, '7a17b809-0ff9-4ba1-9322-4eb2a49abfc5');  // Missing nid
+mapAppqUuid(testInfo, '1154');  // Missing UUID
+mapAppqUuid(testInfo, 'test-case-123');  // Wrong format
+
+// ✅ Correct format
+mapAppqUuid(testInfo, '1154-7a17b809-0ff9-4ba1-9322-4eb2a49abfc5');
+```
+
+---
+
+#### ❌ Error: "Module 'dotenv' not found"
+
+**Cause:** `dotenv` package not installed
+
+**Fix:**
+```bash
+npm install dotenv
+```
+
+---
+
+#### ❌ Results not appearing in portal
+
+**Possible causes:**
+
+1. **Orphan tests** - Tests don't have `mapAppqUuid()` calls
+   - **Fix:** Add UUID mapping to all tests
+   - Enable `logOrphans: true` to see which tests are orphans
+
+2. **Wrong scenario ID** - Results sent to different scenario
+   - **Fix:** Verify `APPLIQATION_SCENARIO_ID` matches portal
+
+3. **API key invalid** - Authentication failed
+   - **Fix:** Regenerate API key from portal
+
+4. **Network issues** - Portal unreachable
+   - **Fix:** Check `APPLIQATION_BASE_URL` is accessible
+
+---
+
+### Debug Mode
+
+Enable detailed logging to troubleshoot issues:
+
+**In .env:**
+```bash
+LOG_LEVEL=DEBUG
+```
+
+**Or in config:**
+```javascript
+const appliqationConfig = {
+  // ... other config
+  logLevel: 'DEBUG'
 };
 ```
 
+**Debug output shows:**
+- ✅ API requests and responses
+- ✅ Authentication flow details
+- ✅ Result submission batches
+- ✅ Orphan test detection
+- ✅ Error stack traces
+
+---
+
+### Test Connection
+
+Verify SDK can reach your portal:
+
+**Create test file:** `test-connection.js`
 ```javascript
-// Add UUID to tests
-test('should login successfully', async () => {
-  // Add UUID metadata
-  expect.getState().currentTestName = '1154-7a17b809-0ff9-4ba1-9322-4eb2a49abfc5';
-
-  // Your test code
-  const loginSuccess = await performLogin();
-  expect(loginSuccess).toBe(true);
+const AppliqationClient = require('@appliqation/automation-sdk');
+require('dotenv').config();
+
+async function testConnection() {
+  const client = new AppliqationClient({
+    baseUrl: process.env.APPLIQATION_BASE_URL,
+    apiKey: process.env.APPLIQATION_API_KEY,
+    projectKey: process.env.APPLIQATION_PROJECT_KEY
+  });
+
+  const result = await client.testConnection();
+  console.log('Connection test:', result);
+}
+
+testConnection();
+```
+
+**Run:**
+```bash
+node test-connection.js
+```
+
+**Expected output:**
+```
+Connection test: { success: true, message: 'Connected to Appliqation portal' }
+```
+
+---
+
+## Advanced Features
+
+### Custom Playwright Fixture (Auto JWT Refresh)
+
+For long-running test suites, use the SDK's custom fixture to automatically refresh JWT tokens:
+
+**File:** `playwright.config.js`
+```javascript
+const { test: base } = require('@playwright/test');
+const { createAppliqationFixture } = require('@appliqation/automation-sdk/playwright');
+
+// Extend Playwright's base test with SDK fixture
+const test = createAppliqationFixture(base, {
+  baseUrl: process.env.APPLIQATION_BASE_URL,
+  apiKey: process.env.APPLIQATION_API_KEY
 });
+
+module.exports = { test };
 ```
 
-## 📊 Advanced Usage (Direct SDK)
+**What it does:**
+- ✅ Checks JWT expiry before each test
+- ✅ Automatically refreshes if < 5 minutes remaining
+- ✅ Updates `.auth/jwt.json` with new token
+- ✅ Prevents authentication failures in long test runs
 
-For custom integrations or frameworks without built-in reporters, use the core SDK directly:
+### Using Core SDK Directly
 
-### Core SDK Usage
+For custom integrations or non-Playwright frameworks:
 
 ```javascript
 const AppliqationClient = require('@appliqation/automation-sdk');
@@ -236,15 +772,14 @@ const AppliqationClient = require('@appliqation/automation-sdk');
 const client = new AppliqationClient({
   baseUrl: process.env.APPLIQATION_BASE_URL,
   apiKey: process.env.APPLIQATION_API_KEY,
-  projectKey: process.env.APPLIQATION_PROJECT_KEY,
-  title: 'My Custom Test Run'
+  projectKey: process.env.APPLIQATION_PROJECT_KEY
 });
 
-// Create run matrix
+// Create run
 const run = await client.createRun({
   scenarioId: 1154,
   environment: 'Production',
-  browsers: ['Chrome', 'Firefox'],
+  browsers: ['Chrome'],
   device: 'Desktop',
   os: 'Windows 11'
 });
@@ -253,7 +788,7 @@ console.log('Run created:', run.runId);
 
 // Submit single result
 await client.submitResult(run.runId, {
-  uuid: '124-d1f9559c-b978-43cc-9c76-fd539c717cb4',
+  uuid: '1154-7a17b809-0ff9-4ba1-9322-4eb2a49abfc5',
   status: 'passed',
   browser: 'Chrome',
   comment: 'Test passed successfully'
@@ -261,181 +796,82 @@ await client.submitResult(run.runId, {
 
 // Submit batch results
 const results = [
-  { uuid: '124-test1-uuid', runId: run.runId, status: 'passed', browser: 'Chrome' },
-  { uuid: '124-test2-uuid', runId: run.runId, status: 'failed', browser: 'Chrome', comment: 'Button missing' },
-  { uuid: '124-test3-uuid', runId: run.runId, status: 'skipped', browser: 'Chrome' }
+  { uuid: '1154-uuid-1', runId: run.runId, status: 'passed', browser: 'Chrome' },
+  { uuid: '1154-uuid-2', runId: run.runId, status: 'failed', browser: 'Chrome' }
 ];
 
 const summary = await client.submitBatch(results);
 console.log(`Submitted: ${summary.success}/${summary.total} successful`);
 ```
 
-### Run Matrix Management
-
-```javascript
-// Create multiple runs for cross-browser testing
-const configs = [
-  { scenarioId: 1154, environment: 'Staging', browsers: ['Chrome'], device: 'Desktop', os: 'Windows 11' },
-  { scenarioId: 1154, environment: 'Staging', browsers: ['Firefox'], device: 'Desktop', os: 'Windows 11' },
-  { scenarioId: 1154, environment: 'Staging', browsers: ['Safari'], device: 'Desktop', os: 'macOS' }
-];
-
-const result = await client.createMultipleRuns(configs);
-console.log(`Created ${result.summary.success} runs`);
+### Custom Run Titles
 
-// Add browser to existing run
-await client.addBrowser(run.runId, 'Edge');
+Set custom titles for test runs:
 
-// Get run details
-const runData = await client.getRun(run.runId);
-console.log(runData);
+**Method 1: Environment Variable**
+```bash
+APPLIQATION_RUN_TITLE="Sprint 24 - Regression Tests" npx playwright test
 ```
 
-## 🔍 API Reference
-
-### AppliqationClient Class
-
-**Constructor:**
+**Method 2: Config File**
 ```javascript
-new AppliqationClient(config)
-```
-- `config.baseUrl` (string) - Appliqation instance URL
-- `config.apiKey` (string) - API key (appq_live_xxxxx)
-- `config.projectKey` (string) - Project key
-- `config.username` (string, optional) - Username for legacy CSRF auth
-- `config.password` (string, optional) - Password for legacy CSRF auth
-- `config.title` (string, optional) - Custom run title
-- `config.options` (object, optional):
-  - `timeout` (number) - Request timeout in ms (default: 30000)
-  - `retries` (number) - Retry attempts (default: 3)
-  - `logOrphans` (boolean) - Log orphan tests (default: true)
-  - `logLevel` (string) - Logging level (default: 'info')
-
-**Methods:**
-
-**createRun(options)** - Create test run matrix
-- `options.scenarioId` (number) - Scenario node ID
-- `options.testSetId` (number) - Test set node ID (alternative to scenarioId)
-- `options.environment` (string) - Environment name (default: 'Local')
-- `options.browsers` (array) - Browser names (default: ['Chrome'])
-- `options.device` (string) - Device type
-- `options.os` (string) - Operating system
-- `options.title` (string) - Custom run title
-- Returns: `{ runId, token, timestamp, metadata }`
-
-**submitResult(runId, result)** - Submit single test result
-- `runId` (string) - Run ID
-- `result.uuid` (string) - Test case UUID (format: nid-uuid)
-- `result.status` (string) - 'passed', 'failed', 'skipped'
-- `result.browser` (string) - Browser name
-- `result.comment` (string, optional) - Additional comments
-- `result.environment` (string, optional) - Environment override
-
-**submitBatch(results, options)** - Submit batch of results
-- `results` (array) - Array of result objects
-- `options.batchSize` (number) - Results per batch (default: 50)
-- `options.onProgress` (function) - Progress callback
-- `options.retryFailures` (boolean) - Retry failed submissions (default: true)
-- Returns: `{ success, failed, total, invalidResults }`
-
-**logOrphanTests(runId, orphanTests)** - Log tests without UUID mappings
-**addBrowser(runId, browser)** - Add browser to existing run
-**getRun(runId)** - Get run matrix data
-**testConnection()** - Test connectivity to Appliqation
-**validateUuid(uuid)** - Validate UUID format
-**extractNid(uuid)** - Extract NID from UUID
-**parseUuid(uuid)** - Validate and extract UUID components
-
-## 🆔 Getting Test UUIDs
-
-1. Login to your Appliqation portal
-2. Navigate to your test cases
-3. Download/copy the UUIDs for the test cases you want to automate
-4. Use these UUIDs in your `reportResult()` calls
+const appliqationConfig = {
+  // ... other config
+  title: "Sprint 24 - Regression Tests"
+};
+```
 
-The UUIDs follow the format: `nid-uuid` (e.g., `124-d1f9559c-b978-43cc-9c76-fd539c717cb4`)
+**Method 3: Programmatic (Core SDK)**
+```javascript
+const client = new AppliqationClient({
+  // ... other config
+  title: "Sprint 24 - Regression Tests"
+});
+```
 
-## 🏃‍♂️ Run Matrix Integration
+**Priority:** Config > Env Var > Default (`"Automation Run - {timestamp}"`)
 
-Each test run in Appliqation has a unique `run_id`. The SDK will:
+---
 
-1. **Auto-generate** a run ID if not provided
-2. **Use environment variable** `RUN_ID` if set
-3. **Accept custom run ID** in configuration
+## API Reference
 
-All test results reported with the same `run_id` will appear together in your Appliqation run matrix.
+### Quick Reference
 
-## 🐛 Error Handling
+Most commonly used SDK exports:
 
+**Reporter (for playwright.config.js):**
 ```javascript
-try {
-  const response = await reportResult('124-test-uuid', 'pass');
-  if (response.success) {
-    console.log('✅ Result reported successfully');
-  } else {
-    console.error('❌ Failed to report:', response.error);
-  }
-} catch (error) {
-  console.error('❌ SDK Error:', error.message);
-}
+['@appliqation/automation-sdk/playwright', config]
 ```
 
-## 🔧 Troubleshooting
-
-### Common Issues
-
-1. **Authentication Failed**
-   ```
-   Error: APPLIQATION_USERNAME environment variable is required
-   ```
-   **Solution**: Set your credentials in `.env` file or pass to `init()`
-
-2. **Invalid UUID Format**
-   ```
-   Error: uuid must be in format: nid-uuid
-   ```
-   **Solution**: Ensure UUID follows `124-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` format
-
-3. **Connection Issues**
-   ```javascript
-   // Test your connection
-   const sdk = new AppliqationSDK();
-   await sdk.init({ /* config */ });
-   const result = await sdk.testConnection();
-   console.log(result);
-   ```
-
-### Debug Mode
+**Global Setup/Teardown:**
+```javascript
+require.resolve('@appliqation/automation-sdk/playwright/global-setup')
+require.resolve('@appliqation/automation-sdk/playwright/global-teardown')
+```
 
+**Utilities:**
 ```javascript
-await init({
-  // ... other config
-  logLevel: 'DEBUG'  // See detailed logs
-});
+const { mapAppqUuid } = require('@appliqation/automation-sdk/utils');
 ```
 
-## 📝 Migration from v0.x
+**Core Client:**
+```javascript
+const AppliqationClient = require('@appliqation/automation-sdk');
+```
 
-If you're upgrading from the old `drupal-test-results-sdk`:
+### Full API Documentation
 
-```javascript
-// Old way
-const { DrupalTestResultsSDK } = require('drupal-test-results-sdk');
-const sdk = new DrupalTestResultsSDK(config);
-await sdk.insertResult(payload);
+For complete API reference including all methods, parameters, and return types, see the source code documentation in the `/src` directory.
 
-// New way
-const { init, reportResult } = require('@appliqation/automation-sdk');
-await init(config);
-await reportResult(uuid, status, options);
-```
+---
 
-## 🤝 Support
+## Support
 
 - 📧 **Email**: support@appliqation.com
-- 📖 **Documentation**: [Appliqation Docs](https://docs.appliqation.com)
-- 🐛 **Issues**: [GitHub Issues](https://github.com/your-repo/issues)
+- 📖 **Documentation**: https://docs.appliqation.com
+- 🐛 **Issues**: https://github.com/appliqation/automation-sdk-js/issues
 
-## 📄 License
+## License
 
 MIT License - see LICENSE file for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appliqation/automation-sdk",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Appliqation Automation SDK with API key authentication, custom run titles, and framework-specific reporters",
   "main": "src/index.js",
   "types": "src/index.d.ts",