@appliqation/automation-sdk 2.1.0

package/src/index.d.ts

@@ -0,0 +1,333 @@
+/**
+ * TypeScript definitions for @appliqation/automation-sdk
+ * @version 2.1.0
+ */
+
+// ============================================================================
+// Core Types
+// ============================================================================
+
+/**
+ * Test result status
+ */
+export type TestStatus = 'pass' | 'fail' | 'skip';
+
+/**
+ * Log levels
+ */
+export type LogLevel = 'ERROR' | 'WARN' | 'INFO' | 'DEBUG';
+
+/**
+ * Browser types
+ */
+export type Browser = 'Chrome' | 'Firefox' | 'Safari' | 'Edge' | 'Chromium' | 'WebKit' | string;
+
+/**
+ * Device types
+ */
+export type Device = 'Desktop' | 'Mobile' | 'Tablet' | string;
+
+/**
+ * Operating systems
+ */
+export type OperatingSystem = 'Windows' | 'macOS' | 'Linux' | 'iOS' | 'Android' | string;
+
+// ============================================================================
+// Configuration Interfaces
+// ============================================================================
+
+/**
+ * SDK configuration options
+ */
+export interface AppliqationConfig {
+  /** Base URL of the Appliqation instance */
+  baseUrl: string;
+
+  /** API key for authentication (recommended) */
+  apiKey?: string;
+
+  /** Project key */
+  projectKey?: string;
+
+  /** Username for legacy CSRF authentication */
+  username?: string;
+
+  /** Password for legacy CSRF authentication */
+  password?: string;
+
+  /** Scenario ID (optional, 0 for generic automation runs) */
+  scenarioId?: number;
+
+  /** Test set ID (alternative to scenarioId) */
+  testSetId?: number;
+
+  /** Environment name (e.g., 'Local', 'Development', 'Staging', 'Production') */
+  environment?: string;
+
+  /** Custom run title */
+  title?: string;
+
+  /** Alternative to title */
+  runTitle?: string;
+
+  /** Browser list */
+  browsers?: Browser[];
+
+  /** Device type */
+  device?: Device;
+
+  /** Operating system */
+  os?: OperatingSystem;
+
+  /** Automatically create run on initialization */
+  autoCreateRun?: boolean;
+
+  /** Enable batch submission of results */
+  batchSubmit?: boolean;
+
+  /** Batch size for result submission */
+  batchSize?: number;
+
+  /** SSL certificate verification (default: true) */
+  rejectUnauthorized?: boolean;
+
+  /** Additional options */
+  options?: {
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+
+    /** Number of retries for failed requests (default: 3) */
+    retries?: number;
+
+    /** Base retry delay in milliseconds (default: 1000) */
+    retryDelay?: number;
+
+    /** Maximum retry delay in milliseconds (default: 30000) */
+    maxRetryDelay?: number;
+
+    /** Retry jitter factor (default: 0.1) */
+    retryJitter?: number;
+
+    /** Log orphan tests (tests without UUID mapping) (default: true) */
+    logOrphans?: boolean;
+
+    /** Log level (default: 'INFO') */
+    logLevel?: LogLevel;
+
+    /** Enable HTTP keep-alive (default: true) */
+    keepAlive?: boolean;
+
+    /** Maximum number of sockets (default: 50) */
+    maxSockets?: number;
+
+    /** Maximum number of free sockets (default: 10) */
+    maxFreeSockets?: number;
+
+    /** Keep-alive timeout in milliseconds (default: 1000) */
+    keepAliveMsecs?: number;
+  };
+}
+
+// ============================================================================
+// Result Interfaces
+// ============================================================================
+
+/**
+ * Test result object
+ */
+export interface TestResult {
+  /** Test UUID (format: "{testSetId}-{uuid}") */
+  uuid: string;
+
+  /** Test status */
+  status: TestStatus;
+
+  /** Optional comment */
+  comment?: string;
+
+  /** Optional attachments */
+  attachments?: string[];
+
+  /** Optional metadata */
+  metadata?: Record<string, any>;
+}
+
+/**
+ * API response
+ */
+export interface ApiResponse<T = any> {
+  /** Success status */
+  success: boolean;
+
+  /** Response data */
+  data?: T;
+
+  /** HTTP status code */
+  status?: number;
+
+  /** Response headers */
+  headers?: Record<string, string>;
+
+  /** Error message (if success is false) */
+  message?: string;
+
+  /** Error details */
+  error?: string;
+}
+
+/**
+ * Run matrix response
+ */
+export interface RunMatrixResponse {
+  /** Run ID */
+  runId: string;
+
+  /** Run timestamp */
+  timestamp: number;
+
+  /** Environment */
+  environment: string;
+
+  /** Browser list */
+  browsers: Browser[];
+
+  /** Device type */
+  device?: Device;
+
+  /** Operating system */
+  os?: OperatingSystem;
+}
+
+/**
+ * Batch submission summary
+ */
+export interface BatchSubmissionSummary {
+  /** Number of successful submissions */
+  success: number;
+
+  /** Number of failed submissions */
+  failed: number;
+
+  /** Total number of results */
+  total: number;
+
+  /** Number of invalid results */
+  invalid?: number;
+
+  /** Invalid results details */
+  invalidResults?: Array<{ result: TestResult; error: string }>;
+}
+
+// ============================================================================
+// AppliqationClient Class
+// ============================================================================
+
+/**
+ * Main SDK client class
+ */
+export class AppliqationClient {
+  /**
+   * Create a new Appliqation client
+   */
+  constructor(config: AppliqationConfig);
+
+  /**
+   * Create a new automation run
+   */
+  createRun(config?: Partial<AppliqationConfig>): Promise<RunMatrixResponse>;
+
+  /**
+   * Submit a single test result
+   */
+  reportResult(
+    uuid: string,
+    status: TestStatus,
+    options?: { comment?: string; attachments?: string[]; metadata?: Record<string, any> }
+  ): Promise<ApiResponse>;
+
+  /**
+   * Submit multiple test results in batch
+   */
+  reportBatchResults(results: TestResult[]): Promise<BatchSubmissionSummary>;
+
+  /**
+   * Log orphan tests (tests without UUID mappings)
+   */
+  logOrphanTests(runId: string, orphanTests: any[]): Promise<ApiResponse>;
+
+  /**
+   * Get current run ID
+   */
+  getRunId(): string | null;
+
+  /**
+   * Test connection to Appliqation instance
+   */
+  testConnection(): Promise<boolean>;
+
+  /**
+   * Get SDK version
+   */
+  getVersion(): string;
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+/**
+ * Main client class (default export)
+ */
+export default AppliqationClient;
+
+/**
+ * Named exports
+ */
+export { AppliqationClient };
+
+/**
+ * Utility exports
+ */
+export class UuidValidator {
+  static validate(uuid: string): { valid: boolean; error?: string };
+  static isValid(uuid: string): boolean;
+}
+
+export class PayloadBuilder {
+  static buildResultPayload(
+    uuid: string,
+    status: TestStatus,
+    options?: { comment?: string; attachments?: string[]; metadata?: Record<string, any> }
+  ): TestResult;
+}
+
+export const logger: {
+  error(message: string, meta?: Record<string, any>): void;
+  warn(message: string, meta?: Record<string, any>): void;
+  info(message: string, meta?: Record<string, any>): void;
+  debug(message: string, meta?: Record<string, any>): void;
+  setLevel(level: LogLevel): void;
+  setConsoleEnabled(enabled: boolean): void;
+};
+
+/**
+ * Map a test UUID to Playwright testInfo for result reporting
+ *
+ * @param testInfo - Playwright test info object from test function
+ * @param uuid - Appliqation test UUID (format: nid-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
+ *
+ * @throws {Error} If testInfo is not provided or invalid
+ *
+ * @example
+ * ```typescript
+ * import { test } from '@playwright/test';
+ * import { mapAppqUuid } from '@appliqation/automation-sdk/utils';
+ *
+ * test('login functionality', async ({ page }, testInfo) => {
+ *   mapAppqUuid(testInfo, '1141-6d2827f3-1bc2-405c-95b4-6a09e8b64148');
+ *   await page.goto('/login');
+ *   // ... test implementation
+ * });
+ * ```
+ */
+export function mapAppqUuid(testInfo: any, uuid: string): void;

package/src/index.js

@@ -0,0 +1,26 @@
+/**
+ * Appliqation Automation SDK
+ *
+ * Main entry point for the SDK - New Architecture with API Key Authentication
+ */
+
+const AppliqationClient = require('./AppliqationClient');
+const UuidValidator = require('./utils/UuidValidator');
+const PayloadBuilder = require('./utils/PayloadBuilder');
+const logger = require('./utils/logger');
+const playwright = require('./playwright');
+
+// Export main client class
+module.exports = AppliqationClient;
+
+// Export utilities as named exports
+module.exports.AppliqationClient = AppliqationClient;
+module.exports.UuidValidator = UuidValidator;
+module.exports.PayloadBuilder = PayloadBuilder;
+module.exports.logger = logger;
+
+// Export Playwright utilities
+module.exports.playwright = playwright;
+
+// Export default
+module.exports.default = AppliqationClient;

package/src/playwright/JwtBrowserAuth.js

@@ -0,0 +1,240 @@
+const axios = require('axios');
+const https = require('https');
+const fs = require('fs');
+const jwt = require('jsonwebtoken');
+const logger = require('../utils/logger');
+
+/**
+ * JWT Browser Authentication Manager
+ *
+ * Handles browser JWT authentication with automatic token refresh
+ * for Playwright test frameworks.
+ *
+ * Features:
+ * - Automatic JWT token refresh when approaching expiry
+ * - Browser cookie management
+ * - Storage state synchronization
+ * - Zero-configuration setup
+ */
+class JwtBrowserAuth {
+  constructor(config) {
+    this.baseUrl = config.baseUrl;
+    this.apiKey = config.apiKey;
+    this.projectKey = config.projectKey;
+    this.storageStatePath = config.storageStatePath || '.auth/user.json';
+    this.refreshThresholdMinutes = config.refreshThresholdMinutes || 5;
+    this.rejectUnauthorized = config.rejectUnauthorized !== undefined ? config.rejectUnauthorized : true;
+
+    this.jwtToken = null;
+    this.jwtExpiry = null;
+  }
+
+  /**
+   * Decode JWT token to extract expiry time
+   */
+  decodeToken(token) {
+    try {
+      return jwt.decode(token);
+    } catch (error) {
+      logger.error('Failed to decode JWT token', { error: error.message });
+      return null;
+    }
+  }
+
+  /**
+   * Get browser JWT token from API
+   */
+  async getBrowserJwt() {
+    try {
+      logger.info('Requesting browser JWT token...');
+
+      const response = await axios.post(`${this.baseUrl}/api/auth/jwt/browser`, {
+        api_key: this.apiKey
+      }, {
+        headers: { 'Content-Type': 'application/json' },
+        timeout: 30000,
+        httpsAgent: new https.Agent({ rejectUnauthorized: this.rejectUnauthorized })
+      });
+
+      if (!response.data || !response.data.jwt_token) {
+        throw new Error('No JWT token received from server');
+      }
+
+      this.jwtToken = response.data.jwt_token;
+
+      // Decode token to get actual expiry
+      const decoded = this.decodeToken(this.jwtToken);
+      if (decoded && decoded.exp) {
+        this.jwtExpiry = decoded.exp * 1000;
+      } else {
+        const expiresIn = response.data.expires_in || 3600;
+        this.jwtExpiry = Date.now() + (expiresIn * 1000);
+      }
+
+      logger.info('Browser JWT token received', {
+        expiresAt: new Date(this.jwtExpiry).toISOString(),
+        minutesUntilExpiry: this.getTimeUntilExpiry()
+      });
+
+      return response.data;
+    } catch (error) {
+      logger.error('Failed to get browser JWT token', { error: error.message });
+      throw error;
+    }
+  }
+
+  /**
+   * Check if JWT token should be refreshed
+   */
+  shouldRefresh() {
+    if (!this.jwtExpiry) return true;
+    const thresholdMs = this.refreshThresholdMinutes * 60 * 1000;
+    const timeUntilExpiry = this.jwtExpiry - Date.now();
+    return timeUntilExpiry <= thresholdMs;
+  }
+
+  /**
+   * Get time until token expiry in minutes
+   */
+  getTimeUntilExpiry() {
+    if (!this.jwtExpiry) return 0;
+    return Math.max(0, Math.floor((this.jwtExpiry - Date.now()) / 1000 / 60));
+  }
+
+  /**
+   * Refresh browser JWT token in the page context
+   */
+  async refreshBrowserJwt(page) {
+    try {
+      logger.debug('Checking JWT token expiry...', {
+        minutesUntilExpiry: this.getTimeUntilExpiry()
+      });
+
+      if (!this.shouldRefresh()) {
+        logger.debug('JWT token is still valid, no refresh needed');
+        return;
+      }
+
+      logger.info('Refreshing browser JWT token...');
+
+      // Get new JWT token
+      const response = await this.getBrowserJwt();
+      const newToken = response.jwt_token;
+
+      // Update cookie in the browser context
+      const context = page.context();
+      const domain = new URL(this.baseUrl).hostname;
+
+      // Get existing cookies
+      const cookies = await context.cookies();
+      const otherCookies = cookies.filter(c => c.name !== 'appliqation_jwt');
+
+      // Clear all cookies and re-add them with new JWT
+      await context.clearCookies();
+
+      if (otherCookies.length > 0) {
+        await context.addCookies(otherCookies);
+      }
+
+      // Add new JWT cookie
+      await context.addCookies([{
+        name: 'appliqation_jwt',
+        value: newToken,
+        domain: domain,
+        path: '/',
+        httpOnly: true,
+        secure: this.baseUrl.startsWith('https'),
+        sameSite: 'Lax'
+      }]);
+
+      logger.info('Browser JWT token refreshed successfully', {
+        minutesUntilExpiry: this.getTimeUntilExpiry()
+      });
+
+      // Update storage state file
+      await this.updateStorageState(context);
+
+    } catch (error) {
+      logger.error('Failed to refresh browser JWT token', { error: error.message });
+      throw error;
+    }
+  }
+
+  /**
+   * Update the storage state file with new cookies
+   */
+  async updateStorageState(context) {
+    try {
+      await context.storageState({ path: this.storageStatePath });
+      logger.debug('Updated storage state', { path: this.storageStatePath });
+    } catch (error) {
+      logger.warn('Failed to update storage state', { error: error.message });
+    }
+  }
+
+  /**
+   * Load JWT info from storage state file
+   */
+  loadFromStorageState() {
+    try {
+      if (!fs.existsSync(this.storageStatePath)) {
+        logger.debug('No storage state file found', { path: this.storageStatePath });
+        return;
+      }
+
+      const storageState = JSON.parse(fs.readFileSync(this.storageStatePath, 'utf8'));
+      const jwtCookie = storageState.cookies?.find(c => c.name === 'appliqation_jwt');
+
+      if (jwtCookie) {
+        this.jwtToken = jwtCookie.value;
+        const decoded = this.decodeToken(this.jwtToken);
+        if (decoded && decoded.exp) {
+          this.jwtExpiry = decoded.exp * 1000;
+          logger.debug('Loaded JWT from storage state', {
+            minutesUntilExpiry: this.getTimeUntilExpiry()
+          });
+        }
+      }
+    } catch (error) {
+      logger.warn('Failed to load JWT from storage state', { error: error.message });
+    }
+  }
+
+  /**
+   * Setup initial browser authentication
+   * Creates JWT token and saves to storage state
+   */
+  async setupInitialAuth(browserContext) {
+    try {
+      logger.info('Setting up initial browser JWT authentication...');
+
+      // Get browser JWT token
+      const response = await this.getBrowserJwt();
+      const jwtToken = response.jwt_token;
+
+      // Set JWT token as cookie
+      const domain = new URL(this.baseUrl).hostname;
+      await browserContext.addCookies([{
+        name: 'appliqation_jwt',
+        value: jwtToken,
+        domain: domain,
+        path: '/',
+        httpOnly: true,
+        secure: this.baseUrl.startsWith('https'),
+        sameSite: 'Lax'
+      }]);
+
+      logger.info('Browser JWT authentication setup complete', {
+        domain,
+        minutesUntilExpiry: this.getTimeUntilExpiry()
+      });
+
+      return jwtToken;
+    } catch (error) {
+      logger.error('Failed to setup initial browser authentication', { error: error.message });
+      throw error;
+    }
+  }
+}
+
+module.exports = JwtBrowserAuth;

package/src/playwright/fixture.js

@@ -0,0 +1,92 @@
+// Import Playwright test dynamically to avoid circular dependencies
+let baseTest;
+try {
+  baseTest = require('@playwright/test').test;
+} catch (error) {
+  // Fallback if @playwright/test is not available
+  console.warn('⚠️  @playwright/test not found. JWT auto-refresh will not be available.');
+  baseTest = null;
+}
+
+const JwtBrowserAuth = require('./JwtBrowserAuth');
+require('dotenv').config();
+
+/**
+ * Appliqation Playwright Fixture with Auto JWT Refresh
+ *
+ * This fixture automatically handles JWT browser authentication with auto-refresh.
+ * Simply import this instead of @playwright/test and authentication is handled automatically.
+ *
+ * USAGE:
+ * ------
+ * // In your test file:
+ * const { test, expect } = require('@appliqation/automation-sdk/playwright');
+ *
+ * test('my test', async ({ page }) => {
+ *   // JWT is automatically refreshed before each test if needed
+ *   await page.goto('/dashboard');
+ * });
+ *
+ * CONFIGURATION:
+ * --------------
+ * Set these environment variables in your .env file:
+ * - APPLIQATION_BASE_URL
+ * - APPLIQATION_API_KEY
+ * - APPLIQATION_PROJECT_KEY
+ */
+
+// Create the fixture only if Playwright is available
+let test, expect;
+
+if (baseTest) {
+  test = baseTest.extend({
+    page: async ({ page }, use) => {
+      // Get configuration from environment
+      const baseUrl = process.env.APPLIQATION_BASE_URL;
+      const apiKey = process.env.APPLIQATION_API_KEY;
+      const projectKey = process.env.APPLIQATION_PROJECT_KEY;
+
+      // If API key is not configured, skip JWT refresh
+      if (!apiKey) {
+        await use(page);
+        return;
+      }
+
+      // Initialize JWT browser auth manager
+      const jwtAuth = new JwtBrowserAuth({
+        baseUrl,
+        apiKey,
+        projectKey,
+        storageStatePath: '.auth/user.json',
+        refreshThresholdMinutes: 5
+      });
+
+      // Load existing JWT from storage state
+      jwtAuth.loadFromStorageState();
+
+      // Refresh JWT if needed before test runs
+      try {
+        await jwtAuth.refreshBrowserJwt(page);
+      } catch (error) {
+        // Log error but don't fail the test
+        // The test might still work with existing token
+        console.warn('⚠️  JWT refresh failed, continuing with existing token:', error.message);
+      }
+
+      // Run the test
+      await use(page);
+
+      // No cleanup needed - JWT is managed automatically
+    },
+  });
+
+  expect = require('@playwright/test').expect;
+} else {
+  test = null;
+  expect = null;
+}
+
+module.exports = {
+  test,
+  expect
+};