@ash-mallick/browserstack-sync 1.0.0

package/README.md

@@ -0,0 +1,211 @@
+# @ash-mallick/browserstack-sync
+
+**By Ashutosh Mallick** — Sync **Playwright** and **Cypress** e2e spec files to **CSV** (one per spec, with test case IDs TC-001, TC-002, …) and optionally to **BrowserStack Test Management** (one folder per spec, test cases imported).
+
+Use it in any project that has Playwright or Cypress e2e tests. Configure paths per project and run via **`am-browserstack-sync`** with `npx` or as a dependency.
+
+---
+
+## Use in your project
+
+### 1. Install
+
+```bash
+npm install @ash-mallick/browserstack-sync
+# or run without installing
+npx @ash-mallick/browserstack-sync --csv-only
+```
+
+### 2. Run
+
+From your **project root** (where your `playwright/e2e` or Cypress specs live):
+
+```bash
+# CSV only (no BrowserStack API calls)
+npx am-browserstack-sync --csv-only
+
+# Sync to BrowserStack – interactive: choose all specs or pick specific ones
+npx am-browserstack-sync
+
+# Sync all specs (no prompt, e.g. for CI)
+npx am-browserstack-sync --all
+
+# Sync only specific spec(s)
+npx am-browserstack-sync --spec=login.spec
+npx am-browserstack-sync --spec=login.spec,checkout.spec
+```
+
+If you installed the package, the command is `am-browserstack-sync`. With `npx` you can use either:
+
+- `npx am-browserstack-sync` (uses the bin name)
+- `npx @ash-mallick/browserstack-sync` (runs the package)
+
+Add scripts in your project’s `package.json`:
+
+```json
+{
+  "scripts": {
+    "sync:e2e": "am-browserstack-sync",
+    "sync:e2e-csv": "am-browserstack-sync --csv-only"
+  }
+}
+```
+
+Then: `npm run sync:e2e-csv` or `npm run sync:e2e`.
+
+### 3. Configure (optional)
+
+Defaults:
+
+- **E2E directory:** `playwright/e2e`
+- **CSV output:** `playwright/e2e-csv`
+
+For **Cypress**, set `e2eDir` to your specs folder (e.g. `cypress/e2e`, `cypress/integration`, or `cypress/specs`).
+
+Override in one of these ways (first wins):
+
+**A) Config file** in project root  
+
+Create `.am-browserstack-sync.json` or `am-browserstack-sync.config.json`:
+
+```json
+{
+  "e2eDir": "playwright/e2e",
+  "csvOutputDir": "playwright/e2e-csv"
+}
+```
+
+(Legacy names `.am-e2e-sync.json`, `playwright-browserstack-sync.config.json`, etc. are still supported.)
+
+**B) package.json**
+
+```json
+{
+  "amBrowserstackSync": {
+    "e2eDir": "tests/e2e",
+    "csvOutputDir": "tests/e2e-csv"
+  }
+}
+```
+
+(Legacy fields `amE2eSync`, `playwrightBrowserstackSync` are also supported.)
+
+**C) Environment**
+
+- `PLAYWRIGHT_BROWSERSTACK_E2E_DIR` – e2e directory (relative to cwd)
+- `PLAYWRIGHT_BROWSERSTACK_CSV_DIR` – CSV output directory
+
+### 4. BrowserStack sync
+
+To push test cases to BrowserStack Test Management:
+
+1. In your project root, create a `.env` file (do not commit it):
+
+   ```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 [BrowserStack Test Management → API keys](https://test-management.browserstack.com/settings/api-keys). Project ID is in the project URL (e.g. `PR-1234`).
+
+3. Run without `--csv-only`:
+
+   ```bash
+   npx am-browserstack-sync
+   ```
+
+The tool will:
+
+- Create **one folder per spec file** under your project (e.g. `login.spec`, `checkout.spec`).
+- **Create** test cases that don’t exist yet; **update** existing ones (matched by title or TC-id tag). No duplicates.
+- When you change a test in the repo and run sync again, the corresponding test case on BrowserStack is updated.
+
+---
+
+## What it does
+
+1. **Analyzes** all spec files in your e2e dir:
+   - **Playwright:** `*.spec.ts`, `*.spec.js`, `*.test.ts`, `*.test.js`
+   - **Cypress:** `*.cy.ts`, `*.cy.js`
+2. **Extracts** test titles from `test('...')` and `it('...')` (ignores `describe`).
+3. **Enriches** each test with defaults: State **Active**, Type **Functional**, **automated**, plus inferred **tags** (framework: `playwright` or `cypress`, plus spec name and title).
+4. **Writes one CSV per spec** with columns: `test_case_id`, `title`, `state`, `case_type`, `steps`, `expected_results`, `jira_issues`, `automation_status`, `tags`, `description`, `spec_file`.
+5. **Optionally** syncs to BrowserStack: creates folders, creates/updates test cases with description, steps, expected results, state, type, automation status, and tags.
+
+### CSV columns and BrowserStack fields
+
+| Column / field | Description | Default / example |
+|----------------|-------------|-------------------|
+| **title** | Test case title | From spec `test('...')` / `it('...')` |
+| **state** | Lifecycle state | `Active` (or Draft, In Review, Outdated, Rejected) |
+| **case_type** | Type of test | `Functional` (or Smoke & Sanity, Regression, etc.) |
+| **steps** | Test steps with expected result | "Step 1: Run Playwright/Cypress e2e test \| Expected: See spec file..." |
+| **expected_results** | Expected outcome | Filled from step results |
+| **jira_issues** | Linked Jira keys | Empty (comma-separated in CSV) |
+| **automation_status** | Automated or not | `automated` |
+| **tags** | Functionality / labels | Inferred from spec name + title plus `playwright`/`cypress`, `e2e` |
+| **description** | Test description | "Playwright/Cypress e2e test. ID: TC-001. [title]" |
+
+---
+
+## Programmatic API
+
+You can import the package and call `runSync` from your own scripts:
+
+```js
+import { runSync } from '@ash-mallick/browserstack-sync';
+
+await runSync({
+  cwd: '/path/to/your/project',
+  csvOnly: true,
+  all: true,           // skip interactive prompt, sync all specs
+  spec: ['login.spec'], // or sync only these specs
+  // optional: e2eDir, csvOutputDir, auth: { username, accessKey, projectId },
+});
+```
+
+---
+
+## Publishing this package
+
+1. **Package name** is `@ash-mallick/browserstack-sync`. The CLI command is **`am-browserstack-sync`**.
+
+2. **Set repository URL** in `package.json` (optional):
+   ```json
+   "repository": { "type": "git", "url": "https://github.com/ash-mallick/browserstack-sync" }
+   ```
+
+3. **Publish to npm:**
+   ```bash
+   npm login
+   npm publish --access public
+   ```
+   (Scoped packages require `--access public` for public installs.)
+
+4. **Use it in another project:**
+   ```bash
+   npm install @ash-mallick/browserstack-sync
+   npx am-browserstack-sync --csv-only
+   ```
+
+---
+
+## This repo as a demo
+
+This repository is the package source and includes sample specs under `playwright/e2e/`. To run the sync **in this repo**:
+
+```bash
+npm install
+npm run sync:csv-only
+# or with .env set:
+npm run sync:csv
+```
+
+CSVs are written to `playwright/e2e-csv/`.
+
+---
+
+**Author:** Ashutosh Mallick

package/bin/cli.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * 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.
+ *
+ * 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
+ */
+
+import { runSync } from '../lib/index.js';
+
+const argv = process.argv.slice(2);
+const csvOnly = argv.includes('--csv-only');
+const all = argv.includes('--all');
+const specArg = argv.find((a) => a.startsWith('--spec='));
+let spec = [];
+if (specArg) {
+  const value = specArg.slice('--spec='.length).trim();
+  if (value) spec = value.split(',').map((s) => s.trim()).filter(Boolean);
+}
+const cwd = argv.includes('--cwd') ? argv[argv.indexOf('--cwd') + 1] : process.cwd();
+
+runSync({ cwd, csvOnly, all, spec }).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/lib/browserstack.js

@@ -0,0 +1,143 @@
+const BS_BASE = 'https://test-management.browserstack.com/api/v2';
+
+function authHeader(auth) {
+  // Some Test Management setups expect a single token in API-TOKEN header
+  if (auth.apiToken) {
+    return { 'API-TOKEN': auth.apiToken };
+  }
+  // Standard Basic auth: username:accessKey (from Test Management → Settings → API Keys)
+  const user = (auth.username || '').trim();
+  const key = (auth.accessKey || '').trim();
+  const token = Buffer.from(`${user}:${key}`).toString('base64');
+  return { Authorization: `Basic ${token}` };
+}
+
+export async function bsRequest(method, url, auth, body = null) {
+  const opts = {
+    method,
+    headers: {
+      ...authHeader(auth),
+      'Content-Type': 'application/json',
+    },
+  };
+  if (body && (method === 'POST' || method === 'PATCH')) opts.body = JSON.stringify(body);
+  const res = await fetch(url, opts);
+  const text = await res.text();
+  let data = null;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch (_) {
+    data = { raw: text };
+  }
+  if (!res.ok) {
+    throw new Error(`BrowserStack API ${res.status}: ${url} -> ${JSON.stringify(data)}`);
+  }
+  return data;
+}
+
+export async function ensureFolder(projectId, folderName, parentId, auth) {
+  const listUrl = `${BS_BASE}/projects/${encodeURIComponent(projectId)}/folders?p=1`;
+  const list = await bsRequest('GET', listUrl, auth);
+  const folders = list.folders || [];
+  const existing = folders.find(
+    (f) => f.name === folderName && (parentId == null ? f.parent_id == null : f.parent_id === parentId)
+  );
+  if (existing) return existing.id;
+
+  const createUrl = `${BS_BASE}/projects/${encodeURIComponent(projectId)}/folders`;
+  const create = await bsRequest('POST', createUrl, auth, {
+    folder: {
+      name: folderName,
+      description: `Tests from spec: ${folderName}`,
+      parent_id: parentId,
+    },
+  });
+  return create.folder?.id ?? create.folder_id;
+}
+
+export async function getTestCasesInFolder(projectId, folderId, auth) {
+  const all = [];
+  let page = 1;
+  let hasMore = true;
+  while (hasMore) {
+    const url = `${BS_BASE}/projects/${encodeURIComponent(projectId)}/test-cases?folder_id=${folderId}&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;
+}
+
+function buildTestCasePayload(testCase) {
+  const steps = Array.isArray(testCase.steps) && testCase.steps.length > 0
+    ? testCase.steps.map((s) => ({ step: s.step ?? '', result: s.result ?? '' }))
+    : [{ step: 'Run Playwright e2e test', result: 'See spec file for implementation.' }];
+  const tags = Array.isArray(testCase.tags) ? testCase.tags : ['playwright', 'e2e', testCase.id];
+  const payload = {
+    name: testCase.title,
+    description: testCase.description ? `<p>${String(testCase.description).replace(/\n/g, '</p><p>')}</p>` : `<p>Playwright e2e test. ID: ${testCase.id}. ${testCase.title}</p>`,
+    preconditions: '',
+    test_case_steps: steps,
+    tags: [...tags, testCase.id],
+    status: testCase.state ?? 'Active',
+    case_type: testCase.case_type ?? 'Functional',
+    automation_status: testCase.automation_status ?? 'automated',
+  };
+  if (Array.isArray(testCase.jira_issues) && testCase.jira_issues.length > 0) {
+    payload.issues = testCase.jira_issues;
+  }
+  return payload;
+}
+
+export async function createTestCase(projectId, folderId, testCase, auth) {
+  const url = `${BS_BASE}/projects/${encodeURIComponent(projectId)}/folders/${folderId}/test-cases`;
+  const body = { test_case: buildTestCasePayload(testCase) };
+  const res = await bsRequest('POST', url, auth, body);
+  return res.data?.test_case?.identifier ?? res.test_case?.identifier;
+}
+
+function testCasePayload(testCase) {
+  return buildTestCasePayload(testCase);
+}
+
+export async function updateTestCase(projectId, testCaseId, testCase, auth) {
+  const url = `${BS_BASE}/projects/${encodeURIComponent(projectId)}/test-cases/${testCaseId}`;
+  const body = { test_case: testCasePayload(testCase) };
+  await bsRequest('PATCH', url, auth, body);
+  return testCaseId;
+}
+
+/** Match existing BS test case to our local case: by title or by our TC-xxx tag */
+function findExisting(existingList, localCase) {
+  const byTitle = existingList.find((t) => (t.title || '').trim() === (localCase.title || '').trim());
+  if (byTitle) return byTitle;
+  const byTag = existingList.find((t) => (t.tags || []).includes(localCase.id));
+  return byTag;
+}
+
+export async function syncToBrowserStack(specsMap, projectId, auth) {
+  console.log('\nSyncing to BrowserStack project', projectId);
+  for (const [baseName, { specFile, cases }] of specsMap) {
+    const folderName = baseName;
+    const folderId = await ensureFolder(projectId, folderName, null, auth);
+    const existing = await getTestCasesInFolder(projectId, folderId, auth);
+    console.log('Folder:', folderName, '(id:', folderId, ')');
+    for (const tc of cases) {
+      try {
+        const found = findExisting(existing, tc);
+        if (found) {
+          await updateTestCase(projectId, found.identifier, tc, auth);
+          console.log('  Updated', tc.id, tc.title, '->', found.identifier);
+        } else {
+          const id = await createTestCase(projectId, folderId, tc, auth);
+          console.log('  Created', tc.id, tc.title, '->', id);
+        }
+      } catch (e) {
+        console.error('  Failed', tc.id, tc.title, e.message);
+      }
+    }
+  }
+}

package/lib/config.js

@@ -0,0 +1,88 @@
+import fs from 'fs';
+import path from 'path';
+
+const CONFIG_FILES = [
+  '.am-browserstack-sync.json',
+  'am-browserstack-sync.config.json',
+  '.am-e2e-sync.json',
+  'am-e2e-sync.config.json',
+  '.playwright-browserstack-sync.json',
+  'playwright-browserstack-sync.config.json',
+  '.config/am-browserstack-sync.json',
+];
+
+const DEFAULTS = {
+  e2eDir: 'playwright/e2e',
+  csvOutputDir: 'playwright/e2e-csv',
+};
+
+/**
+ * Load config from cwd: env > config file > package.json field > defaults.
+ * Returns { cwd, e2eDir, csvOutputDir } (paths are absolute).
+ */
+export function loadConfig(cwd) {
+  const resolvedCwd = path.resolve(cwd || process.cwd());
+  let e2eDir = DEFAULTS.e2eDir;
+  let csvOutputDir = DEFAULTS.csvOutputDir;
+
+  // package.json field
+  const pkgPath = path.join(resolvedCwd, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      const field = pkg.amBrowserstackSync || pkg.amE2eSync || pkg.playwrightBrowserstackSync || pkg['playwright-browserstack-sync'];
+      if (field) {
+        if (field.e2eDir) e2eDir = field.e2eDir;
+        if (field.csvOutputDir) csvOutputDir = field.csvOutputDir;
+      }
+    } catch (_) {}
+  }
+
+  // Config file (overrides package.json)
+  for (const name of CONFIG_FILES) {
+    const configPath = path.join(resolvedCwd, name);
+    if (fs.existsSync(configPath)) {
+      try {
+        const data = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        if (data.e2eDir) e2eDir = data.e2eDir;
+        if (data.csvOutputDir) csvOutputDir = data.csvOutputDir;
+        break;
+      } catch (_) {}
+    }
+  }
+
+  // Env overrides
+  if (process.env.PLAYWRIGHT_BROWSERSTACK_E2E_DIR) e2eDir = process.env.PLAYWRIGHT_BROWSERSTACK_E2E_DIR;
+  if (process.env.PLAYWRIGHT_BROWSERSTACK_CSV_DIR) csvOutputDir = process.env.PLAYWRIGHT_BROWSERSTACK_CSV_DIR;
+
+  return {
+    cwd: resolvedCwd,
+    e2eDir: path.resolve(resolvedCwd, e2eDir),
+    csvOutputDir: path.resolve(resolvedCwd, csvOutputDir),
+  };
+}
+
+function trim(s) {
+  return typeof s === 'string' ? s.trim() : s;
+}
+
+/**
+ * Get BrowserStack credentials from env (after dotenv has been loaded in cwd).
+ * Supports either username+accessKey or a single API token (from Test Management → API Keys).
+ * Values are trimmed to avoid 401 from stray spaces/newlines in .env.
+ */
+export function getBrowserStackEnv() {
+  const username = trim(process.env.BROWSERSTACK_USERNAME);
+  const accessKey = trim(process.env.BROWSERSTACK_ACCESS_KEY);
+  const apiToken = trim(
+    process.env.BROWSERSTACK_API_TOKEN ||
+    process.env.TEST_MANAGEMENT_API_TOKEN
+  );
+  const projectId = trim(process.env.BROWSERSTACK_PROJECT_ID);
+  return {
+    username: username || undefined,
+    accessKey: accessKey || undefined,
+    apiToken: apiToken || undefined,
+    projectId: projectId || undefined,
+  };
+}

package/lib/csv.js

@@ -0,0 +1,70 @@
+import fs from 'fs';
+import path from 'path';
+
+function escapeCsv(s) {
+  const t = String(s ?? '');
+  if (/[",\n\r]/.test(t)) return `"${t.replace(/"/g, '""')}"`;
+  return t;
+}
+
+/** Format steps for CSV: "Step 1: ... | Expected: ... ; Step 2: ..." */
+function formatStepsForCsv(steps) {
+  if (!Array.isArray(steps) || steps.length === 0) return '';
+  return steps
+    .map((s, i) => {
+      const step = s.step ?? s;
+      const result = s.result ?? '';
+      return `Step ${i + 1}: ${step} | Expected: ${result}`;
+    })
+    .join(' ; ');
+}
+
+/**
+ * Write one CSV per spec file under csvOutputDir.
+ * Columns: test_case_id, title, state, case_type, steps, expected_results, jira_issues, automation_status, tags, description, spec_file
+ */
+export function writeCsvFiles(specsMap, csvOutputDir) {
+  if (!fs.existsSync(csvOutputDir)) {
+    fs.mkdirSync(csvOutputDir, { recursive: true });
+  }
+  const headers = [
+    'test_case_id',
+    'title',
+    'state',
+    'case_type',
+    'steps',
+    'expected_results',
+    'jira_issues',
+    'automation_status',
+    'tags',
+    'description',
+    'spec_file',
+  ];
+  for (const [baseName, { specFile, cases }] of specsMap) {
+    const rows = [
+      headers.map(escapeCsv).join(','),
+      ...cases.map((c) => {
+        const stepsStr = formatStepsForCsv(c.steps);
+        const jiraStr = Array.isArray(c.jira_issues) ? c.jira_issues.join(', ') : '';
+        const tagsStr = Array.isArray(c.tags) ? c.tags.join(', ') : '';
+        const expectedResults = c.expected_results ?? (c.steps && c.steps.length ? c.steps.map((s) => s.result).join(' ') : '');
+        return [
+          c.id,
+          c.title,
+          c.state ?? 'Active',
+          c.case_type ?? 'Functional',
+          stepsStr,
+          expectedResults,
+          jiraStr,
+          c.automation_status ?? 'automated',
+          tagsStr,
+          c.description ?? '',
+          specFile,
+        ].map(escapeCsv).join(',');
+      }),
+    ];
+    const csvPath = path.join(csvOutputDir, `${baseName}.csv`);
+    fs.writeFileSync(csvPath, rows.join('\n'), 'utf-8');
+    console.log('Wrote', csvPath, `(${cases.length} test cases)`);
+  }
+}

package/lib/enrich.js

@@ -0,0 +1,73 @@
+/**
+ * Enrich test cases with state, type, steps, tags, description, etc.
+ * Supports Playwright and Cypress; infer tags from spec name + title.
+ */
+
+const DEFAULT_STATE = 'Active';
+const DEFAULT_CASE_TYPE = 'Functional';
+const DEFAULT_AUTOMATION_STATUS = 'automated';
+const DEFAULT_EXPECTED_RESULT = 'See spec file for implementation and assertions.';
+
+const FRAMEWORK = {
+  playwright: { step: 'Run Playwright e2e test', desc: 'Playwright e2e test' },
+  cypress: { step: 'Run Cypress e2e test', desc: 'Cypress e2e test' },
+};
+
+function slug(text) {
+  return String(text || '')
+    .replace(/\s+/g, '_')
+    .replace(/[^a-zA-Z0-9_]/g, '')
+    .replace(/_+/g, '_')
+    .replace(/^_|_$/g, '')
+    .toLowerCase() || 'test';
+}
+
+/** Infer functionality tags from spec base name and test title; include framework tag. */
+function inferTags(specBaseName, title, isCypress) {
+  const base = specBaseName.replace(/\.(spec|test|cy)$/i, '');
+  const specSlug = slug(base);
+  const titleSlug = slug(title.replace(/^\s*TC-\d+\s*[-–]\s*/i, ''));
+  const tags = [isCypress ? 'cypress' : 'playwright', 'e2e', specSlug];
+  if (titleSlug && titleSlug !== specSlug) tags.push(titleSlug);
+  return tags;
+}
+
+/**
+ * Enrich a single case with state, case_type, steps, expected_results, jira_issues, automation_status, tags, description.
+ */
+export function enrichCase(case_, specBaseName, isCypress = false) {
+  const title = case_.title || '';
+  const id = case_.id || '';
+  const fw = isCypress ? FRAMEWORK.cypress : FRAMEWORK.playwright;
+  const tags = inferTags(specBaseName, title, isCypress);
+  const steps = case_.steps && case_.steps.length > 0
+    ? case_.steps
+    : [{ step: fw.step, result: DEFAULT_EXPECTED_RESULT }];
+  const expectedResults = case_.expected_results ?? steps.map((s) => s.result).join(' ');
+  const description = case_.description ?? `${fw.desc}. ID: ${id}. ${title}`;
+
+  return {
+    ...case_,
+    title,
+    id,
+    state: case_.state ?? DEFAULT_STATE,
+    case_type: case_.case_type ?? DEFAULT_CASE_TYPE,
+    steps,
+    expected_results: case_.expected_results ?? expectedResults,
+    jira_issues: case_.jira_issues ?? [],
+    automation_status: case_.automation_status ?? DEFAULT_AUTOMATION_STATUS,
+    tags: case_.tags && case_.tags.length > 0 ? case_.tags : tags,
+    description,
+  };
+}
+
+/**
+ * Enrich all cases in specsMap. Mutates cases in place; returns specsMap.
+ */
+export function enrichSpecsMap(specsMap) {
+  for (const [baseName, data] of specsMap) {
+    const isCypress = data.isCypress === true;
+    data.cases = data.cases.map((c) => enrichCase(c, baseName, isCypress));
+  }
+  return specsMap;
+}

package/lib/index.js

@@ -0,0 +1,80 @@
+import dotenv from 'dotenv';
+import path from 'path';
+import { analyzeSpecs } from './parser.js';
+import { enrichSpecsMap } from './enrich.js';
+import { writeCsvFiles } from './csv.js';
+import { syncToBrowserStack } from './browserstack.js';
+import { loadConfig, getBrowserStackEnv } from './config.js';
+import { promptSpecSelection } from './prompt.js';
+
+/**
+ * Run sync: analyze specs, write CSVs, optionally sync to BrowserStack.
+ * @param {Object} options
+ * @param {string} [options.cwd] - Project root (default: process.cwd())
+ * @param {string} [options.e2eDir] - Override e2e dir (absolute or relative to cwd)
+ * @param {string} [options.csvOutputDir] - Override CSV output dir
+ * @param {boolean} [options.csvOnly] - If true, skip BrowserStack sync
+ * @param {boolean} [options.all] - If true, sync all specs (skip interactive prompt)
+ * @param {string[]} [options.spec] - Sync only these spec base names (e.g. ['login.spec']). Skips prompt.
+ * @param {boolean} [options.interactive] - If false, skip prompt and sync all (default: true when no --all/--spec)
+ * @param {Object} [options.auth] - { username, accessKey, projectId } (default: from env)
+ */
+export async function runSync(options = {}) {
+  const config = loadConfig(options.cwd);
+  const cwd = config.cwd;
+
+  dotenv.config({ path: path.join(cwd, '.env') });
+
+  const e2eDir = options.e2eDir != null ? path.resolve(cwd, options.e2eDir) : config.e2eDir;
+  const csvOutputDir = options.csvOutputDir != null ? path.resolve(cwd, options.csvOutputDir) : config.csvOutputDir;
+  const csvOnly = options.csvOnly === true;
+
+  let specsMap = analyzeSpecs(e2eDir);
+  if (specsMap.size === 0) {
+    console.log('No spec files found in', e2eDir);
+    return;
+  }
+  enrichSpecsMap(specsMap);
+
+  if (!csvOnly) {
+    if (options.all) {
+      // sync all, no prompt
+    } else if (options.spec && options.spec.length > 0) {
+      const set = new Set(options.spec);
+      specsMap = new Map([...specsMap].filter(([name]) => set.has(name)));
+      if (specsMap.size === 0) {
+        console.log('No matching spec files for:', options.spec.join(', '));
+        return;
+      }
+    } else if (options.interactive !== false && process.stdin.isTTY) {
+      const selected = await promptSpecSelection(specsMap);
+      if (selected === null) {
+        // user chose "all"
+      } else if (selected.size === 0) {
+        console.log('No spec files selected. Exiting.');
+        return;
+      } else {
+        specsMap = new Map([...specsMap].filter(([name]) => selected.has(name)));
+      }
+    }
+  }
+
+  writeCsvFiles(specsMap, csvOutputDir);
+
+  if (csvOnly) {
+    console.log('\nCSV-only mode. Skipping BrowserStack sync.');
+    return;
+  }
+
+  const auth = options.auth || getBrowserStackEnv();
+  const hasAuth = (auth.username && auth.accessKey) || auth.apiToken;
+  if (!hasAuth || !auth.projectId) {
+    console.log(
+      '\nSkipping BrowserStack sync. Set credentials in .env: either BROWSERSTACK_USERNAME + BROWSERSTACK_ACCESS_KEY, or BROWSERSTACK_API_TOKEN (from Test Management → Settings → API Keys), and BROWSERSTACK_PROJECT_ID.'
+    );
+    return;
+  }
+
+  await syncToBrowserStack(specsMap, auth.projectId, auth);
+  console.log('\nDone.');
+}

package/lib/parser.js

@@ -0,0 +1,50 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Extract test titles from a Playwright or Cypress spec file.
+ * Matches test('title', ...) and it('title', ...); skips test.describe(...) / describe(...).
+ */
+export function extractTestTitles(content) {
+  const titles = [];
+  const regex = /\b(?:test|it)\s*(?:\.\s*(?!describe)(?:only|skip))?\s*\(\s*['"]([^'"]*)['"]/g;
+  let m;
+  while ((m = regex.exec(content)) !== null) {
+    const title = (m[1] ?? '').trim();
+    if (title) titles.push(title);
+  }
+  const backtickRegex = /\b(?:test|it)\s*(?:\.\s*(?!describe)(?:only|skip))?\s*\(\s*`([^`]*)`/g;
+  while ((m = backtickRegex.exec(content)) !== null) {
+    const title = (m[1] ?? '').trim();
+    if (title && !titles.includes(title)) titles.push(title);
+  }
+  return titles;
+}
+
+/** Match Playwright (*.spec, *.test) and Cypress (*.cy) spec files */
+const SPEC_FILE_PATTERN = /\.(spec|test|cy)\.(ts|js)$/i;
+
+/**
+ * For each spec file in e2eDir, extract tests and assign TC-001, TC-002, ...
+ * Supports Playwright (*.spec.ts/js, *.test.ts/js) and Cypress (*.cy.ts/js).
+ * Returns Map<specBasename, { specFile, cases: Array<{ id, title }> }>
+ */
+export function analyzeSpecs(e2eDir) {
+  if (!fs.existsSync(e2eDir)) {
+    throw new Error(`E2E directory not found: ${e2eDir}`);
+  }
+  const files = fs.readdirSync(e2eDir).filter((f) => SPEC_FILE_PATTERN.test(f));
+  const results = new Map();
+  for (const file of files) {
+    const filePath = path.join(e2eDir, file);
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const titles = extractTestTitles(content);
+    const baseName = path.basename(file, path.extname(file));
+    const cases = titles.map((title, index) => ({
+      id: `TC-${String(index + 1).padStart(3, '0')}`,
+      title: title.replace(/^\s*TC-\d+\s*[-–]\s*/i, '').trim() || title,
+    }));
+    results.set(baseName, { specFile: file, cases, isCypress: /\.cy\.(ts|js)$/i.test(file) });
+  }
+  return results;
+}

package/lib/prompt.js

@@ -0,0 +1,44 @@
+import readline from 'readline';
+
+function question(rl, prompt) {
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => resolve((answer || '').trim()));
+  });
+}
+
+/**
+ * Interactive spec selection. Returns a Set of selected spec base names (e.g. 'login.spec').
+ * If user chooses "all", returns null (meaning no filter). If "choose", returns Set of chosen names.
+ */
+export async function promptSpecSelection(specsMap) {
+  const names = Array.from(specsMap.keys());
+  if (names.length === 0) return new Set();
+  if (names.length === 1) return null;
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  console.log('\nWhich spec file(s) do you want to sync to BrowserStack?');
+  console.log('  1) All spec files');
+  console.log('  2) Choose spec file(s)\n');
+  names.forEach((name, i) => {
+    console.log(`     ${i + 3}) ${name}`);
+  });
+  console.log('\n  (For option 2, enter the numbers of specs you want, e.g. 3,4)\n');
+
+  const choice = await question(rl, 'Enter option number(s): ');
+  rl.close();
+
+  const parts = choice.split(/[\s,]+/).filter(Boolean);
+  if (parts.includes('1')) return null;
+
+  const selected = new Set();
+  for (const p of parts) {
+    const num = parseInt(p, 10);
+    if (num >= 3 && num <= names.length + 2) {
+      selected.add(names[num - 3]);
+    } else if (names.includes(p)) {
+      selected.add(p);
+    }
+  }
+  return selected.size ? selected : null;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ash-mallick/browserstack-sync",
+  "version": "1.0.0",
+  "description": "Sync Playwright & Cypress e2e specs to CSV and BrowserStack Test Management (one folder per spec)",
+  "author": "Ashutosh Mallick",
+  "type": "module",
+  "main": "lib/index.js",
+  "bin": {
+    "am-browserstack-sync": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "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",
+    "prepublishOnly": "node bin/cli.js --csv-only",
+    "publish:public": "npm publish --access public"
+  },
+  "keywords": [
+    "playwright",
+    "cypress",
+    "browserstack",
+    "e2e",
+    "test-management",
+    "sync",
+    "ash-mallick"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "dependencies": {
+    "dotenv": "^16.4.5"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.49.0",
+    "playwright": "^1.49.0"
+  },
+  "peerDependencies": {},
+  "peerDependenciesMeta": {},
+  "engines": {
+    "node": ">=18"
+  }
+}