@ash-mallick/browserstack-sync 1.0.0 → 1.0.2

package/README.md

@@ -1,46 +1,40 @@
 # @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).
+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).
 
-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.
+**By Ashutosh Mallick**
 
 ---
 
-## Use in your project
-
-### 1. Install
+## Install
 
 ```bash
 npm install @ash-mallick/browserstack-sync
-# or run without installing
-npx @ash-mallick/browserstack-sync --csv-only
 ```
 
-### 2. Run
+Or run without installing: `npx @ash-mallick/browserstack-sync --csv-only`
+
+---
+
+## Run
 
-From your **project root** (where your `playwright/e2e` or Cypress specs live):
+From your project root (where your e2e specs live):
 
 ```bash
-# CSV only (no BrowserStack API calls)
+# Generate CSVs only
 npx am-browserstack-sync --csv-only
 
-# Sync to BrowserStack – interactive: choose all specs or pick specific ones
+# Sync to BrowserStack (interactive: choose all or specific specs)
 npx am-browserstack-sync
 
-# Sync all specs (no prompt, e.g. for CI)
+# Sync all specs, no prompt (e.g. CI)
 npx am-browserstack-sync --all
 
-# Sync only specific spec(s)
-npx am-browserstack-sync --spec=login.spec
+# Sync only certain specs
 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`:
+**Scripts** in `package.json`:
 
 ```json
 {
@@ -51,22 +45,13 @@ Add scripts in your project’s `package.json`:
 }
 ```
 
-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):
+## Config (optional)
 
-**A) Config file** in project root  
+Defaults: e2e dir `playwright/e2e`, CSV dir `playwright/e2e-csv`. For Cypress use e.g. `cypress/e2e`.
 
-Create `.am-browserstack-sync.json` or `am-browserstack-sync.config.json`:
+Override via **`.am-browserstack-sync.json`** in project root:
 
 ```json
 {
@@ -75,137 +60,55 @@ Create `.am-browserstack-sync.json` or `am-browserstack-sync.config.json`:
 }
 ```
 
-(Legacy names `.am-e2e-sync.json`, `playwright-browserstack-sync.config.json`, etc. are still supported.)
+Or **package.json**: `"amBrowserstackSync": { "e2eDir": "...", "csvOutputDir": "..." }`  
+Or env: `PLAYWRIGHT_BROWSERSTACK_E2E_DIR`, `PLAYWRIGHT_BROWSERSTACK_CSV_DIR`.
 
-**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
+## BrowserStack sync
 
-### 4. 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.
 
-To push test cases to BrowserStack Test Management:
+**Setup:**
 
-1. In your project root, create a `.env` file (do not commit it):
+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 [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`:
+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`).
 
-   ```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.
+3. 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
 
-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]" |
+- Finds **Playwright** (`*.spec.*`, `*.test.*`) and **Cypress** (`*.cy.*`) spec files in your e2e dir.
+- Extracts test titles from `test('...')` / `it('...')`, assigns TC-001, TC-002, …
+- 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.
 
 ---
 
 ## 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',
+  cwd: '/path/to/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 },
+  all: true,
+  spec: ['login.spec'],
 });
 ```
 
 ---
 
-## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ash-mallick/browserstack-sync",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Sync Playwright & Cypress e2e specs to CSV and BrowserStack Test Management (one folder per spec)",
   "author": "Ashutosh Mallick",
   "type": "module",