npm - @ash-mallick/browserstack-sync - Versions diffs - 1.3.0 → 1.4.0 - Mend

@ash-mallick/browserstack-sync 1.3.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -1,188 +1,194 @@
 # @ash-mallick/browserstack-sync
-Sync **Playwright** and **Cypress** e2e specs to **BrowserStack Test Management** with **AI-powered test step extraction**.
-**🦙 FREE AI analysis** 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**
 ---
-## 🚀 Quick Start (3 Steps)
+## Install
-### Step 1: Install
 ```bash
 npm install @ash-mallick/browserstack-sync
 ```
-### Step 2: Setup Environment
-Create `.env` file in your project root:
+---
+## Quick Setup
+Create `.env` file:
 ```env
 BROWSERSTACK_USERNAME=your_username
 BROWSERSTACK_ACCESS_KEY=your_access_key
 BROWSERSTACK_PROJECT_ID=PR-XXXX
 ```
-### Step 3: Onboard Tests to BrowserStack
+---
+## Commands
+### 1. Generate CSV Files Only (No BrowserStack)
 ```bash
-npx am-browserstack-sync --all
+npx am-browserstack-sync --csv-only
 ```
-This will:
-- ✅ Generate CSV files with test cases
-- ✅ Create folders in BrowserStack (one per spec file)
-- ✅ Create/update test cases with AI-generated steps
+Creates CSV files with test cases in `playwright/e2e-csv/` folder.
 ---
-## 📊 Sync Test Run Results (CI Pipeline)
-Add this single line to your existing CI pipeline to sync test results:
+### 2. Onboard Single Spec to BrowserStack
 ```bash
-npx am-browserstack-sync-runs
+npx am-browserstack-sync --spec=login.spec
 ```
-### GitLab CI Example
+Creates folder and test cases for the specified spec file.
-```yaml
-test:
-  script:
-    # Your existing test command (add JSON reporter)
-    - npx playwright test --reporter=json --output-file=test-results.json
-    # Sync results to BrowserStack (add this line)
-    - npx am-browserstack-sync-runs --run-name="Pipeline #$CI_PIPELINE_ID"
-```
+---
-### GitHub Actions Example
+### 3. Onboard All Specs to BrowserStack
-```yaml
-- run: npx playwright test --reporter=json --output-file=test-results.json
-- run: npx am-browserstack-sync-runs --run-name="Build #${{ github.run_number }}"
+```bash
+npx am-browserstack-sync --all
 ```
-The command will:
-- 📄 Auto-detect your test report file
-- 📊 Parse test results (pass/fail/skip)
-- 🔗 Create a Test Run in BrowserStack
-- ✅ Sync each test result
-- 🔗 Provide a link to view results
+Creates folders and test cases for all spec files in your project.
 ---
-## Commands Overview
+### 4. Sync Test Run Results to BrowserStack
-| Command | Purpose |
-|---------|---------|
-| `npx am-browserstack-sync --all` | Onboard tests to BrowserStack (one-time setup) |
-| `npx am-browserstack-sync-runs` | Sync test run results (add to CI pipeline) |
-| `npx am-browserstack-sync --csv-only` | Generate CSVs only (no BrowserStack sync) |
+Specify your report file location:
----
+```bash
+npx am-browserstack-sync-runs --report=test-results.json
+```
-## Detailed Usage
+**Supported formats (auto-detected):**
+- Playwright JSON
+- Cypress/Mochawesome JSON
+- JUnit XML
-### Onboard Tests (am-browserstack-sync)
+**Configure report path** (so you don't need `--report` every time):
 ```bash
-# Onboard all spec files
-npx am-browserstack-sync --all
+# Via environment variable
+export BROWSERSTACK_REPORT_PATH=test-results.json
-# Onboard specific specs
-npx am-browserstack-sync --spec=login.spec,checkout.spec
+# Or in .am-browserstack-sync.json
+{ "reportPath": "test-results.json" }
+```
-# Generate CSVs only (no BrowserStack)
-npx am-browserstack-sync --csv-only
+**Generate reports** (add to your test command):
-# Disable AI (use regex extraction)
-npx am-browserstack-sync --no-ai
+```bash
+# Playwright
+npx playwright test --reporter=json --output-file=test-results.json
-# Use specific Ollama model
-npx am-browserstack-sync --model=llama3.2
+# Cypress
+npx cypress run --reporter mochawesome
 ```
-### Sync Run Results (am-browserstack-sync-runs)
+**With custom run name:**
 ```bash
-# Auto-detect report and sync
-npx am-browserstack-sync-runs
+npx am-browserstack-sync-runs --report=test-results.json --run-name="Nightly Run"
+```
-# Specify report file
-npx am-browserstack-sync-runs --report=test-results.json
+---
+## GitLab CI Integration
-# Custom run name
-npx am-browserstack-sync-runs --run-name="Nightly Regression"
+### 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
-# JUnit XML format
-npx am-browserstack-sync-runs --report=junit.xml --format=junit
+# 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"
 ```
-### Scripts in package.json
+### Option B: Scheduled sync job (runs tests + syncs)
-```json
-{
-  "scripts": {
-    "test": "playwright test --reporter=json --output-file=test-results.json",
-    "sync:onboard": "am-browserstack-sync --all",
-    "sync:runs": "am-browserstack-sync-runs"
-  }
-}
+```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**.
 ---
-## 🦙 AI-Powered Step Analysis (FREE with Ollama)
+## All Options Reference
-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!
+### Onboarding Command (`am-browserstack-sync`)
-**Example transformation:**
+| 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) |
-```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/);
-});
-```
+### Run Sync Command (`am-browserstack-sync-runs`)
-**Generated steps:**
+| 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` |
-| 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
+## AI-Powered Test Steps (Optional)
-1. Download and install Ollama from [ollama.ai](https://ollama.ai)
+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.
-2. Pull a model (llama3.2 recommended):
+### 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
@@ -191,17 +197,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
 {
@@ -210,222 +215,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`.
----
-## 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.
-**Setup:**
-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`
-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.
----
-## 📊 Test Run Tracking (NEW!)
-Run your Playwright tests and **automatically track results on BrowserStack**. Each test run is recorded with pass/fail status, duration, and links back to your test cases.
-### Quick Start
-```bash
-# Run all tests with BrowserStack tracking
-npx am-browserstack-sync --run
-# Run with a custom run name
-npx am-browserstack-sync --run --run-name="Nightly Regression"
-# Run specific spec files
-npx am-browserstack-sync --run --spec=login.spec.js,checkout.spec.js
-# Run tests matching a pattern
-npx am-browserstack-sync --run --grep="login"
-```
-### Setup
-1. First, **sync your test cases** to BrowserStack (one-time or when tests change):
-   ```bash
-   npx am-browserstack-sync --all
-   ```
-2. Ensure your `.env` has the required credentials:
-   ```env
-   BROWSERSTACK_USERNAME=your_username
-   BROWSERSTACK_ACCESS_KEY=your_access_key
-   BROWSERSTACK_PROJECT_ID=PR-XXXX
-   ```
-3. Run tests with tracking:
-   ```bash
-   npx am-browserstack-sync --run
-   ```
-### What happens during a test run
-1. **Creates a Test Run** in BrowserStack with your specified name
-2. **Maps tests** to existing test cases by title
-3. **Updates results in real-time** as each test passes/fails/skips
-4. **Completes the run** with a summary and link to view results
-### Example Output
-```
-🚀 Running Playwright tests with BrowserStack tracking...
-   Run Name: Nightly Regression
-🔗 BrowserStack Test Management - Initializing...
-   Fetching test cases from BrowserStack...
-   Found 15 test case(s) in project PR-1234
-   Creating test run: "Nightly Regression"...
-   ✓ Test run created: TR-42 (ID: 12345)
-   Adding 15 test case(s) to the run...
-   ✓ Test cases added to run
-   🚀 Starting test execution with BrowserStack tracking
-   ✓ [BS] should display login form → passed
-   ✓ [BS] should log in successfully → passed
-   ✗ [BS] should show error for invalid credentials → failed
-🔗 BrowserStack Test Management - Completing run...
-   ✓ Test run completed: TR-42
-   📊 Results: 2 passed, 1 failed, 0 skipped (3 total)
-   🔗 View in BrowserStack: https://test-management.browserstack.com/projects/PR-1234/runs/12345
-```
-### Using as a Playwright Reporter
-You can also use the BrowserStack reporter directly in your `playwright.config.js`:
-```javascript
-// playwright.config.js
-export default {
-  reporter: [
-    ['list'],
-    ['@ash-mallick/browserstack-sync/reporter', {
-      projectId: 'PR-1234',
-      runName: 'CI Pipeline Run',
-    }],
-  ],
-};
-```
-### CI/CD Integration - GitLab
-**Sync test results from GitLab CI pipelines to BrowserStack!**
-#### Quick Setup
-1. Add CI/CD variables in GitLab (Settings > CI/CD > Variables):
-   - `BROWSERSTACK_USERNAME`
-   - `BROWSERSTACK_ACCESS_KEY`
-   - `BROWSERSTACK_PROJECT_ID`
-2. Run tests with JSON reporter and sync results:
-```yaml
-# .gitlab-ci.yml
-test_and_sync:
-  image: mcr.microsoft.com/playwright:v1.40.0-jammy
-  script:
-    - npm ci
-    - npm install @ash-mallick/browserstack-sync
-    # Run tests with JSON reporter
-    - npx playwright test --reporter=json --output-file=test-results.json || true
-    # Sync results to BrowserStack
-    - npx am-browserstack-sync-runs --run-name="CI Pipeline #$CI_PIPELINE_ID"
-  artifacts:
-    paths:
-      - test-results.json
-```
-#### Scheduled Runs (Nightly/Weekly)
-```yaml
-nightly_tests:
-  rules:
-    - if: $CI_PIPELINE_SOURCE == "schedule"
-  variables:
-    BROWSERSTACK_RUN_NAME: "Nightly Regression - $CI_COMMIT_SHORT_SHA"
-  script:
-    - npx playwright test --reporter=json --output-file=test-results.json || true
-    - npx am-browserstack-sync-runs
-```
-#### CLI Options
-```bash
-# Auto-detect report and sync
-npx am-browserstack-sync-runs
-# Specify report file
-npx am-browserstack-sync-runs --report=custom-results.json
-# Custom run name
-npx am-browserstack-sync-runs --run-name="Nightly Build"
-# JUnit XML format
-npx am-browserstack-sync-runs --report=junit.xml --format=junit
-```
-### GitHub Actions Example
-```yaml
-- name: Run tests and sync to BrowserStack
-  env:
-    BROWSERSTACK_USERNAME: ${{ secrets.BROWSERSTACK_USERNAME }}
-    BROWSERSTACK_ACCESS_KEY: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
-    BROWSERSTACK_PROJECT_ID: PR-1234
-  run: |
-    npx playwright test --reporter=json --output-file=test-results.json || true
-    npx am-browserstack-sync-runs --run-name="Build #${{ github.run_number }}"
-```
+Or via environment variables:
+- `PLAYWRIGHT_BROWSERSTACK_E2E_DIR`
+- `PLAYWRIGHT_BROWSERSTACK_CSV_DIR`
 ---
-## Programmatic API
+## What Gets Created
-```javascript
-import { runSync } from '@ash-mallick/browserstack-sync';
+When you run `npx am-browserstack-sync --all`:
-await runSync({
-  cwd: '/path/to/project',
-  csvOnly: true,
-  all: true,
-  spec: ['login.spec'],
-  useAI: true,
-  model: 'llama3.2',
-});
-```
+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
----
+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/sync-runs.js CHANGED Viewed

@@ -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/browserstack.js CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@ash-mallick/browserstack-sync",
-  "version": "1.3.0",
+  "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",