@appliqation/automation-sdk 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Appliqation Pty Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,441 @@
+# Appliqation Automation Integration 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).
+
+## ✨ Features
+
+- 🎯 **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
+
+## 🚩 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 |
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install @appliqation/automation-sdk
+```
+
+### Playwright (Recommended - Production Ready)
+
+Add the Appliqation reporter to your `playwright.config.js`:
+
+```javascript
+const { AppliqationReporter } = require('@appliqation/automation-sdk/playwright');
+
+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
+    }]
+  ]
+};
+```
+
+Add UUIDs to your tests using the `mapAppqUuid` helper:
+
+```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
+  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');
+  await page.click('#login-button');
+
+  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'
+  });
+
+  // Your test code...
+});
+```
+
+That's it! Results are automatically reported to Appliqation. 🎉
+
+## 📋 Configuration
+
+### Environment Variables (Recommended)
+
+Create a `.env` file:
+
+```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
+
+# 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
+```
+
+### Custom Run Titles
+
+You can customize the test run name in three ways:
+
+**1. Environment Variable (Recommended):**
+```bash
+APPLIQATION_RUN_TITLE="Sprint 24 - Regression Tests" npx playwright test
+```
+
+**2. Config File (playwright.config.js):**
+```javascript
+[AppliqationReporter, {
+  // ...other config
+  title: "Sprint 24 - Regression Tests"
+}]
+```
+
+**3. SDK Client (Programmatic):**
+```javascript
+const client = new AppliqationClient({
+  baseUrl: 'https://your-instance.appliqation.com',
+  apiKey: 'appq_live_xxxxxxxxxxxxx',
+  projectKey: 'your-project-key',
+  title: 'Sprint 24 - Regression Tests'
+});
+```
+
+**Priority:** Config → Env Var → Default ("Automation Run - {timestamp}")
+
+## 🔧 Framework Integration Examples
+
+### Playwright ✅ (Production Ready)
+
+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)
+
+### Cypress 🚧 (Coming in v2.1.0)
+
+Will work similarly to Playwright:
+
+```javascript
+// cypress.config.js
+const { CypressReporter } = require('@appliqation/automation-sdk/cypress');
+
+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
+      });
+    }
+  }
+});
+```
+
+```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');
+});
+```
+
+### Jest 🚧 (Coming in v2.1.0)
+
+Will work similarly to Playwright:
+
+```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
+    }]
+  ]
+};
+```
+
+```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);
+});
+```
+
+## 📊 Advanced Usage (Direct SDK)
+
+For custom integrations or frameworks without built-in reporters, use the core SDK directly:
+
+### Core SDK Usage
+
+```javascript
+const AppliqationClient = require('@appliqation/automation-sdk');
+
+// Initialize client
+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'
+});
+
+// Create run matrix
+const run = await client.createRun({
+  scenarioId: 1154,
+  environment: 'Production',
+  browsers: ['Chrome', 'Firefox'],
+  device: 'Desktop',
+  os: 'Windows 11'
+});
+
+console.log('Run created:', run.runId);
+
+// Submit single result
+await client.submitResult(run.runId, {
+  uuid: '124-d1f9559c-b978-43cc-9c76-fd539c717cb4',
+  status: 'passed',
+  browser: 'Chrome',
+  comment: 'Test passed successfully'
+});
+
+// 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' }
+];
+
+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`);
+
+// Add browser to existing run
+await client.addBrowser(run.runId, 'Edge');
+
+// Get run details
+const runData = await client.getRun(run.runId);
+console.log(runData);
+```
+
+## 🔍 API Reference
+
+### AppliqationClient Class
+
+**Constructor:**
+```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
+
+The UUIDs follow the format: `nid-uuid` (e.g., `124-d1f9559c-b978-43cc-9c76-fd539c717cb4`)
+
+## 🏃‍♂️ Run Matrix Integration
+
+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
+
+All test results reported with the same `run_id` will appear together in your Appliqation run matrix.
+
+## 🐛 Error Handling
+
+```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);
+}
+```
+
+## 🔧 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
+
+```javascript
+await init({
+  // ... other config
+  logLevel: 'DEBUG'  // See detailed logs
+});
+```
+
+## 📝 Migration from v0.x
+
+If you're upgrading from the old `drupal-test-results-sdk`:
+
+```javascript
+// Old way
+const { DrupalTestResultsSDK } = require('drupal-test-results-sdk');
+const sdk = new DrupalTestResultsSDK(config);
+await sdk.insertResult(payload);
+
+// New way
+const { init, reportResult } = require('@appliqation/automation-sdk');
+await init(config);
+await reportResult(uuid, status, options);
+```
+
+## 🤝 Support
+
+- 📧 **Email**: support@appliqation.com
+- 📖 **Documentation**: [Appliqation Docs](https://docs.appliqation.com)
+- 🐛 **Issues**: [GitHub Issues](https://github.com/your-repo/issues)
+
+## 📄 License
+
+MIT License - see LICENSE file for details.

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "@appliqation/automation-sdk",
+  "version": "2.1.0",
+  "description": "Appliqation Automation SDK with API key authentication, custom run titles, and framework-specific reporters",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./src/index.js",
+      "import": "./src/index.js"
+    },
+    "./playwright": {
+      "require": "./src/reporters/playwright/index.js",
+      "import": "./src/reporters/playwright/index.js"
+    },
+    "./cypress": {
+      "require": "./src/reporters/cypress/index.js",
+      "import": "./src/reporters/cypress/index.js"
+    },
+    "./jest": {
+      "require": "./src/reporters/jest/index.js",
+      "import": "./src/reporters/jest/index.js"
+    },
+    "./utils": {
+      "require": "./src/utils/index.js",
+      "import": "./src/utils/index.js"
+    }
+  },
+  "files": [
+    "src/",
+    "src/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "jest",
+    "test:unit": "jest tests/unit",
+    "test:integration": "jest tests/integration",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "example:basic": "node examples/basic-usage.js",
+    "example:playwright": "cd examples/playwright-basic && npx playwright test",
+    "example:cypress": "cd examples/cypress-basic && npm test",
+    "example:jest": "cd examples/jest-basic && npm test",
+    "docs": "echo 'Documentation generation coming soon'"
+  },
+  "keywords": [
+    "appliqation",
+    "testing",
+    "automation",
+    "test-management",
+    "playwright",
+    "cypress",
+    "jest",
+    "selenium",
+    "webdriver",
+    "api-key",
+    "sdk",
+    "test-reporting",
+    "test-results",
+    "quality-assurance",
+    "qa-tools"
+  ],
+  "author": "Appliqation Team",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.6.0",
+    "dotenv": "^16.3.1",
+    "jsonwebtoken": "^9.0.2"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.40.0",
+    "cypress": "^13.0.0",
+    "eslint": "^8.57.0",
+    "jest": "^29.7.0",
+    "playwright": "^1.40.0"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.30.0",
+    "cypress": ">=10.0.0",
+    "jest": ">=29.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    },
+    "cypress": {
+      "optional": true
+    },
+    "jest": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/appliqation/automation-sdk-js"
+  },
+  "bugs": {
+    "url": "https://github.com/appliqation/automation-sdk-js/issues"
+  },
+  "homepage": "https://github.com/appliqation/automation-sdk-js#readme"
+}