@appliqation/automation-sdk 2.1.0

package/src/playwright/global-setup.js

@@ -0,0 +1,243 @@
+/**
+ * Global Setup for JWT Browser Authentication
+ *
+ * This module automatically sets up browser authentication using JWT tokens
+ * instead of traditional username/password login (setup-auth.js).
+ *
+ * How it works:
+ * 1. Uses API Key to call /api/automation/run/create
+ * 2. Receives JWT token from backend
+ * 3. Navigates browser to app with ?qonsole_token={jwt}
+ * 4. Backend validates JWT and establishes session
+ * 5. Saves authenticated state to .auth/jwt.json
+ * 6. All tests use this authenticated state
+ *
+ * Benefits:
+ * - No username/password in .env
+ * - No manual setup step required
+ * - 1-hour token validity
+ * - Auto-refresh support
+ * - Works in CI/CD environments
+ *
+ * @module playwright/global-setup
+ */
+
+const { chromium } = require('@playwright/test');
+const axios = require('axios');
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Setup JWT-based browser authentication
+ *
+ * @param {Object} config - Playwright config object
+ * @returns {Promise<void>}
+ */
+async function globalSetup(config) {
+  console.log('\n🔐 Setting up JWT browser authentication...\n');
+
+  // Extract SDK configuration from reporter config or use env
+  const sdkConfig = extractSDKConfig(config);
+
+  // Validate required configuration
+  if (!sdkConfig.apiKey) {
+    console.error('❌ APPLIQATION_API_KEY is required for JWT authentication');
+    console.error('   Please add to your .env file:\n');
+    console.error('   APPLIQATION_API_KEY=appq_live_xxxxx\n');
+    throw new Error('Missing APPLIQATION_API_KEY');
+  }
+
+  if (!sdkConfig.baseUrl) {
+    console.error('❌ APPLIQATION_BASE_URL is required');
+    throw new Error('Missing APPLIQATION_BASE_URL');
+  }
+
+  // Determine if JWT auth is enabled
+  const useJwtAuth = sdkConfig.useJwtAuth !== false; // Default: true
+
+  if (!useJwtAuth) {
+    console.log('ℹ️  JWT authentication disabled. Using legacy session auth.\n');
+    return;
+  }
+
+  try {
+    // Step 1: Get JWT token from API
+    console.log('📡 Requesting JWT token from Appliqation backend...');
+    const jwtData = await getJWTToken(sdkConfig);
+
+    if (!jwtData.jwt_token) {
+      console.warn('⚠️  No JWT token received. Falling back to legacy auth.');
+      return;
+    }
+
+    console.log(`✅ JWT token received (expires in 1 hour)`);
+    console.log(`   Run ID: ${jwtData.run_id}\n`);
+
+    // Step 2: Setup browser with JWT
+    console.log('🌐 Setting up browser session with JWT...');
+    await setupBrowserWithJWT(sdkConfig, jwtData.jwt_token);
+
+    console.log('✅ Browser authentication setup complete!');
+    console.log('📄 Authenticated state saved to: .auth/jwt.json\n');
+    console.log('✨ Tests will run with JWT authentication!\n');
+
+    // Store for use in tests
+    process.env.APPLIQATION_JWT_TOKEN = jwtData.jwt_token;
+    process.env.APPLIQATION_RUN_ID = jwtData.run_id;
+
+  } catch (error) {
+    console.error('\n❌ JWT authentication setup failed:', error.message);
+    console.error('\n💡 Troubleshooting:');
+    console.error('   1. Check APPLIQATION_API_KEY is valid');
+    console.error('   2. Check APPLIQATION_BASE_URL is accessible');
+    console.error('   3. Check backend has QONSOLE_JWT_SECRET configured');
+    console.error('   4. Try running: npm run setup-auth (legacy method)\n');
+
+    // Don't fail the test run - fall back to legacy auth
+    console.warn('⚠️  Falling back to legacy authentication method\n');
+  }
+}
+
+/**
+ * Extract SDK configuration from Playwright config
+ *
+ * @param {Object} config - Playwright config
+ * @returns {Object} SDK configuration
+ */
+function extractSDKConfig(config) {
+  // Try to find SDK config in reporter configuration
+  let sdkConfig = {};
+
+  if (config.reporter) {
+    const reporters = Array.isArray(config.reporter) ? config.reporter : [config.reporter];
+
+    for (const reporter of reporters) {
+      if (Array.isArray(reporter)) {
+        const [reporterPath, reporterConfig] = reporter;
+        if (reporterPath && reporterPath.includes('appliqation')) {
+          sdkConfig = reporterConfig || {};
+          break;
+        }
+      }
+    }
+  }
+
+  // Fallback to environment variables
+  return {
+    baseUrl: sdkConfig.baseUrl || process.env.APPLIQATION_BASE_URL,
+    apiKey: sdkConfig.apiKey || process.env.APPLIQATION_API_KEY,
+    projectKey: sdkConfig.projectKey || process.env.APPLIQATION_PROJECT_KEY,
+    scenarioId: sdkConfig.scenarioId || parseInt(process.env.APPLIQATION_SCENARIO_ID) || 0,
+    environment: sdkConfig.environment || process.env.APPLIQATION_ENVIRONMENT || 'Local',
+    appUrl: sdkConfig.appUrl || process.env.APPLIQATION_APP_URL || sdkConfig.baseUrl || process.env.APPLIQATION_BASE_URL,
+    useJwtAuth: sdkConfig.useJwtAuth !== undefined ? sdkConfig.useJwtAuth : process.env.APPLIQATION_USE_JWT_AUTH !== 'false',
+    runTitle: sdkConfig.runTitle || process.env.APPLIQATION_RUN_TITLE || `JWT Auth Setup - ${new Date().toISOString()}`,
+  };
+}
+
+/**
+ * Get JWT token from Appliqation API
+ *
+ * @param {Object} sdkConfig - SDK configuration
+ * @returns {Promise<Object>} JWT data { jwt_token, run_id }
+ */
+async function getJWTToken(sdkConfig) {
+  const endpoint = `${sdkConfig.baseUrl.replace(/\/$/, '')}/api/automation/run/create`;
+
+  const payload = {
+    project_key: sdkConfig.projectKey,
+    scenario_id: sdkConfig.scenarioId || 0,
+    environment: sdkConfig.environment,
+    title: sdkConfig.runTitle,
+    browsers: ['Chrome'], // Default browser for setup
+    device: 'Desktop',
+    os: process.platform === 'darwin' ? 'macOS' : process.platform === 'win32' ? 'Windows' : 'Linux',
+  };
+
+  try {
+    const response = await axios.post(endpoint, payload, {
+      headers: {
+        'Content-Type': 'application/json',
+        'X-API-Key': sdkConfig.apiKey,
+      },
+      httpsAgent: new https.Agent({
+        rejectUnauthorized: false, // Allow self-signed certs in dev
+      }),
+      validateStatus: (status) => status < 500,
+    });
+
+    if (response.status !== 200 && response.status !== 201) {
+      throw new Error(`API returned status ${response.status}: ${response.data?.message || 'Unknown error'}`);
+    }
+
+    return {
+      jwt_token: response.data.jwt_token,
+      run_id: response.data.run_id,
+      metadata: response.data.metadata,
+    };
+
+  } catch (error) {
+    if (error.response) {
+      throw new Error(`API error: ${error.response.status} - ${error.response.data?.message || error.message}`);
+    }
+    throw new Error(`Network error: ${error.message}`);
+  }
+}
+
+/**
+ * Setup browser session with JWT token
+ *
+ * @param {Object} sdkConfig - SDK configuration
+ * @param {string} jwtToken - JWT token
+ * @returns {Promise<void>}
+ */
+async function setupBrowserWithJWT(sdkConfig, jwtToken) {
+  const browser = await chromium.launch({
+    headless: true,
+  });
+
+  const context = await browser.newContext({
+    ignoreHTTPSErrors: true, // Allow self-signed certs in dev
+  });
+
+  const page = await context.newPage();
+
+  try {
+    // Navigate to app with JWT token in query parameter
+    const appUrl = sdkConfig.appUrl.replace(/\/$/, '');
+    const separator = appUrl.includes('?') ? '&' : '?';
+    const urlWithToken = `${appUrl}${separator}qonsole_token=${encodeURIComponent(jwtToken)}`;
+
+    console.log(`   Navigating to: ${appUrl}...`);
+    await page.goto(urlWithToken, {
+      waitUntil: 'networkidle',
+      timeout: 30000,
+    });
+
+    // Wait a bit for session to be established
+    await page.waitForTimeout(2000);
+
+    // Verify authentication worked
+    const currentUrl = page.url();
+    if (currentUrl.includes('/user/login')) {
+      throw new Error('JWT authentication failed - redirected to login page');
+    }
+
+    // Save authenticated state
+    const authDir = path.resolve('.auth');
+    if (!fs.existsSync(authDir)) {
+      fs.mkdirSync(authDir, { recursive: true });
+    }
+
+    await context.storageState({ path: '.auth/jwt.json' });
+    console.log('   ✓ Authenticated state saved');
+
+  } catch (error) {
+    throw new Error(`Browser setup failed: ${error.message}`);
+  } finally {
+    await browser.close();
+  }
+}
+
+module.exports = globalSetup;

package/src/playwright/helpers/jwt-browser-auth.js

@@ -0,0 +1,227 @@
+/**
+ * JWT Browser Authentication Helper
+ *
+ * Provides utilities for managing JWT-based browser authentication in Playwright tests.
+ * Handles token injection, validation, and refresh for both Appliqation and external apps.
+ *
+ * @module playwright/helpers/jwt-browser-auth
+ */
+
+const axios = require('axios');
+const https = require('https');
+
+class JWTBrowserAuth {
+  /**
+   * Create a JWT Browser Auth helper
+   *
+   * @param {Object} config - Configuration object
+   * @param {string} config.baseUrl - Appliqation backend URL
+   * @param {string} config.apiKey - API key for authentication
+   * @param {string} config.appUrl - Application URL to test (optional, defaults to baseUrl)
+   */
+  constructor(config) {
+    this.baseUrl = config.baseUrl;
+    this.apiKey = config.apiKey;
+    this.appUrl = config.appUrl || config.baseUrl;
+    this.jwtToken = null;
+    this.jwtExpiry = null;
+    this.runId = null;
+  }
+
+  /**
+   * Get current JWT token, refreshing if expired
+   *
+   * @returns {Promise<string>} JWT token
+   */
+  async getToken() {
+    if (this.jwtToken && !this.isTokenExpired()) {
+      return this.jwtToken;
+    }
+
+    // Token expired or doesn't exist, get new one
+    await this.refreshToken();
+    return this.jwtToken;
+  }
+
+  /**
+   * Check if current token is expired
+   *
+   * @returns {boolean} True if expired
+   */
+  isTokenExpired() {
+    if (!this.jwtExpiry) {
+      return true;
+    }
+
+    // Consider expired if less than 5 minutes remaining
+    const now = Math.floor(Date.now() / 1000);
+    return (this.jwtExpiry - now) < 300;
+  }
+
+  /**
+   * Refresh JWT token from API
+   *
+   * @returns {Promise<void>}
+   */
+  async refreshToken() {
+    const endpoint = `${this.baseUrl.replace(/\/$/, '')}/api/automation/run/create`;
+
+    try {
+      const response = await axios.post(
+        endpoint,
+        {
+          project_key: process.env.APPLIQATION_PROJECT_KEY,
+          scenario_id: parseInt(process.env.APPLIQATION_SCENARIO_ID) || 0,
+          environment: process.env.APPLIQATION_ENVIRONMENT || 'Local',
+          title: `JWT Refresh - ${new Date().toISOString()}`,
+          browsers: ['Chrome'],
+          device: 'Desktop',
+          os: process.platform === 'darwin' ? 'macOS' : process.platform === 'win32' ? 'Windows' : 'Linux',
+        },
+        {
+          headers: {
+            'Content-Type': 'application/json',
+            'X-API-Key': this.apiKey,
+          },
+          httpsAgent: new https.Agent({
+            rejectUnauthorized: false,
+          }),
+        }
+      );
+
+      this.jwtToken = response.data.jwt_token;
+      this.runId = response.data.run_id;
+      this.jwtExpiry = this.parseJwtExpiry(this.jwtToken);
+
+    } catch (error) {
+      throw new Error(`Failed to refresh JWT token: ${error.message}`);
+    }
+  }
+
+  /**
+   * Parse JWT token to extract expiry time
+   *
+   * @param {string} token - JWT token
+   * @returns {number|null} Unix timestamp of expiry
+   */
+  parseJwtExpiry(token) {
+    try {
+      const parts = token.split('.');
+      if (parts.length !== 3) {
+        return null;
+      }
+
+      const payload = JSON.parse(Buffer.from(parts[1], 'base64').toString());
+      return payload.exp || null;
+    } catch (error) {
+      console.warn('Failed to parse JWT expiry:', error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Inject JWT into browser context via URL navigation
+   *
+   * @param {import('@playwright/test').Page} page - Playwright page
+   * @param {string} targetUrl - URL to navigate to (optional)
+   * @returns {Promise<void>}
+   */
+  async injectJwtIntoContext(page, targetUrl = null) {
+    const token = await this.getToken();
+    const url = targetUrl || this.appUrl;
+
+    // Add JWT as query parameter
+    const separator = url.includes('?') ? '&' : '?';
+    const urlWithToken = `${url}${separator}qonsole_token=${encodeURIComponent(token)}`;
+
+    await page.goto(urlWithToken, {
+      waitUntil: 'networkidle',
+      timeout: 30000,
+    });
+  }
+
+  /**
+   * Validate that JWT session is active in browser
+   *
+   * @param {import('@playwright/test').Page} page - Playwright page
+   * @returns {Promise<boolean>} True if session is active
+   */
+  async validateJwtSession(page) {
+    try {
+      // Check if we're on login page (authentication failed)
+      const currentUrl = page.url();
+      if (currentUrl.includes('/user/login')) {
+        return false;
+      }
+
+      // Check for common authenticated elements
+      const isAuthenticated = await page.evaluate(() => {
+        // Check for user menu or authenticated indicators
+        const userMenu = document.querySelector('.user-menu, [data-user-menu], #user-menu');
+        const logoutLink = document.querySelector('a[href*="logout"]');
+        const loginForm = document.querySelector('form[action*="login"]');
+
+        return (userMenu !== null || logoutLink !== null) && loginForm === null;
+      });
+
+      return isAuthenticated;
+
+    } catch (error) {
+      console.warn('Failed to validate JWT session:', error.message);
+      return false;
+    }
+  }
+
+  /**
+   * Get authenticated URL with JWT token
+   *
+   * @param {string} path - Path to append to base URL (optional)
+   * @returns {Promise<string>} URL with JWT token
+   */
+  async getAuthenticatedUrl(path = '') {
+    const token = await this.getToken();
+    const baseUrl = this.appUrl.replace(/\/$/, '');
+    const fullPath = path.startsWith('/') ? path : `/${path}`;
+    const url = `${baseUrl}${fullPath}`;
+
+    const separator = url.includes('?') ? '&' : '?';
+    return `${url}${separator}qonsole_token=${encodeURIComponent(token)}`;
+  }
+
+  /**
+   * Refresh token if needed before long-running operations
+   *
+   * @returns {Promise<void>}
+   */
+  async refreshJwtIfNeeded() {
+    if (this.isTokenExpired()) {
+      console.log('🔄 JWT token expired, refreshing...');
+      await this.refreshToken();
+      console.log('✅ JWT token refreshed');
+    }
+  }
+
+  /**
+   * Get current run ID
+   *
+   * @returns {string|null} Run ID
+   */
+  getRunId() {
+    return this.runId;
+  }
+
+  /**
+   * Create JWT auth helper from environment variables
+   *
+   * @returns {JWTBrowserAuth} Auth helper instance
+   */
+  static fromEnv() {
+    return new JWTBrowserAuth({
+      baseUrl: process.env.APPLIQATION_BASE_URL,
+      apiKey: process.env.APPLIQATION_API_KEY,
+      appUrl: process.env.APPLIQATION_APP_URL || process.env.APPLIQATION_BASE_URL,
+    });
+  }
+}
+
+module.exports = { JWTBrowserAuth };

package/src/playwright/index.js

@@ -0,0 +1,16 @@
+/**
+ * Appliqation Playwright Integration
+ *
+ * Provides Playwright-specific utilities including:
+ * - JWT browser authentication with auto-refresh
+ * - Playwright test fixture with automatic token management
+ */
+
+const JwtBrowserAuth = require('./JwtBrowserAuth');
+const { test, expect } = require('./fixture');
+
+module.exports = {
+  JwtBrowserAuth,
+  test,
+  expect
+};