@ash-mallick/browserstack-sync 1.0.4 → 1.0.6

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 (2) hide show
  1. package/README.md +169 -45
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,122 +1,246 @@
1
1
  # @ash-mallick/browserstack-sync
2
2
 
3
- 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).
3
+ Sync **Playwright** and **Cypress** e2e test specs to CSV files and **BrowserStack Test Management**.
4
4
 
5
5
  **By Ashutosh Mallick**
6
6
 
7
7
  ---
8
8
 
9
+ ## What It Does
10
+
11
+ - Scans your e2e test files (Playwright or Cypress)
12
+ - Extracts test cases and assigns IDs (TC-001, TC-002, ...)
13
+ - Generates **one CSV file per spec** with test details
14
+ - Optionally syncs to **BrowserStack Test Management** (creates folders and test cases)
15
+ - **Idempotent**: existing tests are updated, new ones are created (no duplicates)
16
+
17
+ ---
18
+
9
19
  ## Install
10
20
 
11
21
  ```bash
12
22
  npm install @ash-mallick/browserstack-sync
13
23
  ```
14
24
 
15
- Or run without installing: `npx @ash-mallick/browserstack-sync --csv-only`
25
+ Or run directly without installing:
26
+
27
+ ```bash
28
+ npx @ash-mallick/browserstack-sync --csv-only
29
+ ```
16
30
 
17
31
  ---
18
32
 
19
- ## Run
33
+ ## Usage
20
34
 
21
- From your project root (where your e2e specs live):
35
+ Run from your project root:
22
36
 
23
37
  ```bash
24
- # Generate CSVs only
38
+ # Generate CSVs only (no BrowserStack sync)
25
39
  npx am-browserstack-sync --csv-only
26
40
 
27
- # Sync to BrowserStack (interactive: choose all or specific specs)
41
+ # Sync to BrowserStack (interactive prompt)
28
42
  npx am-browserstack-sync
29
43
 
30
- # Sync all specs, no prompt (e.g. CI)
44
+ # Sync all specs without prompt (for CI/CD)
31
45
  npx am-browserstack-sync --all
32
46
 
33
- # Sync only certain specs
47
+ # Sync specific specs only
34
48
  npx am-browserstack-sync --spec=login.spec,checkout.spec
35
49
  ```
36
50
 
37
- **Scripts** in `package.json`:
51
+ ### Add to package.json scripts
38
52
 
39
53
  ```json
40
54
  {
41
55
  "scripts": {
42
56
  "sync:e2e": "am-browserstack-sync",
43
- "sync:e2e-csv": "am-browserstack-sync --csv-only"
57
+ "sync:csv": "am-browserstack-sync --csv-only"
44
58
  }
45
59
  }
46
60
  ```
47
61
 
48
62
  ---
49
63
 
50
- ## Config (optional)
64
+ ## Supported Frameworks
65
+
66
+ | Framework | File Patterns | Auto-Detected Directory |
67
+ |-----------|---------------|------------------------|
68
+ | Playwright | `*.spec.ts`, `*.spec.js`, `*.test.ts`, `*.test.js` | `playwright/e2e` |
69
+ | Cypress | `*.cy.ts`, `*.cy.js` | `cypress/e2e` |
70
+ | Generic | Any of the above | `e2e` |
71
+
72
+ **Auto-detection priority:**
73
+ 1. `playwright/e2e` (if exists)
74
+ 2. `cypress/e2e` (if exists)
75
+ 3. `e2e` (generic fallback)
51
76
 
52
- **Auto-detection:** The tool automatically detects your e2e directory structure:
77
+ No configuration needed for standard project structures!
53
78
 
54
- | Priority | Directory | CSV Output |
55
- |----------|-----------|------------|
56
- | 1st | `playwright/e2e` | `playwright/e2e-csv` |
57
- | 2nd | `cypress/e2e` | `cypress/e2e-csv` |
58
- | 3rd | `e2e` | `e2e-csv` |
79
+ ---
59
80
 
60
- No config needed for standard Playwright or Cypress projects!
81
+ ## Configuration (Optional)
61
82
 
62
- **Override** via **`.am-browserstack-sync.json`** in project root:
83
+ Override defaults via **`.am-browserstack-sync.json`** in project root:
63
84
 
64
85
  ```json
65
86
  {
66
- "e2eDir": "playwright/e2e",
67
- "csvOutputDir": "playwright/e2e-csv"
87
+ "e2eDir": "tests/e2e",
88
+ "csvOutputDir": "tests/csv-output"
68
89
  }
69
90
  ```
70
91
 
71
- Or **package.json**: `"amBrowserstackSync": { "e2eDir": "...", "csvOutputDir": "..." }`
72
- Or env: `PLAYWRIGHT_BROWSERSTACK_E2E_DIR`, `PLAYWRIGHT_BROWSERSTACK_CSV_DIR`.
92
+ Or in **package.json**:
93
+
94
+ ```json
95
+ {
96
+ "amBrowserstackSync": {
97
+ "e2eDir": "cypress/e2e",
98
+ "csvOutputDir": "cypress/csv"
99
+ }
100
+ }
101
+ ```
102
+
103
+ Or via **environment variables**:
104
+
105
+ ```bash
106
+ PLAYWRIGHT_BROWSERSTACK_E2E_DIR=tests/e2e
107
+ PLAYWRIGHT_BROWSERSTACK_CSV_DIR=tests/csv
108
+ ```
73
109
 
74
110
  ---
75
111
 
76
- ## BrowserStack sync
112
+ ## BrowserStack Integration
113
+
114
+ ### Setup
115
+
116
+ 1. Create a **`.env`** file in your project root (don't commit this!):
117
+
118
+ ```env
119
+ BROWSERSTACK_USERNAME=your_username
120
+ BROWSERSTACK_ACCESS_KEY=your_access_key
121
+ BROWSERSTACK_PROJECT_ID=PR-XXXX
122
+ ```
123
+
124
+ Or use a single API token:
125
+
126
+ ```env
127
+ BROWSERSTACK_API_TOKEN=your_token
128
+ BROWSERSTACK_PROJECT_ID=PR-XXXX
129
+ ```
77
130
 
78
- 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.
131
+ 2. Get credentials from [BrowserStack Test Management → Settings → API Keys](https://test-management.browserstack.com/settings/api-keys)
79
132
 
80
- **Setup:**
133
+ 3. Find your Project ID in the BrowserStack project URL (e.g., `PR-1234`)
81
134
 
82
- 1. In project root, create **`.env`** (do not commit):
135
+ ### What Gets Synced
83
136
 
84
- ```env
85
- BROWSERSTACK_USERNAME=your_username
86
- BROWSERSTACK_ACCESS_KEY=your_access_key
87
- BROWSERSTACK_PROJECT_ID=PR-XXXX
88
- ```
89
- Or use a single token: `BROWSERSTACK_API_TOKEN=your_token`
137
+ For each spec file, the tool:
138
+ - Creates a **folder** in BrowserStack (named after the spec file)
139
+ - Creates **test cases** with:
140
+ - Title (from test name)
141
+ - Description
142
+ - Steps and expected results
143
+ - State (Active)
144
+ - Type (Functional)
145
+ - Automation status (automated)
146
+ - Tags (framework, spec name, test keywords)
90
147
 
91
- 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`).
148
+ ### Idempotent Sync
92
149
 
93
- 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.
150
+ - **New tests** → Created in BrowserStack
151
+ - **Existing tests** (matched by title or TC-ID tag) → Updated
152
+ - **No duplicates** are created
94
153
 
95
154
  ---
96
155
 
97
- ## What it does
156
+ ## CSV Output
157
+
158
+ Each spec file generates a CSV with these columns:
98
159
 
99
- - Finds **Playwright** (`*.spec.*`, `*.test.*`) and **Cypress** (`*.cy.*`) spec files in your e2e dir.
100
- - Extracts test titles from `test('...')` / `it('...')`, assigns TC-001, TC-002, …
101
- - Enriches with state (Active), type (Functional), automation (automated), tags (from spec + title).
102
- - Writes **one CSV per spec** (test_case_id, title, state, case_type, steps, expected_results, jira_issues, automation_status, tags, description, spec_file).
103
- - Optionally syncs to BrowserStack with description, steps, and tags.
160
+ | Column | Description |
161
+ |--------|-------------|
162
+ | `test_case_id` | TC-001, TC-002, ... |
163
+ | `title` | Test name |
164
+ | `state` | Active, Draft, etc. |
165
+ | `case_type` | Functional, Regression, etc. |
166
+ | `steps` | Test steps |
167
+ | `expected_results` | Expected outcomes |
168
+ | `jira_issues` | Linked Jira tickets |
169
+ | `automation_status` | automated / manual |
170
+ | `tags` | Framework, functionality tags |
171
+ | `description` | Test description |
172
+ | `spec_file` | Source file name |
104
173
 
105
174
  ---
106
175
 
107
176
  ## Programmatic API
108
177
 
109
- ```js
178
+ Use in your own scripts:
179
+
180
+ ```javascript
110
181
  import { runSync } from '@ash-mallick/browserstack-sync';
111
182
 
112
183
  await runSync({
113
184
  cwd: '/path/to/project',
114
- csvOnly: true,
185
+ csvOnly: false,
115
186
  all: true,
116
- spec: ['login.spec'],
187
+ // Or specify specific specs:
188
+ // spec: ['login.spec', 'checkout.spec'],
117
189
  });
118
190
  ```
119
191
 
192
+ ### Options
193
+
194
+ | Option | Type | Description |
195
+ |--------|------|-------------|
196
+ | `cwd` | string | Project root directory |
197
+ | `csvOnly` | boolean | Skip BrowserStack sync |
198
+ | `all` | boolean | Sync all specs (no prompt) |
199
+ | `spec` | string[] | Specific specs to sync |
200
+ | `e2eDir` | string | Override e2e directory |
201
+ | `csvOutputDir` | string | Override CSV output directory |
202
+
203
+ ---
204
+
205
+ ## Example Project Structure
206
+
207
+ ### Playwright
208
+
209
+ ```
210
+ my-project/
211
+ ├── package.json
212
+ ├── .env # BrowserStack credentials
213
+ ├── playwright/
214
+ │ ├── e2e/ # Your test files
215
+ │ │ ├── login.spec.ts
216
+ │ │ └── checkout.spec.ts
217
+ │ └── e2e-csv/ # Generated CSVs
218
+ │ ├── login.spec.csv
219
+ │ └── checkout.spec.csv
220
+ ```
221
+
222
+ ### Cypress
223
+
224
+ ```
225
+ my-project/
226
+ ├── package.json
227
+ ├── .env
228
+ ├── cypress/
229
+ │ ├── e2e/ # Your test files
230
+ │ │ ├── login.cy.ts
231
+ │ │ └── cart.cy.ts
232
+ │ └── e2e-csv/ # Generated CSVs
233
+ │ ├── login.cy.csv
234
+ │ └── cart.cy.csv
235
+ ```
236
+
237
+ ---
238
+
239
+ ## License
240
+
241
+ MIT
242
+
120
243
  ---
121
244
 
122
- **Author:** Ashutosh Mallick
245
+ **Author:** Ashutosh Mallick
246
+ **npm:** [@ash-mallick/browserstack-sync](https://www.npmjs.com/package/@ash-mallick/browserstack-sync)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ash-mallick/browserstack-sync",
3
- "version": "1.0.4",
3
+ "version": "1.0.6",
4
4
  "description": "Sync Playwright & Cypress e2e specs to CSV and BrowserStack Test Management (one folder per spec)",
5
5
  "author": "Ashutosh Mallick",
6
6
  "type": "module",