qa360 2.1.7 → 2.2.0

package/core/src/adapters/playwright-native-api.ts

@@ -0,0 +1,619 @@
+/**
+ * QA360 Playwright Native API Adapter
+ *
+ * Uses Playwright's native APIRequestContext for HTTP testing.
+ * No browser launch required - lighter and faster than browser-based approach.
+ *
+ * @see https://playwright.dev/docs/api/class-apirequestcontext
+ *
+ * Benefits over browser-based approach:
+ * - No browser overhead (faster startup, lower memory)
+ * - Direct HTTP requests
+ * - Same API testing capabilities
+ * - Better for CI/CD environments
+ */
+
+import * as playwright from 'playwright';
+import { ApiTarget, PackBudgets } from '../types/pack-v1.js';
+import { SecurityRedactor } from '../security/redactor.js';
+import { AuthCredentials } from '../auth/index.js';
+import { ResponseCache, generateCacheKey } from '../cache/lru-cache.js';
+
+export interface NativeApiTestConfig {
+  target: ApiTarget;
+  budgets?: PackBudgets;
+  timeout?: number;
+  retries?: number;
+  auth?: AuthCredentials;
+  /**
+   * Basic auth credentials (username/password)
+   */
+  basicAuth?: { username: string; password: string };
+  /**
+   * Request body for POST/PUT/PATCH
+   */
+  body?: Record<string, unknown> | string;
+  /**
+   * Storage state to persist cookies/auth between requests
+   */
+  storageState?: Record<string, unknown> | string;
+  /**
+   * Cache configuration for HTTP responses
+   */
+  cache?: {
+    /** Enable caching (default: false) */
+    enabled?: boolean;
+    /** TTL in milliseconds (default: 300000 = 5 minutes) */
+    ttl?: number;
+    /** Maximum cache size in bytes (default: 10MB) */
+    maxSizeBytes?: number;
+    /** Maximum number of entries (default: 100) */
+    maxSize?: number;
+  };
+}
+
+export interface ApiTestResult {
+  endpoint: string;
+  method: string;
+  status: number;
+  responseTime: number;
+  success: boolean;
+  error?: string;
+  headers?: Record<string, string>;
+  body?: any;
+  attempts?: number;
+}
+
+export interface NativeApiSmokeResult {
+  success: boolean;
+  results: ApiTestResult[];
+  summary: {
+    total: number;
+    passed: number;
+    failed: number;
+    avgResponseTime: number;
+    totalAttempts: number;
+  };
+  junit?: string;
+  error?: string;
+}
+
+/**
+ * Playwright Native API Adapter
+ *
+ * Uses playwright.request.newContext() for direct HTTP requests
+ * without launching a browser.
+ */
+export class PlaywrightNativeApiAdapter {
+  private requestContext?: playwright.APIRequestContext;
+  private redactor: SecurityRedactor;
+  private auth?: AuthCredentials;
+  private cache?: ResponseCache<ApiTestResult>;
+
+  constructor() {
+    this.redactor = SecurityRedactor.forLogs();
+  }
+
+  /**
+   * Set authentication credentials for requests
+   */
+  setAuth(credentials?: AuthCredentials): void {
+    this.auth = credentials;
+  }
+
+  /**
+   * Execute API smoke tests using Playwright's native API
+   */
+  async runSmokeTests(config: NativeApiTestConfig): Promise<NativeApiSmokeResult> {
+    try {
+      this.auth = config.auth;
+
+      // Initialize cache if enabled
+      if (config.cache?.enabled) {
+        this.cache = new ResponseCache<ApiTestResult>({
+          maxSize: config.cache.maxSize ?? 100,
+          ttl: config.cache.ttl ?? 300000,
+          maxSizeBytes: config.cache.maxSizeBytes ?? 10 * 1024 * 1024,
+          verbose: false
+        });
+        console.log(`📦 Cache enabled: max=${config.cache.maxSize ?? 100}, ttl=${config.cache.ttl ?? 300000}ms`);
+      }
+
+      await this.setupRequestContext(config);
+
+      const results: ApiTestResult[] = [];
+      const smokeTests = config.target.smoke || [`GET ${config.target.baseUrl}/health -> 200`];
+
+      console.log(`🌐 Running API smoke tests with Playwright Native (${smokeTests.length} endpoints)`);
+
+      for (const test of smokeTests) {
+        // Check cache first if enabled
+        const cacheKey = this.cache ? generateCacheKey({
+          method: test.split(' ')[0],
+          url: config.target.baseUrl,
+          headers: this.auth?.headers
+        }) : '';
+
+        let testResult: ApiTestResult;
+
+        if (this.cache) {
+          testResult = await this.cache.getOrFetch(cacheKey, () => this.executeApiTest(test, config));
+          const cached = this.cache.has(cacheKey);
+          const cacheIndicator = cached ? '📦' : '🌐';
+          if (testResult.success) {
+            console.log(`  ${cacheIndicator} ✅ ${testResult.method} ${testResult.endpoint} -> ${testResult.status} (${testResult.responseTime}ms)`);
+          } else {
+            const errorMsg = testResult.error || 'Request failed';
+            const retryInfo = testResult.attempts && testResult.attempts > 1
+              ? ` (after ${testResult.attempts} attempts)`
+              : '';
+            console.log(`  ${cacheIndicator} ❌ ${testResult.method} ${testResult.endpoint} -> ${errorMsg}${retryInfo}`);
+          }
+        } else {
+          testResult = await this.executeApiTest(test, config);
+          if (testResult.success) {
+            console.log(`  ✅ ${testResult.method} ${testResult.endpoint} -> ${testResult.status} (${testResult.responseTime}ms)`);
+          } else {
+            const errorMsg = testResult.error || 'Request failed';
+            const retryInfo = testResult.attempts && testResult.attempts > 1
+              ? ` (after ${testResult.attempts} attempts)`
+              : '';
+            console.log(`  ❌ ${testResult.method} ${testResult.endpoint} -> ${errorMsg}${retryInfo}`);
+          }
+        }
+
+        results.push(testResult);
+      }
+
+      const summary = this.calculateSummary(results);
+      const junit = this.generateJUnit(results);
+
+      let error: string | undefined;
+      if (summary.failed > 0) {
+        const failedTests = results.filter(r => !r.success);
+        const errorMessages = failedTests.map(t => t.error).filter(Boolean);
+        error = errorMessages.length > 0
+          ? `${summary.failed} endpoint(s) failed: ${errorMessages[0]}${errorMessages.length > 1 ? ` (and ${errorMessages.length - 1} more)` : ''}`
+          : `${summary.failed} endpoint(s) failed`;
+      }
+
+      return {
+        success: summary.failed === 0,
+        results,
+        summary,
+        junit,
+        error
+      };
+
+    } finally {
+      await this.cleanup();
+    }
+  }
+
+  /**
+   * Setup Playwright APIRequestContext for HTTP requests
+   */
+  private async setupRequestContext(config: NativeApiTestConfig): Promise<void> {
+    const baseOptions: any = {
+      userAgent: 'QA360-Native-API/1.0',
+    };
+
+    const headers: Record<string, string> = {
+      'Accept': 'application/json, text/plain, */*',
+      'Accept-Encoding': 'gzip, deflate, br',
+    };
+
+    // Add auth headers if provided
+    if (this.auth?.headers) {
+      Object.assign(headers, this.auth.headers);
+    }
+
+    baseOptions.extraHTTPHeaders = headers;
+
+    // Add storage state if provided
+    if (config.storageState) {
+      baseOptions.storageState = config.storageState;
+    }
+
+    // Set timeout
+    if (config.timeout) {
+      baseOptions.timeout = config.timeout;
+    }
+
+    // Create API request context using Playwright
+    this.requestContext = await playwright.request.newContext(baseOptions);
+
+    // Set basic auth if provided in config
+    if (config.basicAuth) {
+      // Note: setHTTPCredentials may not exist on APIRequestContext
+      // Using HTTPCredentials via newContext options instead
+      const creds = { username: config.basicAuth.username, password: config.basicAuth.password };
+      // Set in context options - basic auth is handled via headers
+      const authHeader = 'Basic ' + Buffer.from(`${creds.username}:${creds.password}`).toString('base64');
+      headers['Authorization'] = authHeader;
+      baseOptions.extraHTTPHeaders = headers;
+      // Recreate context with auth headers
+      await this.requestContext.dispose();
+      this.requestContext = await playwright.request.newContext(baseOptions);
+    }
+  }
+
+  /**
+   * Execute single API test with retry logic using native API
+   */
+  private async executeApiTest(
+    testSpec: string,
+    config: NativeApiTestConfig
+  ): Promise<ApiTestResult> {
+    const { method, endpoint, expectedStatus } = this.parseTestSpec(testSpec, config.target.baseUrl);
+    const maxRetries = config.retries || 0;
+
+    let lastError: string = '';
+    let lastResponse: playwright.APIResponse | null = null;
+    let attempts = 0;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      attempts++;
+      const startTime = Date.now();
+
+      try {
+        // Build request options
+        const requestOptions: any = {
+          method: method,
+          timeout: config.timeout || 30000,
+          failOnStatusCode: false, // Don't throw on non-2xx responses
+        };
+
+        // Add body for POST/PUT/PATCH (from config)
+        if (['POST', 'PUT', 'PATCH'].includes(method) && config.body) {
+          requestOptions.data = config.body;
+        }
+
+        // Make the request using Playwright's native API
+        lastResponse = await this.requestContext!.fetch(endpoint, requestOptions);
+
+        const responseTime = Date.now() - startTime;
+        const status = lastResponse.status();
+        const success = status === expectedStatus;
+
+        // Get response headers
+        const responseHeaders = lastResponse.headers();
+        const headers: Record<string, string> = {};
+        for (const [key, value] of Object.entries(responseHeaders)) {
+          headers[key] = value;
+        }
+
+        // Get response body safely
+        let body: any;
+        try {
+          const contentType = headers['content-type'] || '';
+          if (contentType.includes('application/json')) {
+            body = await lastResponse.json();
+          } else {
+            const text = await lastResponse.text();
+            body = text.substring(0, 500); // Limit body size
+          }
+        } catch {
+          body = '[Response body not readable]';
+        }
+
+        return {
+          endpoint,
+          method,
+          status,
+          responseTime,
+          success,
+          error: success ? undefined : `Expected status ${expectedStatus}, got ${status}`,
+          headers,
+          body: this.redactor.redactObject(body),
+          attempts
+        };
+
+      } catch (error) {
+        lastError = error instanceof Error ? error.message : 'Unknown error';
+
+        // Check if this is a retryable error
+        const isRetryable = this.isRetryableError(lastError);
+
+        if (isRetryable && attempt < maxRetries) {
+          const waitTime = 1000 * Math.pow(2, attempt); // Exponential backoff
+          console.log(`    🔄 Retry ${attempt + 1}/${maxRetries} for ${method} ${endpoint} (${lastError}) - waiting ${waitTime}ms`);
+          await new Promise(resolve => setTimeout(resolve, waitTime));
+          continue;
+        }
+
+        break;
+      }
+    }
+
+    // If we get here, all retries failed or request threw an error
+    return {
+      endpoint,
+      method,
+      status: lastResponse?.status() || 0,
+      responseTime: 0,
+      success: false,
+      error: this.redactor.redact(lastError),
+      attempts
+    };
+  }
+
+  /**
+   * Parse test specification string
+   * Format: "GET /path -> 200" or "POST /api/users -> 201"
+   */
+  private parseTestSpec(spec: string, baseUrl: string): {
+    method: string;
+    endpoint: string;
+    expectedStatus: number;
+  } {
+    // Validate baseUrl first
+    if (!baseUrl || typeof baseUrl !== 'string') {
+      throw new Error('baseUrl is required in gate configuration. Add "baseUrl: https://your-api.com" to the config section.');
+    }
+
+    const match = spec.match(/^(\w+)\s+(.+?)\s*->\s*(\d+)$/);
+
+    if (!match) {
+      throw new Error(`Invalid test spec format: ${spec}. Expected: "METHOD /path -> STATUS"`);
+    }
+
+    const [, method, path, statusStr] = match;
+    const expectedStatus = parseInt(statusStr, 10);
+
+    // Build full endpoint URL
+    let endpoint = path;
+    if (!path.startsWith('http')) {
+      endpoint = baseUrl.replace(/\/$/, '') + (path.startsWith('/') ? path : `/${path}`);
+    }
+
+    return {
+      method: method.toUpperCase(),
+      endpoint,
+      expectedStatus
+    };
+  }
+
+  /**
+   * Check if error is retryable
+   */
+  private isRetryableError(error: string): boolean {
+    const retryablePatterns = [
+      /ECONNRESET/,
+      /ETIMEDOUT/,
+      /ECONNREFUSED/,
+      /502 Bad Gateway/,
+      /503 Service Unavailable/,
+      /504 Gateway Timeout/,
+      /timeout/i,
+      /network/i,
+      /fetch failed/i,
+      /EPROTO/,
+    ];
+
+    return retryablePatterns.some(pattern => pattern.test(error));
+  }
+
+  /**
+   * Calculate test summary
+   */
+  private calculateSummary(results: ApiTestResult[]): {
+    total: number;
+    passed: number;
+    failed: number;
+    avgResponseTime: number;
+    totalAttempts: number;
+  } {
+    const total = results.length;
+    const passed = results.filter(r => r.success).length;
+    const failed = total - passed;
+    const avgResponseTime = total > 0 ?
+      Math.round(results.reduce((sum, r) => sum + r.responseTime, 0) / total) : 0;
+    const totalAttempts = results.reduce((sum, r) => sum + (r.attempts || 1), 0);
+
+    return { total, passed, failed, avgResponseTime, totalAttempts };
+  }
+
+  /**
+   * Generate JUnit XML fragment
+   */
+  private generateJUnit(results: ApiTestResult[]): string {
+    const summary = this.calculateSummary(results);
+    const timestamp = new Date().toISOString();
+
+    let junit = `<?xml version="1.0" encoding="UTF-8"?>
+<testsuite name="API Smoke Tests (Playwright Native)" tests="${summary.total}" failures="${summary.failed}" time="${summary.avgResponseTime / 1000}" timestamp="${timestamp}">
+`;
+
+    for (const result of results) {
+      const testName = `${result.method} ${result.endpoint}`;
+      const time = result.responseTime / 1000;
+
+      junit += `  <testcase name="${this.escapeXml(testName)}" time="${time}">
+`;
+
+      if (!result.success) {
+        const failureDetails = {
+          error: result.error,
+          status: result.status,
+          attempts: result.attempts || 1
+        };
+        junit += `    <failure message="${this.escapeXml(result.error || 'Test failed')}">${this.escapeXml(JSON.stringify(failureDetails, null, 2))}</failure>
+`;
+      }
+
+      junit += `  </testcase>
+`;
+    }
+
+    junit += `</testsuite>`;
+
+    return junit;
+  }
+
+  /**
+   * Escape XML special characters
+   */
+  private escapeXml(str: string): string {
+    return str
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&apos;');
+  }
+
+  /**
+   * Cleanup request context
+   */
+  private async cleanup(): Promise<void> {
+    if (this.requestContext) {
+      await this.requestContext.dispose();
+      this.requestContext = undefined;
+    }
+  }
+
+  /**
+   * Validate API target configuration
+   */
+  static validateConfig(target: ApiTarget): { valid: boolean; errors: string[] } {
+    const errors: string[] = [];
+
+    if (!target.baseUrl) {
+      errors.push('baseUrl is required in gate config. Add: "baseUrl: https://your-api.com"');
+    } else {
+      try {
+        new URL(target.baseUrl);
+      } catch {
+        errors.push(`baseUrl "${target.baseUrl}" is not a valid URL. Expected format: https://api.example.com`);
+      }
+    }
+
+    if (target.smoke) {
+      for (const test of target.smoke) {
+        if (!/^\w+\s+.+\s*->\s*\d+$/.test(test)) {
+          errors.push(`Invalid smoke test format: ${test}. Expected: "METHOD /path -> STATUS"`);
+        }
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+
+  /**
+   * Health check using native API
+   * Quick check if the API is accessible without running full tests
+   */
+  async healthCheck(baseUrl: string, path = '/health', timeout = 5000): Promise<boolean> {
+    try {
+      await this.setupRequestContext({
+        target: { baseUrl },
+        timeout
+      });
+
+      const endpoint = baseUrl.replace(/\/$/, '') + (path.startsWith('/') ? path : `/${path}`);
+      const response = await this.requestContext!.fetch(endpoint, {
+        method: 'GET',
+        timeout,
+        failOnStatusCode: false
+      });
+
+      // Consider 2xx and 3xx as healthy
+      return response.status() >= 200 && response.status() < 400;
+
+    } catch {
+      return false;
+    } finally {
+      await this.cleanup();
+    }
+  }
+
+  /**
+   * Get API info (useful for debugging)
+   * Returns version and capabilities
+   */
+  static getCapabilities(): {
+    adapter: string;
+    browserless: boolean;
+    features: string[];
+  } {
+    return {
+      adapter: 'playwright-native',
+      browserless: true,
+      features: [
+        'REST API testing',
+        'GraphQL support',
+        'Basic auth',
+        'Bearer token auth',
+        'Custom headers',
+        'Request/response interception',
+        'Retry logic with exponential backoff',
+        'Storage state for cookie persistence',
+        'Timeout configuration',
+        'LRU cache for HTTP responses'
+      ]
+    };
+  }
+
+  /**
+   * Get cache statistics if cache is enabled
+   */
+  getCacheStats(): {
+    enabled: boolean;
+    stats?: {
+      hits: number;
+      misses: number;
+      additions: number;
+      evictions: number;
+      size: number;
+      sizeBytes: number;
+      hitRate: number;
+      avgEntrySize: number;
+    };
+  } {
+    if (!this.cache) {
+      return { enabled: false };
+    }
+
+    return {
+      enabled: true,
+      stats: this.cache.getStats()
+    };
+  }
+
+  /**
+   * Clear the cache if enabled
+   */
+  clearCache(): void {
+    if (this.cache) {
+      this.cache.clear();
+      console.log('📦 Cache cleared');
+    }
+  }
+}
+
+/**
+ * Factory function to create a native API adapter
+ */
+export function createPlaywrightNativeApiAdapter(): PlaywrightNativeApiAdapter {
+  return new PlaywrightNativeApiAdapter();
+}
+
+/**
+ * Error class for native API adapter
+ */
+export class PlaywrightNativeApiError extends Error {
+  code = 'PLAYWRIGHT_NATIVE_API_ERROR';
+  endpoint?: string;
+  method?: string;
+
+  constructor(message: string, endpoint?: string, method?: string) {
+    super(message);
+    this.name = 'PlaywrightNativeApiError';
+    this.endpoint = endpoint;
+    this.method = method;
+  }
+}