@ash-mallick/browserstack-sync 1.1.4 → 1.3.1

package/README.md

@@ -1,8 +1,6 @@
 # @ash-mallick/browserstack-sync
 
-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!
+Sync Playwright/Cypress tests to BrowserStack Test Management with AI-powered test step extraction.
 
 **By Ashutosh Mallick**
 
@@ -14,96 +12,140 @@ Sync **Playwright** and **Cypress** e2e specs to CSV (TC-001, TC-002, …) and o
 npm install @ash-mallick/browserstack-sync
 ```
 
-Or run without installing: `npx @ash-mallick/browserstack-sync --csv-only`
+---
+
+## Quick Setup
+
+Create `.env` file:
+
+```env
+BROWSERSTACK_USERNAME=your_username
+BROWSERSTACK_ACCESS_KEY=your_access_key
+BROWSERSTACK_PROJECT_ID=PR-XXXX
+```
 
 ---
 
-## Run
+## Commands
 
-From your project root (where your e2e specs live):
+### 1. Generate CSV Files Only (No BrowserStack)
 
 ```bash
-# Generate CSVs only
 npx am-browserstack-sync --csv-only
+```
 
-# Sync all specs, no prompt (e.g. CI)
-npx am-browserstack-sync --all
+Creates CSV files with test cases in `playwright/e2e-csv/` folder.
 
-# Sync only certain specs
-npx am-browserstack-sync --spec=login.spec,checkout.spec
+---
 
-# Disable AI analysis (use regex extraction only)
-npx am-browserstack-sync --no-ai
+### 2. Onboard Single Spec to BrowserStack
 
-# Use a specific Ollama model
-npx am-browserstack-sync --model=llama3.2
+```bash
+npx am-browserstack-sync --spec=login.spec
 ```
 
-**Scripts** in `package.json`:
+Creates folder and test cases for the specified spec file.
 
-```json
-{
-  "scripts": {
-    "sync:e2e": "am-browserstack-sync",
-    "sync:e2e-csv": "am-browserstack-sync --csv-only"
-  }
-}
+---
+
+### 3. Onboard All Specs to BrowserStack
+
+```bash
+npx am-browserstack-sync --all
 ```
 
+Creates folders and test cases for all spec files in your project.
+
 ---
 
-## 🦙 AI-Powered Step Analysis (FREE with Ollama)
+### 4. Sync Test Run Results to BrowserStack
+
+First, run your tests with JSON reporter:
 
-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!
+```bash
+npx playwright test --reporter=list,json --output-file=test-results.json
+```
 
-**Example transformation:**
+Then sync results:
 
-```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/);
-});
+```bash
+npx am-browserstack-sync-runs
 ```
 
-**Generated steps:**
+Or with custom run name:
 
-| 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 |
+```bash
+npx am-browserstack-sync-runs --run-name="Nightly Run"
+```
 
-### Setup Ollama
+---
+
+## GitLab CI Scheduled Job
+
+Add to `.gitlab-ci.yml`:
+
+```yaml
+scheduled_browserstack_sync:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule"
+  script:
+    - npm ci
+    - npx playwright test --reporter=list,json --output-file=test-results.json || true
+    - npm install @ash-mallick/browserstack-sync
+    - npx am-browserstack-sync-runs
+```
 
-1. Download and install Ollama from [ollama.ai](https://ollama.ai)
+Add CI/CD Variables in GitLab (**Settings → CI/CD → Variables**):
 
-2. Pull a model (llama3.2 recommended):
+| Key | Value |
+|-----|-------|
+| `BROWSERSTACK_USERNAME` | your_username |
+| `BROWSERSTACK_ACCESS_KEY` | your_access_key |
+| `BROWSERSTACK_PROJECT_ID` | PR-XXXX |
+
+Create schedule in **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)
+
+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.
+
+### Setup Ollama
+
+1. Download from [ollama.ai](https://ollama.ai)
+2. Pull a model:
    ```bash
    ollama pull llama3.2
    ```
-
-3. Start Ollama (runs automatically on macOS, or run manually):
+3. Start Ollama:
    ```bash
    ollama serve
    ```
 
-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
+AI analysis runs automatically when Ollama is running. Use `--no-ai` to disable.
 
 ### Recommended Models
 
@@ -112,17 +154,16 @@ test('should log in successfully', async ({ page }) => {
 | `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.
 
 ---
 
-## Config (optional)
+## Configuration (Optional)
 
-Defaults: e2e dir `playwright/e2e`, CSV dir `playwright/e2e-csv`. For Cypress use e.g. `cypress/e2e`.
+Default directories:
+- e2e specs: `playwright/e2e`
+- CSV output: `playwright/e2e-csv`
 
-Override via **`.am-browserstack-sync.json`** in project root:
+Override via `.am-browserstack-sync.json`:
 
 ```json
 {
@@ -131,42 +172,27 @@ Override via **`.am-browserstack-sync.json`** in project root:
 }
 ```
 
-Or **package.json**: `"amBrowserstackSync": { "e2eDir": "...", "csvOutputDir": "..." }`  
-Or env: `PLAYWRIGHT_BROWSERSTACK_E2E_DIR`, `PLAYWRIGHT_BROWSERSTACK_CSV_DIR`.
+Or via environment variables:
+- `PLAYWRIGHT_BROWSERSTACK_E2E_DIR`
+- `PLAYWRIGHT_BROWSERSTACK_CSV_DIR`
 
 ---
 
-## 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.
+## What Gets Created
 
-**Setup:**
+When you run `npx am-browserstack-sync --all`:
 
-1. In project root, create **`.env`** (do not commit):
-
-   ```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`
+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
 
-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.
----
+When you run `npx am-browserstack-sync-runs`:
 
-**Author:** Ashutosh Mallick
+1. **Test Run** - Created in BrowserStack
+2. **Results** - Pass/fail status for each test
+3. **Link** - URL to view results in BrowserStack

package/bin/cli.js

@@ -2,31 +2,67 @@
 /**
  * CLI for @ash-mallick/browserstack-sync (am-browserstack-sync).
  * By Ashutosh Mallick. Run from your project root: npx am-browserstack-sync [options]
- * Uses cwd as project root; config from .env, config file, or package.json.
+ * 
+ * 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
  *
- * 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). 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
+ *   --spec=name     Sync only these specs (comma-separated)
+ *   --no-ai         Disable AI-powered step analysis
+ *   --model=name    Ollama model to use (default: llama3.2)
  *
- * AI Analysis (FREE, Local with Ollama):
- *   Install Ollama from https://ollama.ai, then:
- *     ollama pull llama3.2
- *     ollama serve
+ * 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 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"
+ * To sync test run results, use:
+ *   npx am-browserstack-sync-runs
  */
 
 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/bin/sync-runs.js

@@ -0,0 +1,189 @@
+#!/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.
+Add this command to your existing CI pipeline after tests complete.
+
+USAGE:
+  npx am-browserstack-sync-runs [options]
+
+OPTIONS:
+  --report=<path>     Path to report file (auto-detects if not specified)
+  --run-name=<name>   Name for the test run (default: "CI Run - <timestamp>")
+  --format=<fmt>      Report format: playwright-json, junit (default: auto)
+  --help, -h          Show this help
+
+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
+
+  # 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}"
+
+  # Sync JUnit XML results
+  npx am-browserstack-sync-runs --report=junit.xml --format=junit
+
+ADD TO YOUR CI PIPELINE:
+  # 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
+`);
+  process.exit(0);
+}
+
+// Auto-detect report file
+function findReportFile() {
+  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',
+  ];
+  
+  for (const file of possibleFiles) {
+    const fullPath = path.join(cwd, file);
+    if (fs.existsSync(fullPath)) {
+      return fullPath;
+    }
+  }
+  
+  // Check for playwright-report directory
+  const htmlReportDir = path.join(cwd, 'playwright-report');
+  if (fs.existsSync(htmlReportDir) && fs.statSync(htmlReportDir).isDirectory()) {
+    return htmlReportDir;
+  }
+  
+  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', ' ')}`;
+
+// Auto-detect report if not specified
+if (!reportPath) {
+  reportPath = findReportFile();
+  if (!reportPath) {
+    console.error(`
+❌ No test report found!
+
+Make sure your test framework generates a report file:
+
+  # Playwright - add to your test command:
+  npx playwright test --reporter=json --output-file=test-results.json
+
+  # Or specify the report path:
+  npx am-browserstack-sync-runs --report=path/to/results.json
+`);
+    process.exit(1);
+  }
+  console.log(`📄 Auto-detected report: ${reportPath}`);
+}
+
+// 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/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 QA expert creating manual test steps from automated test code.
+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.
 
 CRITICAL RULES:
 1. Generate steps ONLY for what is explicitly in the test code provided

package/lib/browserstack.js

@@ -200,3 +200,109 @@ 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/lib/sync-results.js

@@ -0,0 +1,329 @@
+/**
+ * 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 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;
+  
+  const stat = fs.statSync(reportPath);
+  if (stat.isDirectory()) {
+    // Assume it's a Playwright HTML report directory
+    testResults = parsePlaywrightHtmlReport(reportPath);
+  } else if (format === 'junit' || reportPath.endsWith('.xml')) {
+    testResults = parseJunitXml(reportPath);
+  } else {
+    testResults = parsePlaywrightJson(reportPath);
+  }
+  
+  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 };

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@ash-mallick/browserstack-sync",
-  "version": "1.1.4",
-  "description": "Sync Playwright & Cypress e2e specs to CSV and BrowserStack Test Management with FREE AI-powered test step extraction using Ollama (local)",
+  "version": "1.3.1",
+  "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": "bin/cli.js",
+    "am-browserstack-sync-runs": "bin/sync-runs.js"
   },
   "files": [
     "bin",
@@ -14,10 +15,9 @@
   ],
   "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,9 +28,11 @@
     "e2e",
     "test-management",
     "sync",
+    "ci-cd",
+    "gitlab",
+    "github-actions",
     "ai",
     "ollama",
-    "llama",
     "test-steps",
     "free",
     "local",
@@ -42,15 +44,12 @@
     "url": ""
   },
   "dependencies": {
-    "@ash-mallick/browserstack-sync": "^1.1.3",
     "dotenv": "^16.4.5",
     "ollama": "^0.6.3"
   },
   "devDependencies": {
-    "@playwright/test": "^1.49.0",
-    "playwright": "^1.49.0"
+    "@playwright/test": "^1.49.0"
   },
-  "peerDependenciesMeta": {},
   "engines": {
     "node": ">=18"
   }