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

@ash-mallick/browserstack-sync 1.3.0 → 1.3.1

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 (3) hide show

package/README.md CHANGED Viewed

@@ -1,188 +1,151 @@
 # @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
-```bash
-npx am-browserstack-sync --all
-```
-This will:
-- ✅ Generate CSV files with test cases
-- ✅ Create folders in BrowserStack (one per spec file)
-- ✅ Create/update test cases with AI-generated steps
 ---
-## 📊 Sync Test Run Results (CI Pipeline)
+## Commands
-Add this single line to your existing CI pipeline to sync test results:
+### 1. Generate CSV Files Only (No BrowserStack)
 ```bash
-npx am-browserstack-sync-runs
+npx am-browserstack-sync --csv-only
 ```
-### GitLab CI Example
+Creates CSV files with test cases in `playwright/e2e-csv/` folder.
-```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
+### 2. Onboard Single Spec 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 --spec=login.spec
 ```
-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 folder and test cases for the specified spec file.
 ---
-## Commands Overview
+### 3. Onboard All Specs to BrowserStack
+```bash
+npx am-browserstack-sync --all
+```
-| 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) |
+Creates folders and test cases for all spec files in your project.
 ---
-## Detailed Usage
+### 4. Sync Test Run Results to BrowserStack
-### Onboard Tests (am-browserstack-sync)
+First, run your tests with JSON reporter:
 ```bash
-# Onboard all spec files
-npx am-browserstack-sync --all
-# Onboard specific specs
-npx am-browserstack-sync --spec=login.spec,checkout.spec
-# Generate CSVs only (no BrowserStack)
-npx am-browserstack-sync --csv-only
+npx playwright test --reporter=list,json --output-file=test-results.json
+```
-# Disable AI (use regex extraction)
-npx am-browserstack-sync --no-ai
+Then sync results:
-# Use specific Ollama model
-npx am-browserstack-sync --model=llama3.2
+```bash
+npx am-browserstack-sync-runs
 ```
-### Sync Run Results (am-browserstack-sync-runs)
+Or with custom run name:
 ```bash
-# Auto-detect report and sync
-npx am-browserstack-sync-runs
+npx am-browserstack-sync-runs --run-name="Nightly Run"
+```
+---
-# Specify report file
-npx am-browserstack-sync-runs --report=test-results.json
+## GitLab CI Scheduled Job
-# Custom run name
-npx am-browserstack-sync-runs --run-name="Nightly Regression"
+Add to `.gitlab-ci.yml`:
-# JUnit XML format
-npx am-browserstack-sync-runs --report=junit.xml --format=junit
+```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
 ```
-### Scripts in package.json
+Add CI/CD Variables in GitLab (**Settings → CI/CD → Variables**):
-```json
-{
-  "scripts": {
-    "test": "playwright test --reporter=json --output-file=test-results.json",
-    "sync:onboard": "am-browserstack-sync --all",
-    "sync:runs": "am-browserstack-sync-runs"
-  }
-}
-```
+| 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**.
 ---
-## 🦙 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.
+### Setup Ollama
-2. Pull a model (llama3.2 recommended):
+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 +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
 {
@@ -210,222 +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`.
----
-## 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/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/package.json CHANGED Viewed

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