@ash-mallick/browserstack-sync 1.3.1 → 1.4.0

package/README.md

@@ -60,29 +60,70 @@ Creates folders and test cases for all spec files in your project.
 
 ### 4. Sync Test Run Results to BrowserStack
 
-First, run your tests with JSON reporter:
+Specify your report file location:
 
 ```bash
-npx playwright test --reporter=list,json --output-file=test-results.json
+npx am-browserstack-sync-runs --report=test-results.json
 ```
 
-Then sync results:
+**Supported formats (auto-detected):**
+- Playwright JSON
+- Cypress/Mochawesome JSON  
+- JUnit XML
+
+**Configure report path** (so you don't need `--report` every time):
 
 ```bash
-npx am-browserstack-sync-runs
+# Via environment variable
+export BROWSERSTACK_REPORT_PATH=test-results.json
+
+# Or in .am-browserstack-sync.json
+{ "reportPath": "test-results.json" }
 ```
 
-Or with custom run name:
+**Generate reports** (add to your test command):
 
 ```bash
-npx am-browserstack-sync-runs --run-name="Nightly Run"
+# Playwright
+npx playwright test --reporter=json --output-file=test-results.json
+
+# Cypress
+npx cypress run --reporter mochawesome
+```
+
+**With custom run name:**
+
+```bash
+npx am-browserstack-sync-runs --report=test-results.json --run-name="Nightly Run"
 ```
 
 ---
 
-## GitLab CI Scheduled Job
+## GitLab CI Integration
 
-Add to `.gitlab-ci.yml`:
+### Option A: Your pipeline already generates reports
+
+If your existing test job generates JSON/JUnit reports, just add sync after:
+
+```yaml
+# Your existing test job
+test:
+  script:
+    - npm ci
+    - CENV=prod npx playwright test --reporter=allure-playwright,json --output-file=test-results.json
+  artifacts:
+    paths:
+      - test-results.json
+
+# Add this job to sync results to BrowserStack  
+sync_browserstack:
+  needs: [test]
+  script:
+    - npm install @ash-mallick/browserstack-sync
+    - npx am-browserstack-sync-runs --report=test-results.json --run-name="Pipeline #$CI_PIPELINE_ID"
+```
+
+### Option B: Scheduled sync job (runs tests + syncs)
 
 ```yaml
 scheduled_browserstack_sync:
@@ -90,12 +131,14 @@ scheduled_browserstack_sync:
     - if: $CI_PIPELINE_SOURCE == "schedule"
   script:
     - npm ci
-    - npx playwright test --reporter=list,json --output-file=test-results.json || true
+    - CENV=prod npx playwright test --reporter=allure-playwright,json --output-file=test-results.json || true
     - npm install @ash-mallick/browserstack-sync
-    - npx am-browserstack-sync-runs
+    - npx am-browserstack-sync-runs --report=test-results.json
 ```
 
-Add CI/CD Variables in GitLab (**Settings → CI/CD → Variables**):
+### Required CI/CD Variables
+
+Add in **Settings → CI/CD → Variables**:
 
 | Key | Value |
 |-----|-------|
@@ -103,7 +146,7 @@ Add CI/CD Variables in GitLab (**Settings → CI/CD → Variables**):
 | `BROWSERSTACK_ACCESS_KEY` | your_access_key |
 | `BROWSERSTACK_PROJECT_ID` | PR-XXXX |
 
-Create schedule in **CI/CD → Schedules → New Schedule**.
+For scheduled jobs: **CI/CD → Schedules → New Schedule**.
 
 ---
 

package/bin/sync-runs.js

@@ -34,79 +34,108 @@ if (argv.includes('--help') || argv.includes('-h')) {
 📊 BrowserStack Test Run Sync
 
 Sync your Playwright/Cypress test results to BrowserStack Test Management.
-Add this command to your existing CI pipeline after tests complete.
+Specify your report file location - supports JSON and XML formats.
 
 USAGE:
-  npx am-browserstack-sync-runs [options]
+  npx am-browserstack-sync-runs --report=<path> [options]
 
 OPTIONS:
-  --report=<path>     Path to report file (auto-detects if not specified)
+  --report=<path>     Path to your test report file (required unless configured)
   --run-name=<name>   Name for the test run (default: "CI Run - <timestamp>")
-  --format=<fmt>      Report format: playwright-json, junit (default: auto)
+  --format=<fmt>      Report format: playwright-json, mochawesome, cypress, junit (auto-detected)
   --help, -h          Show this help
 
+CONFIGURE REPORT PATH (optional - so you don't need --report every time):
+  Environment variable:  BROWSERSTACK_REPORT_PATH=test-results.json
+  Config file:           .am-browserstack-sync.json { "reportPath": "test-results.json" }
+  package.json:          "amBrowserstackSync": { "reportPath": "test-results.json" }
+
 ENVIRONMENT VARIABLES (required):
   BROWSERSTACK_USERNAME     Your BrowserStack username
   BROWSERSTACK_ACCESS_KEY   Your BrowserStack access key
   BROWSERSTACK_PROJECT_ID   Your project ID (e.g., PR-1234)
 
-EXAMPLES:
-  # Auto-detect report and sync
-  npx am-browserstack-sync-runs
+SUPPORTED REPORT FORMATS:
+  - Playwright JSON:    npx playwright test --reporter=json --output-file=test-results.json
+  - Cypress Mochawesome: npx cypress run --reporter mochawesome
+  - JUnit XML:          npx playwright test --reporter=junit --output-file=junit.xml
 
+EXAMPLES:
   # Specify report file
   npx am-browserstack-sync-runs --report=test-results.json
 
-  # Custom run name (great for CI)
-  npx am-browserstack-sync-runs --run-name="Build #\${CI_PIPELINE_ID}"
+  # With custom run name (great for CI)
+  npx am-browserstack-sync-runs --report=test-results.json --run-name="Build #123"
 
   # Sync JUnit XML results
-  npx am-browserstack-sync-runs --report=junit.xml --format=junit
+  npx am-browserstack-sync-runs --report=junit.xml
 
-ADD TO YOUR CI PIPELINE:
+CI PIPELINE EXAMPLE:
   # GitLab CI
   script:
-    - npm test  # Your existing test command
-    - npx am-browserstack-sync-runs --run-name="Pipeline #\$CI_PIPELINE_ID"
-
-  # GitHub Actions  
-  - run: npm test
-  - run: npx am-browserstack-sync-runs --run-name="Build #\${{ github.run_number }}"
-
-PREREQUISITES:
-  1. First, onboard your tests to BrowserStack:
-     npx am-browserstack-sync --all
-
-  2. Then add run sync to your pipeline:
-     npx am-browserstack-sync-runs
+    - npm ci
+    - npx playwright test --reporter=json --output-file=test-results.json || true
+    - npx am-browserstack-sync-runs --report=test-results.json --run-name="Pipeline #\$CI_PIPELINE_ID"
 `);
   process.exit(0);
 }
 
-// Auto-detect report file
-function findReportFile() {
+// Check if a report file exists at the given path
+function checkReportExists(reportPath) {
+  if (!reportPath) return null;
+  
+  const cwd = process.cwd();
+  const fullPath = path.isAbsolute(reportPath) ? reportPath : path.join(cwd, reportPath);
+  
+  if (fs.existsSync(fullPath)) {
+    const stat = fs.statSync(fullPath);
+    const ageMinutes = Math.round((Date.now() - stat.mtime.getTime()) / 60000);
+    console.log(`📄 Using report: ${reportPath}`);
+    console.log(`   Modified: ${ageMinutes < 60 ? ageMinutes + ' minutes ago' : Math.round(ageMinutes / 60) + ' hours ago'}`);
+    return fullPath;
+  }
+  
+  return null;
+}
+
+// Get report path from config or environment
+function getConfiguredReportPath() {
+  // Check environment variable first
+  if (process.env.BROWSERSTACK_REPORT_PATH) {
+    return process.env.BROWSERSTACK_REPORT_PATH;
+  }
+  
+  // Check config file
   const cwd = process.cwd();
-  const possibleFiles = [
-    'test-results.json',
-    'results.json',
-    'playwright-report/results.json',
-    'playwright-report.json',
-    'report.json',
-    'junit.xml',
-    'test-results.xml',
+  const configPaths = [
+    path.join(cwd, '.am-browserstack-sync.json'),
+    path.join(cwd, 'browserstack-sync.json'),
   ];
   
-  for (const file of possibleFiles) {
-    const fullPath = path.join(cwd, file);
-    if (fs.existsSync(fullPath)) {
-      return fullPath;
+  for (const configPath of configPaths) {
+    if (fs.existsSync(configPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        if (config.reportPath) {
+          return config.reportPath;
+        }
+      } catch {
+        // Ignore parse errors
+      }
     }
   }
   
-  // Check for playwright-report directory
-  const htmlReportDir = path.join(cwd, 'playwright-report');
-  if (fs.existsSync(htmlReportDir) && fs.statSync(htmlReportDir).isDirectory()) {
-    return htmlReportDir;
+  // Check package.json
+  const pkgPath = path.join(cwd, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      if (pkg.amBrowserstackSync?.reportPath) {
+        return pkg.amBrowserstackSync.reportPath;
+      }
+    } catch {
+      // Ignore parse errors
+    }
   }
   
   return null;
@@ -131,24 +160,60 @@ const runName = runNameArg
   ? runNameArg.slice('--run-name='.length).trim() 
   : process.env.BROWSERSTACK_RUN_NAME || `CI Run - ${new Date().toISOString().slice(0, 16).replace('T', ' ')}`;
 
-// Auto-detect report if not specified
+// Determine report path: CLI arg > env var > config file
 if (!reportPath) {
-  reportPath = findReportFile();
-  if (!reportPath) {
-    console.error(`
-❌ No test report found!
-
-Make sure your test framework generates a report file:
+  reportPath = getConfiguredReportPath();
+}
 
-  # Playwright - add to your test command:
-  npx playwright test --reporter=json --output-file=test-results.json
+// Check if report exists
+if (reportPath) {
+  const resolvedPath = checkReportExists(reportPath);
+  if (!resolvedPath) {
+    console.error(`
+❌ Report file not found: ${reportPath}
 
-  # Or specify the report path:
-  npx am-browserstack-sync-runs --report=path/to/results.json
+Make sure your test run generates this report before syncing.
 `);
     process.exit(1);
   }
-  console.log(`📄 Auto-detected report: ${reportPath}`);
+  reportPath = resolvedPath;
+} else {
+  console.error(`
+❌ No report path configured!
+
+Please specify your test report location using one of these methods:
+
+OPTION 1: Command line argument
+  npx am-browserstack-sync-runs --report=test-results.json
+
+OPTION 2: Environment variable
+  export BROWSERSTACK_REPORT_PATH=test-results.json
+  npx am-browserstack-sync-runs
+
+OPTION 3: Config file (.am-browserstack-sync.json)
+  {
+    "reportPath": "test-results.json"
+  }
+
+OPTION 4: package.json
+  {
+    "amBrowserstackSync": {
+      "reportPath": "test-results.json"
+    }
+  }
+
+GENERATING REPORTS:
+
+  Playwright:
+    npx playwright test --reporter=json --output-file=test-results.json
+
+  Cypress (mochawesome):
+    npx cypress run --reporter mochawesome
+
+  JUnit XML (both):
+    npx playwright test --reporter=junit --output-file=junit.xml
+`);
+  process.exit(1);
 }
 
 // Auto-detect format if not specified

package/lib/sync-results.js

@@ -108,6 +108,115 @@ function parseJunitXml(reportPath) {
   return results;
 }
 
+/**
+ * Parse Mochawesome JSON report format (commonly used with Cypress).
+ * @param {string} reportPath - Path to the mochawesome JSON file
+ * @returns {Array<{title: string, status: string, duration: number, error?: string}>}
+ */
+function parseMochawesome(reportPath) {
+  const report = JSON.parse(fs.readFileSync(reportPath, 'utf-8'));
+  const results = [];
+  
+  // Mochawesome structure: { results: [{ suites: [{ tests: [...] }] }] }
+  function extractTests(suites) {
+    for (const suite of suites || []) {
+      for (const test of suite.tests || []) {
+        results.push({
+          title: test.title,
+          fullTitle: test.fullTitle || `${suite.title} > ${test.title}`,
+          status: mapMochawesomeStatus(test.state || test.pass),
+          duration: test.duration || 0,
+          error: test.err?.message || test.err?.estack || '',
+          file: suite.file,
+        });
+      }
+      
+      // Recursively process nested suites
+      if (suite.suites) {
+        extractTests(suite.suites);
+      }
+    }
+  }
+  
+  // Handle both mochawesome and mochawesome-merge formats
+  if (report.results) {
+    for (const result of report.results) {
+      extractTests(result.suites);
+    }
+  } else if (report.suites) {
+    extractTests(report.suites);
+  }
+  
+  return results;
+}
+
+/**
+ * Parse Cypress JSON report (spec-based results).
+ * @param {string} reportPath - Path to the Cypress JSON report
+ * @returns {Array<{title: string, status: string, duration: number, error?: string}>}
+ */
+function parseCypressJson(reportPath) {
+  const report = JSON.parse(fs.readFileSync(reportPath, 'utf-8'));
+  const results = [];
+  
+  // Cypress native JSON structure
+  // { runs: [{ tests: [...], spec: {...} }] }
+  if (report.runs) {
+    for (const run of report.runs) {
+      for (const test of run.tests || []) {
+        const attempts = test.attempts || [];
+        const lastAttempt = attempts[attempts.length - 1] || {};
+        
+        results.push({
+          title: test.title?.join(' > ') || test.title,
+          status: mapCypressStatus(test.state || lastAttempt.state),
+          duration: test.duration || lastAttempt.duration || 0,
+          error: lastAttempt.error?.message || test.displayError || '',
+          file: run.spec?.relative || run.spec?.name,
+        });
+      }
+    }
+  }
+  
+  // Cypress Dashboard JSON structure
+  // { tests: [...] }
+  if (report.tests && !report.runs) {
+    for (const test of report.tests) {
+      results.push({
+        title: test.title || test.name,
+        status: mapCypressStatus(test.state || test.status),
+        duration: test.duration || 0,
+        error: test.error?.message || '',
+      });
+    }
+  }
+  
+  return results;
+}
+
+/**
+ * Map Mochawesome status to BrowserStack status.
+ */
+function mapMochawesomeStatus(status) {
+  if (status === true || status === 'passed') return 'passed';
+  if (status === false || status === 'failed') return 'failed';
+  if (status === 'pending' || status === 'skipped') return 'skipped';
+  return status || 'passed';
+}
+
+/**
+ * Map Cypress status to BrowserStack status.
+ */
+function mapCypressStatus(status) {
+  const map = {
+    passed: 'passed',
+    failed: 'failed',
+    pending: 'skipped',
+    skipped: 'skipped',
+  };
+  return map[status] || status;
+}
+
 /**
  * Parse Playwright HTML report's index.html or results.json
  */
@@ -211,17 +320,52 @@ export async function syncResultsFromReport(options = {}) {
   // Parse the report based on format
   console.log('\n   Parsing test results...');
   let testResults;
+  let detectedFormat = format;
   
   const stat = fs.statSync(reportPath);
   if (stat.isDirectory()) {
     // Assume it's a Playwright HTML report directory
     testResults = parsePlaywrightHtmlReport(reportPath);
+    detectedFormat = 'playwright-html';
   } else if (format === 'junit' || reportPath.endsWith('.xml')) {
     testResults = parseJunitXml(reportPath);
+    detectedFormat = 'junit-xml';
   } else {
-    testResults = parsePlaywrightJson(reportPath);
+    // Try to auto-detect JSON format by reading the file
+    const content = fs.readFileSync(reportPath, 'utf-8');
+    const json = JSON.parse(content);
+    
+    if (format === 'mochawesome' || json.stats?.testsRegistered !== undefined || (json.results && json.results[0]?.suites)) {
+      // Mochawesome format (Cypress)
+      testResults = parseMochawesome(reportPath);
+      detectedFormat = 'mochawesome';
+    } else if (format === 'cypress' || json.runs) {
+      // Cypress native JSON format
+      testResults = parseCypressJson(reportPath);
+      detectedFormat = 'cypress-json';
+    } else if (json.suites || json.config?.projects) {
+      // Playwright JSON format
+      testResults = parsePlaywrightJson(reportPath);
+      detectedFormat = 'playwright-json';
+    } else {
+      // Fallback: try Playwright first, then Mochawesome
+      try {
+        testResults = parsePlaywrightJson(reportPath);
+        detectedFormat = 'playwright-json';
+      } catch {
+        try {
+          testResults = parseMochawesome(reportPath);
+          detectedFormat = 'mochawesome';
+        } catch {
+          testResults = parseCypressJson(reportPath);
+          detectedFormat = 'cypress-json';
+        }
+      }
+    }
   }
   
+  console.log(`   Detected format: ${detectedFormat}`)
+  
   console.log(`   Found ${testResults.length} test result(s)`);
   
   if (testResults.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ash-mallick/browserstack-sync",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Sync Playwright & Cypress e2e specs to CSV and BrowserStack Test Management with FREE AI-powered test step extraction using Ollama (local).",
   "author": "Ashutosh Mallick",
   "type": "module",