@ash-mallick/browserstack-sync 1.4.0 → 1.5.0

package/README.md

@@ -1,6 +1,8 @@
 # @ash-mallick/browserstack-sync
 
-Sync Playwright/Cypress tests to BrowserStack Test Management with AI-powered test step extraction.
+Sync **Playwright** and **Cypress** e2e specs to CSV (TC-001, TC-002, …) and optionally to **BrowserStack Test Management** (one folder per spec, create/update test cases).
+
+**🦙 FREE AI-powered test step extraction** using **Ollama** — runs 100% locally, no data sent to cloud!
 
 **By Ashutosh Mallick**
 
@@ -12,183 +14,96 @@ Sync Playwright/Cypress tests to BrowserStack Test Management with AI-powered te
 npm install @ash-mallick/browserstack-sync
 ```
 
----
-
-## Quick Setup
-
-Create `.env` file:
-
-```env
-BROWSERSTACK_USERNAME=your_username
-BROWSERSTACK_ACCESS_KEY=your_access_key
-BROWSERSTACK_PROJECT_ID=PR-XXXX
-```
+Or run without installing: `npx @ash-mallick/browserstack-sync --csv-only`
 
 ---
 
-## Commands
+## Run
 
-### 1. Generate CSV Files Only (No BrowserStack)
+From your project root (where your e2e specs live):
 
 ```bash
+# Generate CSVs only
 npx am-browserstack-sync --csv-only
-```
-
-Creates CSV files with test cases in `playwright/e2e-csv/` folder.
-
----
-
-### 2. Onboard Single Spec to BrowserStack
-
-```bash
-npx am-browserstack-sync --spec=login.spec
-```
-
-Creates folder and test cases for the specified spec file.
-
----
-
-### 3. Onboard All Specs to BrowserStack
 
-```bash
+# Sync all specs, no prompt (e.g. CI)
 npx am-browserstack-sync --all
-```
-
-Creates folders and test cases for all spec files in your project.
-
----
-
-### 4. Sync Test Run Results to BrowserStack
-
-Specify your report file location:
-
-```bash
-npx am-browserstack-sync-runs --report=test-results.json
-```
-
-**Supported formats (auto-detected):**
-- Playwright JSON
-- Cypress/Mochawesome JSON  
-- JUnit XML
 
-**Configure report path** (so you don't need `--report` every time):
+# Sync only certain specs
+npx am-browserstack-sync --spec=login.spec,checkout.spec
 
-```bash
-# Via environment variable
-export BROWSERSTACK_REPORT_PATH=test-results.json
+# Disable AI analysis (use regex extraction only)
+npx am-browserstack-sync --no-ai
 
-# Or in .am-browserstack-sync.json
-{ "reportPath": "test-results.json" }
+# Use a specific Ollama model
+npx am-browserstack-sync --model=llama3.2
 ```
 
-**Generate reports** (add to your test command):
-
-```bash
-# Playwright
-npx playwright test --reporter=json --output-file=test-results.json
+**Scripts** in `package.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"
+```json
+{
+  "scripts": {
+    "sync:e2e": "am-browserstack-sync",
+    "sync:e2e-csv": "am-browserstack-sync --csv-only"
+  }
+}
 ```
 
 ---
 
-## GitLab CI Integration
+## 🦙 AI-Powered Step Analysis (FREE with Ollama)
 
-### Option A: Your pipeline already generates reports
+The tool uses **Ollama** to analyze your test code and generate **human-readable test steps**. Ollama runs **100% locally** on your machine — no data sent to cloud, completely free, no API key needed!
 
-If your existing test job generates JSON/JUnit reports, just add sync after:
+**Example transformation:**
 
-```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"
+```typescript
+// Your test code:
+test('should log in successfully', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel(/email/i).fill('user@example.com');
+  await page.getByLabel(/password/i).fill('validpassword');
+  await page.getByRole('button', { name: /sign in/i }).click();
+  await expect(page).toHaveURL(/\/dashboard/);
+});
 ```
 
-### Option B: Scheduled sync job (runs tests + syncs)
-
-```yaml
-scheduled_browserstack_sync:
-  rules:
-    - if: $CI_PIPELINE_SOURCE == "schedule"
-  script:
-    - npm ci
-    - 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 --report=test-results.json
-```
-
-### Required CI/CD Variables
-
-Add in **Settings → CI/CD → Variables**:
-
-| Key | Value |
-|-----|-------|
-| `BROWSERSTACK_USERNAME` | your_username |
-| `BROWSERSTACK_ACCESS_KEY` | your_access_key |
-| `BROWSERSTACK_PROJECT_ID` | PR-XXXX |
-
-For scheduled jobs: **CI/CD → Schedules → New Schedule**.
-
----
-
-## All Options Reference
-
-### Onboarding Command (`am-browserstack-sync`)
-
-| Option | Description |
-|--------|-------------|
-| `--csv-only` | Generate CSVs only, do not sync to BrowserStack |
-| `--all` | Sync all spec files without prompting |
-| `--spec=name` | Sync specific spec(s), comma-separated |
-| `--no-ai` | Disable AI step analysis, use regex extraction |
-| `--model=name` | Ollama model to use (default: llama3.2) |
-
-### Run Sync Command (`am-browserstack-sync-runs`)
-
-| Option | Description |
-|--------|-------------|
-| `--report=path` | Path to test report file (auto-detects if not specified) |
-| `--run-name=name` | Custom name for the test run |
-| `--format=type` | Report format: `playwright-json` or `junit` |
-
----
-
-## AI-Powered Test Steps (Optional)
+**Generated steps:**
 
-The tool uses Ollama to analyze your test code and generate human-readable test steps. Ollama runs locally - no data sent to cloud, completely free.
+| Step | Expected Result |
+|------|-----------------|
+| Navigate to /login page | Login page loads successfully |
+| Enter 'user@example.com' in the Email field | Email is entered |
+| Enter 'validpassword' in the Password field | Password is masked and entered |
+| Click the 'Sign In' button | Form is submitted |
+| Verify URL | URL matches /dashboard |
 
 ### Setup Ollama
 
-1. Download from [ollama.ai](https://ollama.ai)
-2. Pull a model:
+1. Download and install Ollama from [ollama.ai](https://ollama.ai)
+
+2. Pull a model (llama3.2 recommended):
    ```bash
    ollama pull llama3.2
    ```
-3. Start Ollama:
+
+3. Start Ollama (runs automatically on macOS, or run manually):
    ```bash
    ollama serve
    ```
 
-AI analysis runs automatically when Ollama is running. Use `--no-ai` to disable.
+4. Run the sync — AI analysis is automatic when Ollama is running!
+   ```bash
+   npx am-browserstack-sync --csv-only
+   ```
+
+### Options
+
+- `--no-ai` — Disable AI, use regex-based extraction instead
+- `--model=llama3.2` — Use a different Ollama model
+- `OLLAMA_MODEL=llama3.2` — Set default model via env variable
+- `OLLAMA_HOST=http://localhost:11434` — Custom Ollama host
 
 ### Recommended Models
 
@@ -197,16 +112,17 @@ AI analysis runs automatically when Ollama is running. Use `--no-ai` to disable.
 | `llama3.2` | 2GB | General purpose, fast (default) |
 | `codellama` | 4GB | Better code understanding |
 | `llama3.2:1b` | 1GB | Fastest, lower quality |
+| `mistral` | 4GB | Good balance |
+
+**Fallback:** If Ollama is not running, the tool automatically uses regex-based step extraction, which still provides meaningful steps.
 
 ---
 
-## Configuration (Optional)
+## Config (optional)
 
-Default directories:
-- e2e specs: `playwright/e2e`
-- CSV output: `playwright/e2e-csv`
+Defaults: e2e dir `playwright/e2e`, CSV dir `playwright/e2e-csv`. For Cypress use e.g. `cypress/e2e`.
 
-Override via `.am-browserstack-sync.json`:
+Override via **`.am-browserstack-sync.json`** in project root:
 
 ```json
 {
@@ -215,27 +131,42 @@ Override via `.am-browserstack-sync.json`:
 }
 ```
 
-Or via environment variables:
-- `PLAYWRIGHT_BROWSERSTACK_E2E_DIR`
-- `PLAYWRIGHT_BROWSERSTACK_CSV_DIR`
+Or **package.json**: `"amBrowserstackSync": { "e2eDir": "...", "csvOutputDir": "..." }`  
+Or env: `PLAYWRIGHT_BROWSERSTACK_E2E_DIR`, `PLAYWRIGHT_BROWSERSTACK_CSV_DIR`.
 
 ---
 
-## What Gets Created
+## BrowserStack sync
+
+Sync pushes your e2e tests into **BrowserStack Test Management** so you can track test cases, link runs, and keep specs in sync with one source of truth. Under your chosen project it creates **one folder per spec file** (e.g. `login.spec`, `checkout.spec`) and one **test case** per test, with title, description, steps, state (Active), type (Functional), automation status, and tags. Existing test cases are matched by title or TC-id and **updated**; new ones are **created**. No duplicates.
 
-When you run `npx am-browserstack-sync --all`:
+**Setup:**
 
-1. **CSV files** - One per spec file with test case details
-2. **BrowserStack folders** - One folder per spec file
-3. **Test cases** - Each test becomes a test case with:
-   - Title
-   - AI-generated steps (or regex-extracted)
-   - Expected results
-   - Tags
-   - Automation status
+1. In project root, create **`.env`** (do not commit):
 
-When you run `npx am-browserstack-sync-runs`:
+   ```env
+   BROWSERSTACK_USERNAME=your_username
+   BROWSERSTACK_ACCESS_KEY=your_access_key
+   BROWSERSTACK_PROJECT_ID=PR-XXXX
+   ```
+   Or use a single token: `BROWSERSTACK_API_TOKEN=your_token`
+
+2. Get credentials and project ID from [Test Management → API keys](https://test-management.browserstack.com/settings/api-keys). The project ID is in the project URL (e.g. `PR-1234`).
+
+3. **Install Ollama** for AI-powered step analysis (optional but recommended).
+
+4. Run **`npx am-browserstack-sync`** (without `--csv-only`). You'll be prompted to sync all specs or pick specific ones (unless you use `--all` or `--spec=...`). After sync, open your project in BrowserStack to see the new folders and test cases.
+
+---
+
+## What it does
+
+- Finds **Playwright** (`*.spec.*`, `*.test.*`) and **Cypress** (`*.cy.*`) spec files in your e2e dir.
+- Extracts test titles from `test('...')` / `it('...')`, assigns TC-001, TC-002, …
+- **Analyzes test code** with Ollama AI (local, free) or regex to generate human-readable steps and expected results.
+- Enriches with state (Active), type (Functional), automation (automated), tags (from spec + title).
+- Writes **one CSV per spec** (test_case_id, title, state, case_type, steps, expected_results, jira_issues, automation_status, tags, description, spec_file).
+- Optionally syncs to BrowserStack with description, steps, and tags.
+---
 
-1. **Test Run** - Created in BrowserStack
-2. **Results** - Pass/fail status for each test
-3. **Link** - URL to view results in BrowserStack
+**Author:** Ashutosh Mallick

package/bin/cli.js

@@ -2,67 +2,31 @@
 /**
  * CLI for @ash-mallick/browserstack-sync (am-browserstack-sync).
  * By Ashutosh Mallick. Run from your project root: npx am-browserstack-sync [options]
- * 
- * This command onboards your Playwright/Cypress tests to BrowserStack:
- * - Generates CSV files with test cases
- * - Creates folders in BrowserStack (one per spec file)
- * - Creates/updates test cases with AI-generated steps
+ * Uses cwd as project root; config from .env, config file, or package.json.
  *
- * OPTIONS:
+ * Options:
  *   --csv-only      Generate CSVs only, do not sync to BrowserStack
  *   --all           Sync all spec files (no interactive prompt)
- *   --spec=name     Sync only these specs (comma-separated)
- *   --no-ai         Disable AI-powered step analysis
- *   --model=name    Ollama model to use (default: llama3.2)
+ *   --spec=name     Sync only these specs (comma-separated). e.g. --spec=login.spec,checkout.spec
+ *   --no-ai         Disable AI-powered step analysis (use regex extraction only)
+ *   --model=name    Ollama model to use (default: llama3.2). e.g. --model=codellama
  *
- * EXAMPLES:
- *   npx am-browserstack-sync --all           # Onboard all tests
- *   npx am-browserstack-sync --csv-only      # Generate CSVs only
- *   npx am-browserstack-sync --spec=login    # Onboard specific spec
+ * AI Analysis (FREE, Local with Ollama):
+ *   Install Ollama from https://ollama.ai, then:
+ *     ollama pull llama3.2
+ *     ollama serve
  *
- * To sync test run results, use:
- *   npx am-browserstack-sync-runs
+ *   AI analysis is automatic when Ollama is running! No API key needed.
+ *   The AI will analyze your test code and generate human-readable steps like:
+ *     - "Navigate to /login page"
+ *     - "Enter 'user@test.com' in the Email field"
+ *     - "Click the 'Sign In' button"
+ *     - "Verify URL matches /dashboard"
  */
 
 import { runSync } from '../lib/index.js';
-import 'dotenv/config';
 
 const argv = process.argv.slice(2);
-
-// Show help
-if (argv.includes('--help') || argv.includes('-h')) {
-  console.log(`
-📦 BrowserStack Test Case Sync
-
-Onboard your Playwright/Cypress tests to BrowserStack Test Management.
-
-USAGE:
-  npx am-browserstack-sync [options]
-
-OPTIONS:
-  --csv-only      Generate CSVs only, do not sync to BrowserStack
-  --all           Sync all spec files without prompting
-  --spec=<names>  Sync specific specs (comma-separated)
-  --no-ai         Disable AI step analysis (use regex)
-  --model=<name>  Ollama model (default: llama3.2)
-  --help, -h      Show this help
-
-EXAMPLES:
-  npx am-browserstack-sync --all
-  npx am-browserstack-sync --csv-only
-  npx am-browserstack-sync --spec=login.spec,checkout.spec
-
-TO SYNC TEST RUN RESULTS:
-  npx am-browserstack-sync-runs
-
-ENVIRONMENT VARIABLES:
-  BROWSERSTACK_USERNAME     Your BrowserStack username
-  BROWSERSTACK_ACCESS_KEY   Your BrowserStack access key
-  BROWSERSTACK_PROJECT_ID   Project ID (e.g., PR-1234)
-`);
-  process.exit(0);
-}
-
 const csvOnly = argv.includes('--csv-only');
 const all = argv.includes('--all');
 const noAI = argv.includes('--no-ai');

package/lib/ai-analyzer.js

@@ -14,7 +14,7 @@ const OLLAMA_HOST = process.env.OLLAMA_HOST || 'http://localhost:11434';
 /**
  * System prompt for the AI to understand what we want.
  */
-const SYSTEM_PROMPT = `You are a test automation expert. Your job is to analyze Playwright or Cypress test code and extract human-readable test steps.
+const SYSTEM_PROMPT = `You are a QA expert creating manual test steps from automated test code.
 
 CRITICAL RULES:
 1. Generate steps ONLY for what is explicitly in the test code provided

package/lib/browserstack.js

@@ -200,109 +200,3 @@ export async function syncToBrowserStack(specsMap, projectId, auth) {
   console.log(`  Updated: ${totalUpdated} test case(s)`);
   console.log(`  Skipped: ${totalSkipped} test case(s) (no changes)`);
 }
-
-// ============================================================================
-// TEST RUN API - For syncing test execution results
-// ============================================================================
-
-/**
- * Create a new Test Run in BrowserStack.
- */
-export async function createTestRun(projectId, runName, description, auth) {
-  const url = `${BS_BASE}/projects/${encodeURIComponent(projectId)}/test-runs`;
-  const body = {
-    test_run: {
-      name: runName,
-      description: description || `Automated test run: ${runName}`,
-    },
-  };
-  const res = await bsRequest('POST', url, auth, body);
-  return {
-    runId: res.test_run?.id || res.id,
-    identifier: res.test_run?.identifier || res.identifier,
-  };
-}
-
-/**
- * Add test cases to a Test Run.
- */
-export async function addTestCasesToRun(projectId, runId, testCaseIds, auth) {
-  const url = `${BS_BASE}/projects/${encodeURIComponent(projectId)}/test-runs/${runId}/test-cases`;
-  const body = {
-    test_case_identifiers: testCaseIds,
-  };
-  return bsRequest('POST', url, auth, body);
-}
-
-/**
- * Update test result in a Test Run.
- */
-export async function updateTestResult(projectId, runId, testCaseId, status, options = {}, auth) {
-  const url = `${BS_BASE}/projects/${encodeURIComponent(projectId)}/test-runs/${runId}/test-results`;
-  
-  const statusMap = {
-    passed: 'passed',
-    failed: 'failed',
-    skipped: 'skipped',
-    timedOut: 'failed',
-  };
-  
-  const body = {
-    test_result: {
-      test_case_identifier: testCaseId,
-      status: statusMap[status] || status,
-      comment: options.comment || '',
-    },
-  };
-  
-  if (options.duration) {
-    body.test_result.duration = Math.round(options.duration / 1000);
-  }
-  
-  return bsRequest('POST', url, auth, body);
-}
-
-/**
- * Complete a Test Run.
- */
-export async function completeTestRun(projectId, runId, auth) {
-  const url = `${BS_BASE}/projects/${encodeURIComponent(projectId)}/test-runs/${runId}`;
-  const body = {
-    test_run: {
-      state: 'done',
-    },
-  };
-  return bsRequest('PATCH', url, auth, body);
-}
-
-/**
- * Get all test cases in a project.
- */
-export async function getAllTestCases(projectId, auth) {
-  const all = [];
-  let page = 1;
-  let hasMore = true;
-  
-  while (hasMore) {
-    const url = `${BS_BASE}/projects/${encodeURIComponent(projectId)}/test-cases?p=${page}`;
-    const res = await bsRequest('GET', url, auth);
-    const list = res.test_cases || [];
-    all.push(...list);
-    const info = res.info || {};
-    hasMore = info.next != null;
-    page += 1;
-  }
-  
-  return all;
-}
-
-/**
- * Find test case by title.
- */
-export function findTestCaseByTitle(testCases, title) {
-  const normalizedTitle = (title || '').trim().toLowerCase();
-  return testCases.find((tc) => {
-    const tcTitle = (tc.name || tc.title || '').trim().toLowerCase();
-    return tcTitle === normalizedTitle;
-  });
-}

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@ash-mallick/browserstack-sync",
-  "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).",
+  "version": "1.5.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",
   "main": "lib/index.js",
   "bin": {
-    "am-browserstack-sync": "bin/cli.js",
-    "am-browserstack-sync-runs": "bin/sync-runs.js"
+    "am-browserstack-sync": "bin/cli.js"
   },
   "files": [
     "bin",
@@ -15,9 +14,10 @@
   ],
   "scripts": {
     "test": "playwright test",
+    "test:e2e": "playwright test",
     "sync": "node bin/cli.js",
+    "sync:csv": "node bin/cli.js",
     "sync:csv-only": "node bin/cli.js --csv-only",
-    "sync:runs": "node bin/sync-runs.js",
     "prepublishOnly": "node bin/cli.js --csv-only",
     "publish:public": "npm publish --access public"
   },
@@ -28,11 +28,9 @@
     "e2e",
     "test-management",
     "sync",
-    "ci-cd",
-    "gitlab",
-    "github-actions",
     "ai",
     "ollama",
+    "llama",
     "test-steps",
     "free",
     "local",
@@ -48,8 +46,10 @@
     "ollama": "^0.6.3"
   },
   "devDependencies": {
-    "@playwright/test": "^1.49.0"
+    "@playwright/test": "^1.49.0",
+    "playwright": "^1.49.0"
   },
+  "peerDependenciesMeta": {},
   "engines": {
     "node": ">=18"
   }

package/bin/sync-runs.js

@@ -1,254 +0,0 @@
-#!/usr/bin/env node
-/**
- * Simple CLI to sync test run results to BrowserStack.
- * Add this to your existing CI pipeline after tests run.
- * 
- * Usage:
- *   npx am-browserstack-sync-runs
- *   npx am-browserstack-sync-runs --report=custom-results.json
- *   npx am-browserstack-sync-runs --run-name="Nightly Build #123"
- * 
- * Environment Variables (required):
- *   BROWSERSTACK_USERNAME
- *   BROWSERSTACK_ACCESS_KEY
- *   BROWSERSTACK_PROJECT_ID
- * 
- * The command will:
- *   1. Auto-detect Playwright report files (results.json, test-results.json, etc.)
- *   2. Parse test results
- *   3. Create a Test Run in BrowserStack
- *   4. Sync pass/fail status for each test
- *   5. Show a link to view results
- */
-
-import 'dotenv/config';
-import fs from 'fs';
-import path from 'path';
-import { syncResultsFromReport } from '../lib/sync-results.js';
-
-const argv = process.argv.slice(2);
-
-// Show help
-if (argv.includes('--help') || argv.includes('-h')) {
-  console.log(`
-📊 BrowserStack Test Run Sync
-
-Sync your Playwright/Cypress test results to BrowserStack Test Management.
-Specify your report file location - supports JSON and XML formats.
-
-USAGE:
-  npx am-browserstack-sync-runs --report=<path> [options]
-
-OPTIONS:
-  --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, 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)
-
-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
-
-  # 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
-
-CI PIPELINE EXAMPLE:
-  # GitLab CI
-  script:
-    - 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);
-}
-
-// 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 configPaths = [
-    path.join(cwd, '.am-browserstack-sync.json'),
-    path.join(cwd, 'browserstack-sync.json'),
-  ];
-  
-  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 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;
-}
-
-// Auto-detect format from file
-function detectFormat(reportPath) {
-  if (reportPath.endsWith('.xml')) {
-    return 'junit';
-  }
-  return 'playwright-json';
-}
-
-// Parse arguments
-const reportArg = argv.find((a) => a.startsWith('--report='));
-const formatArg = argv.find((a) => a.startsWith('--format='));
-const runNameArg = argv.find((a) => a.startsWith('--run-name='));
-
-let reportPath = reportArg ? reportArg.slice('--report='.length).trim() : null;
-let format = formatArg ? formatArg.slice('--format='.length).trim() : null;
-const runName = runNameArg 
-  ? runNameArg.slice('--run-name='.length).trim() 
-  : process.env.BROWSERSTACK_RUN_NAME || `CI Run - ${new Date().toISOString().slice(0, 16).replace('T', ' ')}`;
-
-// Determine report path: CLI arg > env var > config file
-if (!reportPath) {
-  reportPath = getConfiguredReportPath();
-}
-
-// Check if report exists
-if (reportPath) {
-  const resolvedPath = checkReportExists(reportPath);
-  if (!resolvedPath) {
-    console.error(`
-❌ Report file not found: ${reportPath}
-
-Make sure your test run generates this report before syncing.
-`);
-    process.exit(1);
-  }
-  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
-if (!format) {
-  format = detectFormat(reportPath);
-}
-
-// Check required env vars
-const missing = [];
-if (!process.env.BROWSERSTACK_USERNAME && !process.env.BROWSERSTACK_API_TOKEN) {
-  missing.push('BROWSERSTACK_USERNAME');
-}
-if (!process.env.BROWSERSTACK_ACCESS_KEY && !process.env.BROWSERSTACK_API_TOKEN) {
-  missing.push('BROWSERSTACK_ACCESS_KEY');
-}
-if (!process.env.BROWSERSTACK_PROJECT_ID) {
-  missing.push('BROWSERSTACK_PROJECT_ID');
-}
-
-if (missing.length > 0) {
-  console.error(`
-❌ Missing required environment variables:
-   ${missing.join('\n   ')}
-
-Set these in your CI/CD settings or .env file.
-`);
-  process.exit(1);
-}
-
-// Run sync
-syncResultsFromReport({
-  reportPath,
-  format,
-  runName,
-}).catch((err) => {
-  console.error('\n❌ Error:', err.message);
-  process.exit(1);
-});

package/lib/sync-results.js

@@ -1,473 +0,0 @@
-/**
- * Sync test results from CI pipeline to BrowserStack Test Management.
- * 
- * This module reads test results from Playwright JSON report or JUnit XML
- * and syncs them to BrowserStack, creating a Test Run with pass/fail status.
- * 
- * Usage:
- *   npx am-browserstack-sync --sync-results --report=playwright-report.json
- *   npx am-browserstack-sync --sync-results --report=junit.xml --format=junit
- */
-
-import fs from 'fs';
-import path from 'path';
-import {
-  createTestRun,
-  addTestCasesToRun,
-  updateTestResult,
-  completeTestRun,
-  getAllTestCases,
-  findTestCaseByTitle,
-} from './browserstack.js';
-
-/**
- * Parse Playwright JSON report format.
- * @param {string} reportPath - Path to the JSON report file
- * @returns {Array<{title: string, status: string, duration: number, error?: string}>}
- */
-function parsePlaywrightJson(reportPath) {
-  const report = JSON.parse(fs.readFileSync(reportPath, 'utf-8'));
-  const results = [];
-  
-  // Playwright JSON report structure: { suites: [...], stats: {...} }
-  function extractTests(suites) {
-    for (const suite of suites || []) {
-      for (const spec of suite.specs || []) {
-        for (const test of spec.tests || []) {
-          // Get the result from the test results array
-          const result = test.results?.[0] || {};
-          results.push({
-            title: spec.title || test.title,
-            fullTitle: `${suite.title} > ${spec.title}`,
-            status: mapPlaywrightStatus(test.status || result.status),
-            duration: result.duration || 0,
-            error: result.error?.message || result.errors?.[0]?.message || '',
-            file: suite.file || spec.file,
-          });
-        }
-      }
-      
-      // Recursively process nested suites
-      if (suite.suites) {
-        extractTests(suite.suites);
-      }
-    }
-  }
-  
-  extractTests(report.suites);
-  return results;
-}
-
-/**
- * Parse JUnit XML report format.
- * @param {string} reportPath - Path to the JUnit XML file
- * @returns {Array<{title: string, status: string, duration: number, error?: string}>}
- */
-function parseJunitXml(reportPath) {
-  const xml = fs.readFileSync(reportPath, 'utf-8');
-  const results = [];
-  
-  // Simple regex-based XML parsing for JUnit format
-  // <testcase name="..." classname="..." time="...">
-  //   <failure message="...">...</failure>
-  //   <skipped/>
-  // </testcase>
-  
-  const testcaseRegex = /<testcase\s+[^>]*name="([^"]+)"[^>]*time="([^"]+)"[^>]*>([\s\S]*?)<\/testcase>/gi;
-  const failureRegex = /<failure[^>]*message="([^"]*)"[^>]*>/i;
-  const skippedRegex = /<skipped\s*\/?>/i;
-  const errorRegex = /<error[^>]*message="([^"]*)"[^>]*>/i;
-  
-  let match;
-  while ((match = testcaseRegex.exec(xml)) !== null) {
-    const [, name, time, content] = match;
-    
-    let status = 'passed';
-    let error = '';
-    
-    if (skippedRegex.test(content)) {
-      status = 'skipped';
-    } else if (failureRegex.test(content)) {
-      status = 'failed';
-      const failMatch = content.match(failureRegex);
-      error = failMatch?.[1] || 'Test failed';
-    } else if (errorRegex.test(content)) {
-      status = 'failed';
-      const errMatch = content.match(errorRegex);
-      error = errMatch?.[1] || 'Test error';
-    }
-    
-    results.push({
-      title: name,
-      status,
-      duration: Math.round(parseFloat(time) * 1000), // Convert seconds to ms
-      error,
-    });
-  }
-  
-  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
- */
-function parsePlaywrightHtmlReport(reportDir) {
-  // Try to find the JSON data in the HTML report directory
-  const possiblePaths = [
-    path.join(reportDir, 'report.json'),
-    path.join(reportDir, 'data', 'report.json'),
-    path.join(reportDir, 'results.json'),
-  ];
-  
-  for (const p of possiblePaths) {
-    if (fs.existsSync(p)) {
-      return parsePlaywrightJson(p);
-    }
-  }
-  
-  throw new Error(`Could not find JSON data in Playwright HTML report directory: ${reportDir}`);
-}
-
-/**
- * Map Playwright status to BrowserStack status.
- */
-function mapPlaywrightStatus(status) {
-  const map = {
-    passed: 'passed',
-    failed: 'failed',
-    timedOut: 'failed',
-    skipped: 'skipped',
-    interrupted: 'blocked',
-    expected: 'passed',
-    unexpected: 'failed',
-    flaky: 'retest',
-  };
-  return map[status] || status;
-}
-
-/**
- * Load authentication from environment.
- */
-function loadAuth() {
-  const username = process.env.BROWSERSTACK_USERNAME;
-  const accessKey = process.env.BROWSERSTACK_ACCESS_KEY;
-  const apiToken = process.env.BROWSERSTACK_API_TOKEN;
-  
-  if (apiToken) {
-    return { apiToken };
-  }
-  
-  if (username && accessKey) {
-    return { username, accessKey };
-  }
-  
-  return null;
-}
-
-/**
- * Sync test results from a report file to BrowserStack.
- * 
- * @param {Object} options
- * @param {string} options.reportPath - Path to the report file or directory
- * @param {string} options.format - Report format: 'playwright-json', 'junit', 'playwright-html'
- * @param {string} options.projectId - BrowserStack project ID
- * @param {string} options.runName - Name for the test run
- * @param {string} options.runDescription - Description for the test run
- */
-export async function syncResultsFromReport(options = {}) {
-  const {
-    reportPath,
-    format = 'playwright-json',
-    projectId = process.env.BROWSERSTACK_PROJECT_ID,
-    runName = process.env.BROWSERSTACK_RUN_NAME || `CI Run - ${new Date().toISOString().slice(0, 16).replace('T', ' ')}`,
-    runDescription = process.env.BROWSERSTACK_RUN_DESCRIPTION || 'Test results synced from CI pipeline',
-  } = options;
-  
-  // Validate inputs
-  if (!reportPath) {
-    throw new Error('Report path is required. Use --report=<path>');
-  }
-  
-  if (!projectId) {
-    throw new Error('BROWSERSTACK_PROJECT_ID is required');
-  }
-  
-  const auth = loadAuth();
-  if (!auth) {
-    throw new Error('BrowserStack credentials not found. Set BROWSERSTACK_USERNAME/ACCESS_KEY or API_TOKEN');
-  }
-  
-  // Check if report exists
-  if (!fs.existsSync(reportPath)) {
-    throw new Error(`Report file not found: ${reportPath}`);
-  }
-  
-  console.log('\n📊 BrowserStack Results Sync');
-  console.log('   Report:', reportPath);
-  console.log('   Format:', format);
-  console.log('   Project:', projectId);
-  console.log('   Run Name:', runName);
-  
-  // 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 {
-    // 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) {
-    console.log('\n   ⚠️ No test results found in report');
-    return;
-  }
-  
-  // Fetch all test cases from BrowserStack
-  console.log('\n   Fetching test cases from BrowserStack...');
-  const allBsTestCases = await getAllTestCases(projectId, auth);
-  console.log(`   Found ${allBsTestCases.length} test case(s) in project`);
-  
-  // Map results to BrowserStack test cases
-  const mappedResults = [];
-  const unmappedResults = [];
-  
-  for (const result of testResults) {
-    const bsTestCase = findTestCaseByTitle(allBsTestCases, result.title);
-    if (bsTestCase) {
-      mappedResults.push({ ...result, bsTestCase });
-    } else {
-      unmappedResults.push(result);
-    }
-  }
-  
-  console.log(`   Mapped: ${mappedResults.length} test(s)`);
-  if (unmappedResults.length > 0) {
-    console.log(`   Unmapped: ${unmappedResults.length} test(s) (not found in BrowserStack)`);
-  }
-  
-  if (mappedResults.length === 0) {
-    console.log('\n   ⚠️ No tests matched. Make sure tests are synced first:');
-    console.log('      npx am-browserstack-sync --all');
-    return;
-  }
-  
-  // Create test run
-  console.log(`\n   Creating test run: "${runName}"...`);
-  const run = await createTestRun(projectId, runName, runDescription, auth);
-  const runId = run.runId;
-  const runIdentifier = run.identifier;
-  console.log(`   ✓ Test run created: ${runIdentifier}`);
-  
-  // Add test cases to run
-  const testCaseIds = mappedResults.map(r => r.bsTestCase.identifier);
-  console.log(`   Adding ${testCaseIds.length} test case(s) to run...`);
-  await addTestCasesToRun(projectId, runId, testCaseIds, auth);
-  
-  // Update results
-  console.log('\n   Syncing results:');
-  const stats = { passed: 0, failed: 0, skipped: 0 };
-  
-  for (const result of mappedResults) {
-    try {
-      await updateTestResult(
-        projectId,
-        runId,
-        result.bsTestCase.identifier,
-        result.status,
-        {
-          duration: result.duration,
-          comment: result.error || '',
-        },
-        auth
-      );
-      
-      const icon = result.status === 'passed' ? '✓' : result.status === 'failed' ? '✗' : '○';
-      console.log(`   ${icon} ${result.title} → ${result.status}`);
-      
-      if (result.status === 'passed') stats.passed++;
-      else if (result.status === 'failed') stats.failed++;
-      else stats.skipped++;
-    } catch (error) {
-      console.error(`   ✗ Failed to update ${result.title}: ${error.message}`);
-    }
-  }
-  
-  // Complete the run
-  console.log('\n   Completing test run...');
-  await completeTestRun(projectId, runId, auth);
-  
-  const total = stats.passed + stats.failed + stats.skipped;
-  console.log(`\n   ✓ Test run completed: ${runIdentifier}`);
-  console.log(`   📊 Results: ${stats.passed} passed, ${stats.failed} failed, ${stats.skipped} skipped (${total} total)`);
-  console.log(`   🔗 View: https://test-management.browserstack.com/projects/${projectId}/runs/${runId}`);
-  
-  // Show unmapped tests
-  if (unmappedResults.length > 0) {
-    console.log('\n   ⚠️ Tests not found in BrowserStack (sync them first):');
-    unmappedResults.slice(0, 5).forEach(r => console.log(`      - ${r.title}`));
-    if (unmappedResults.length > 5) {
-      console.log(`      ... and ${unmappedResults.length - 5} more`);
-    }
-  }
-  
-  return {
-    runId,
-    runIdentifier,
-    stats,
-    mappedCount: mappedResults.length,
-    unmappedCount: unmappedResults.length,
-  };
-}
-
-export { parsePlaywrightJson, parseJunitXml };