@ash-mallick/browserstack-sync 1.0.6 → 1.1.2

package/README.md

@@ -1,18 +1,10 @@
 # @ash-mallick/browserstack-sync
 
-Sync **Playwright** and **Cypress** e2e test specs to CSV files and **BrowserStack Test Management**.
+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).
 
-**By Ashutosh Mallick**
-
----
-
-## What It Does
+**🦙 FREE AI-powered test step extraction** using **Ollama** — runs 100% locally, no data sent to cloud!
 
-- Scans your e2e test files (Playwright or Cypress)
-- Extracts test cases and assigns IDs (TC-001, TC-002, ...)
-- Generates **one CSV file per spec** with test details
-- Optionally syncs to **BrowserStack Test Management** (creates folders and test cases)
-- **Idempotent**: existing tests are updated, new ones are created (no duplicates)
+**By Ashutosh Mallick**
 
 ---
 
@@ -22,225 +14,159 @@ Sync **Playwright** and **Cypress** e2e test specs to CSV files and **BrowserSta
 npm install @ash-mallick/browserstack-sync
 ```
 
-Or run directly without installing:
-
-```bash
-npx @ash-mallick/browserstack-sync --csv-only
-```
+Or run without installing: `npx @ash-mallick/browserstack-sync --csv-only`
 
 ---
 
-## Usage
+## Run
 
-Run from your project root:
+From your project root (where your e2e specs live):
 
 ```bash
-# Generate CSVs only (no BrowserStack sync)
+# Generate CSVs only
 npx am-browserstack-sync --csv-only
 
-# Sync to BrowserStack (interactive prompt)
-npx am-browserstack-sync
-
-# Sync all specs without prompt (for CI/CD)
+# Sync all specs, no prompt (e.g. CI)
 npx am-browserstack-sync --all
 
-# Sync specific specs only
+# Sync only certain specs
 npx am-browserstack-sync --spec=login.spec,checkout.spec
+
+# Disable AI analysis (use regex extraction only)
+npx am-browserstack-sync --no-ai
+
+# Use a specific Ollama model
+npx am-browserstack-sync --model=llama3.2
 ```
 
-### Add to package.json scripts
+**Scripts** in `package.json`:
 
 ```json
 {
   "scripts": {
     "sync:e2e": "am-browserstack-sync",
-    "sync:csv": "am-browserstack-sync --csv-only"
+    "sync:e2e-csv": "am-browserstack-sync --csv-only"
   }
 }
 ```
 
 ---
 
-## Supported Frameworks
+## 🦙 AI-Powered Step Analysis (FREE with Ollama)
 
-| Framework | File Patterns | Auto-Detected Directory |
-|-----------|---------------|------------------------|
-| Playwright | `*.spec.ts`, `*.spec.js`, `*.test.ts`, `*.test.js` | `playwright/e2e` |
-| Cypress | `*.cy.ts`, `*.cy.js` | `cypress/e2e` |
-| Generic | Any of the above | `e2e` |
+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!
 
-**Auto-detection priority:**
-1. `playwright/e2e` (if exists)
-2. `cypress/e2e` (if exists)
-3. `e2e` (generic fallback)
-
-No configuration needed for standard project structures!
-
----
+**Example transformation:**
 
-## Configuration (Optional)
-
-Override defaults via **`.am-browserstack-sync.json`** in project root:
-
-```json
-{
-  "e2eDir": "tests/e2e",
-  "csvOutputDir": "tests/csv-output"
-}
-```
-
-Or in **package.json**:
-
-```json
-{
-  "amBrowserstackSync": {
-    "e2eDir": "cypress/e2e",
-    "csvOutputDir": "cypress/csv"
-  }
-}
-```
-
-Or via **environment variables**:
-
-```bash
-PLAYWRIGHT_BROWSERSTACK_E2E_DIR=tests/e2e
-PLAYWRIGHT_BROWSERSTACK_CSV_DIR=tests/csv
+```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/);
+});
 ```
 
----
+**Generated steps:**
 
-## BrowserStack Integration
+| 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
+### Setup Ollama
 
-1. Create a **`.env`** file in your project root (don't commit this!):
+1. Download and install Ollama from [ollama.ai](https://ollama.ai)
 
-```env
-BROWSERSTACK_USERNAME=your_username
-BROWSERSTACK_ACCESS_KEY=your_access_key
-BROWSERSTACK_PROJECT_ID=PR-XXXX
-```
+2. Pull a model (llama3.2 recommended):
+   ```bash
+   ollama pull llama3.2
+   ```
 
-Or use a single API token:
+3. Start Ollama (runs automatically on macOS, or run manually):
+   ```bash
+   ollama serve
+   ```
 
-```env
-BROWSERSTACK_API_TOKEN=your_token
-BROWSERSTACK_PROJECT_ID=PR-XXXX
-```
+4. Run the sync — AI analysis is automatic when Ollama is running!
+   ```bash
+   npx am-browserstack-sync --csv-only
+   ```
 
-2. Get credentials from [BrowserStack Test Management → Settings → API Keys](https://test-management.browserstack.com/settings/api-keys)
-
-3. Find your Project ID in the BrowserStack project URL (e.g., `PR-1234`)
+### Options
 
-### What Gets Synced
+- `--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
 
-For each spec file, the tool:
-- Creates a **folder** in BrowserStack (named after the spec file)
-- Creates **test cases** with:
-  - Title (from test name)
-  - Description
-  - Steps and expected results
-  - State (Active)
-  - Type (Functional)
-  - Automation status (automated)
-  - Tags (framework, spec name, test keywords)
+### Recommended Models
 
-### Idempotent Sync
+| Model | Size | Best for |
+|-------|------|----------|
+| `llama3.2` | 2GB | General purpose, fast (default) |
+| `codellama` | 4GB | Better code understanding |
+| `llama3.2:1b` | 1GB | Fastest, lower quality |
+| `mistral` | 4GB | Good balance |
 
-- **New tests** → Created in BrowserStack
-- **Existing tests** (matched by title or TC-ID tag) → Updated
-- **No duplicates** are created
+**Fallback:** If Ollama is not running, the tool automatically uses regex-based step extraction, which still provides meaningful steps.
 
 ---
 
-## CSV Output
-
-Each spec file generates a CSV with these columns:
+## Config (optional)
 
-| Column | Description |
-|--------|-------------|
-| `test_case_id` | TC-001, TC-002, ... |
-| `title` | Test name |
-| `state` | Active, Draft, etc. |
-| `case_type` | Functional, Regression, etc. |
-| `steps` | Test steps |
-| `expected_results` | Expected outcomes |
-| `jira_issues` | Linked Jira tickets |
-| `automation_status` | automated / manual |
-| `tags` | Framework, functionality tags |
-| `description` | Test description |
-| `spec_file` | Source file name |
+Defaults: e2e dir `playwright/e2e`, CSV dir `playwright/e2e-csv`. For Cypress use e.g. `cypress/e2e`.
 
----
-
-## Programmatic API
+Override via **`.am-browserstack-sync.json`** in project root:
 
-Use in your own scripts:
+```json
+{
+  "e2eDir": "playwright/e2e",
+  "csvOutputDir": "playwright/e2e-csv"
+}
+```
 
-```javascript
-import { runSync } from '@ash-mallick/browserstack-sync';
+Or **package.json**: `"amBrowserstackSync": { "e2eDir": "...", "csvOutputDir": "..." }`  
+Or env: `PLAYWRIGHT_BROWSERSTACK_E2E_DIR`, `PLAYWRIGHT_BROWSERSTACK_CSV_DIR`.
 
-await runSync({
-  cwd: '/path/to/project',
-  csvOnly: false,
-  all: true,
-  // Or specify specific specs:
-  // spec: ['login.spec', 'checkout.spec'],
-});
-```
+---
 
-### Options
+## BrowserStack sync
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `cwd` | string | Project root directory |
-| `csvOnly` | boolean | Skip BrowserStack sync |
-| `all` | boolean | Sync all specs (no prompt) |
-| `spec` | string[] | Specific specs to sync |
-| `e2eDir` | string | Override e2e directory |
-| `csvOutputDir` | string | Override CSV output directory |
+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:**
 
-## Example Project Structure
+1. In project root, create **`.env`** (do not commit):
 
-### Playwright
+   ```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`
 
-```
-my-project/
-├── package.json
-├── .env                    # BrowserStack credentials
-├── playwright/
-│   ├── e2e/               # Your test files
-│   │   ├── login.spec.ts
-│   │   └── checkout.spec.ts
-│   └── e2e-csv/           # Generated CSVs
-│       ├── login.spec.csv
-│       └── checkout.spec.csv
-```
+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`).
 
-### Cypress
+3. **Install Ollama** for AI-powered step analysis (optional but recommended).
 
-```
-my-project/
-├── package.json
-├── .env
-├── cypress/
-│   ├── e2e/               # Your test files
-│   │   ├── login.cy.ts
-│   │   └── cart.cy.ts
-│   └── e2e-csv/           # Generated CSVs
-│       ├── login.cy.csv
-│       └── cart.cy.csv
-```
+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.
 
 ---
 
-## License
-
-MIT
+## 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.
 ---
 
-**Author:** Ashutosh Mallick  
-**npm:** [@ash-mallick/browserstack-sync](https://www.npmjs.com/package/@ash-mallick/browserstack-sync)
+**Author:** Ashutosh Mallick

package/bin/cli.js

@@ -5,9 +5,23 @@
  * 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
+ *   --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
+ *   --no-ai         Disable AI-powered step analysis (use regex extraction only)
+ *   --model=name    Ollama model to use (default: llama3.2). e.g. --model=codellama
+ *
+ * AI Analysis (FREE, Local with Ollama):
+ *   Install Ollama from https://ollama.ai, then:
+ *     ollama pull llama3.2
+ *     ollama serve
+ *
+ *   AI analysis is automatic when Ollama is running! No API key needed.
+ *   The AI will analyze your test code and generate human-readable steps like:
+ *     - "Navigate to /login page"
+ *     - "Enter 'user@test.com' in the Email field"
+ *     - "Click the 'Sign In' button"
+ *     - "Verify URL matches /dashboard"
  */
 
 import { runSync } from '../lib/index.js';
@@ -15,15 +29,31 @@ import { runSync } from '../lib/index.js';
 const argv = process.argv.slice(2);
 const csvOnly = argv.includes('--csv-only');
 const all = argv.includes('--all');
+const noAI = argv.includes('--no-ai');
+
+// Parse --spec=value
 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);
 }
+
+// Parse --model=value
+const modelArg = argv.find((a) => a.startsWith('--model='));
+const model = modelArg ? modelArg.slice('--model='.length).trim() : undefined;
+
+// Parse --cwd value
 const cwd = argv.includes('--cwd') ? argv[argv.indexOf('--cwd') + 1] : process.cwd();
 
-runSync({ cwd, csvOnly, all, spec }).catch((err) => {
+runSync({
+  cwd,
+  csvOnly,
+  all,
+  spec,
+  useAI: !noAI,
+  model,
+}).catch((err) => {
   console.error(err);
   process.exit(1);
 });

package/lib/ai-analyzer.js

@@ -0,0 +1,267 @@
+/**
+ * AI-powered test step analyzer using Ollama (FREE, local).
+ * 
+ * Ollama runs 100% locally on your machine - no data sent to cloud, completely free.
+ * Install Ollama: https://ollama.ai
+ * Then run: ollama pull llama3.2
+ */
+
+import { Ollama } from 'ollama';
+
+const DEFAULT_MODEL = 'llama3.2';
+const OLLAMA_HOST = process.env.OLLAMA_HOST || 'http://localhost:11434';
+
+/**
+ * System prompt for the AI to understand what we want.
+ */
+const SYSTEM_PROMPT = `You are a test automation expert. Your job is to analyze Playwright or Cypress test code and extract human-readable test steps.
+
+For each test, output a JSON array of steps. Each step should have:
+- "step": A clear, human-readable action (e.g., "Navigate to /login page", "Enter 'test@example.com' in the email field")
+- "result": The expected result or assertion for this step (e.g., "Login form is displayed", "Error message 'Invalid credentials' appears")
+
+Rules:
+1. Convert code actions to plain English that a manual tester could follow
+2. For page.goto(url) -> "Navigate to <url>"
+3. For page.fill(selector, value) or getByLabel().fill() -> "Enter '<value>' in the <field name> field"
+4. For page.click() or getByRole().click() -> "Click the '<button/link name>' button/link"
+5. For expect() assertions -> This becomes the "result" of the previous step
+6. If there's no explicit assertion, the result should describe the expected state
+7. Be concise but clear
+8. Group related actions if they form one logical step
+
+Output ONLY valid JSON array, no markdown, no explanation. Example:
+[
+  {"step": "Navigate to /login page", "result": "Login page loads successfully"},
+  {"step": "Enter 'user@test.com' in the Email field", "result": "Email is entered"},
+  {"step": "Enter 'password123' in the Password field", "result": "Password is masked and entered"},
+  {"step": "Click the 'Sign In' button", "result": "User is redirected to /dashboard"}
+]`;
+
+/**
+ * Build the user prompt for AI analysis.
+ */
+function buildUserPrompt(testTitle, testCode) {
+  return `Analyze this Playwright/Cypress test and extract the test steps:
+
+Test Title: ${testTitle}
+
+Test Code:
+\`\`\`
+${testCode}
+\`\`\`
+
+Return a JSON array of steps with "step" and "result" fields.`;
+}
+
+/**
+ * Parse AI response content to extract steps array.
+ */
+function parseAIResponse(content) {
+  if (!content) {
+    throw new Error('Empty response from AI');
+  }
+
+  // Remove markdown code block wrapper if present: ```json ... ``` or ``` ... ```
+  let jsonStr = content.trim();
+  const codeBlockMatch = jsonStr.match(/^```(?:json)?\s*\n?([\s\S]*?)\n?```$/);
+  if (codeBlockMatch) {
+    jsonStr = codeBlockMatch[1].trim();
+  }
+
+  // Also try to extract JSON array from anywhere in the response
+  if (!jsonStr.startsWith('[')) {
+    const arrayMatch = jsonStr.match(/\[[\s\S]*\]/);
+    if (arrayMatch) {
+      jsonStr = arrayMatch[0];
+    }
+  }
+
+  let steps;
+  try {
+    steps = JSON.parse(jsonStr);
+  } catch (parseError) {
+    throw new Error(`Failed to parse AI response as JSON: ${parseError.message}. Response: ${content.slice(0, 200)}`);
+  }
+
+  if (!Array.isArray(steps)) {
+    throw new Error('AI response is not an array');
+  }
+
+  return steps.map((s) => ({
+    step: String(s.step || ''),
+    result: String(s.result || ''),
+  }));
+}
+
+/**
+ * Check if Ollama is running and accessible.
+ */
+export async function checkOllamaConnection() {
+  try {
+    const ollama = new Ollama({ host: OLLAMA_HOST });
+    await ollama.list(); // Simple API call to check connection
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Get list of available Ollama models.
+ */
+export async function listOllamaModels() {
+  try {
+    const ollama = new Ollama({ host: OLLAMA_HOST });
+    const response = await ollama.list();
+    return response.models?.map((m) => m.name) || [];
+  } catch (error) {
+    return [];
+  }
+}
+
+/**
+ * Analyze using Ollama (FREE, local).
+ * Requires Ollama installed: https://ollama.ai
+ * Run: ollama pull llama3.2 (or another model)
+ */
+async function analyzeWithOllama(testTitle, testCode, model) {
+  const ollama = new Ollama({ host: OLLAMA_HOST });
+  const modelName = model || process.env.OLLAMA_MODEL || DEFAULT_MODEL;
+
+  const response = await ollama.chat({
+    model: modelName,
+    messages: [
+      { role: 'system', content: SYSTEM_PROMPT },
+      { role: 'user', content: buildUserPrompt(testTitle, testCode) },
+    ],
+    options: {
+      temperature: 0.2,
+    },
+  });
+
+  return response.message?.content;
+}
+
+/**
+ * Analyze a single test's code and return structured steps using Ollama (FREE, local).
+ *
+ * @param {string} testTitle - The test title
+ * @param {string} testCode - The full test code block
+ * @param {Object} options - { model: string }
+ * @returns {Promise<Array<{step: string, result: string}>>}
+ */
+export async function analyzeTestWithAI(testTitle, testCode, apiKey, options = {}) {
+  const model = options.model || process.env.OLLAMA_MODEL || DEFAULT_MODEL;
+
+  try {
+    const content = await analyzeWithOllama(testTitle, testCode, model);
+    return parseAIResponse(content);
+  } catch (error) {
+    // Provide helpful error messages
+    if (error.message?.includes('ECONNREFUSED') || error.message?.includes('fetch failed')) {
+      console.warn(`  ⚠ Ollama not running. Start it with: ollama serve`);
+    } else if (error.message?.includes('model') && error.message?.includes('not found')) {
+      console.warn(`  ⚠ Model "${model}" not found. Pull it with: ollama pull ${model}`);
+    } else {
+      console.warn(`  ⚠ AI analysis failed for "${testTitle}": ${error.message}`);
+    }
+    return null; // Return null to indicate failure, caller will use fallback
+  }
+}
+
+/**
+ * Fallback: Extract steps using regex patterns (no AI).
+ * Less accurate but works without Ollama.
+ */
+export function extractStepsWithRegex(testCode, isCypress = false) {
+  const steps = [];
+
+  // Common Playwright patterns
+  const patterns = [
+    // page.goto or cy.visit
+    {
+      regex: /(?:page\.goto|cy\.visit)\s*\(\s*['"`]([^'"`]+)['"`]/gi,
+      format: (match) => ({ step: `Navigate to ${match[1]}`, result: 'Page loads successfully' }),
+    },
+    // page.fill or cy.get().type() with getByLabel
+    {
+      regex: /(?:getByLabel|getByPlaceholder)\s*\([^)]+\)\.fill\s*\(\s*['"`]([^'"`]+)['"`]/gi,
+      format: (match) => {
+        const labelMatch = match.input.match(/(?:getByLabel|getByPlaceholder)\s*\(\s*['"`/]([^'"`/]+)/i);
+        const label = labelMatch ? labelMatch[1].replace(/\\?\/i$/, '') : 'field';
+        return { step: `Enter '${match[1]}' in the ${label} field`, result: 'Value is entered' };
+      },
+    },
+    // page.click or getByRole().click()
+    {
+      regex: /getByRole\s*\(\s*['"`]([^'"`]+)['"`]\s*,\s*\{[^}]*name:\s*['"`/]([^'"`/]+)/gi,
+      format: (match) => ({ step: `Click the '${match[2].replace(/\\?\/i$/, '')}' ${match[1]}`, result: `${match[1]} is clicked` }),
+    },
+    // expect toBeVisible
+    {
+      regex: /expect\s*\([^)]+\)\.toBeVisible\s*\(\s*\)/gi,
+      format: () => ({ step: 'Verify element is visible', result: 'Element is visible on the page' }),
+    },
+    // expect toHaveURL
+    {
+      regex: /expect\s*\([^)]+\)\.toHaveURL\s*\(\s*['"`/]([^'"`/]+)/gi,
+      format: (match) => ({ step: 'Verify URL', result: `URL matches ${match[1]}` }),
+    },
+    // expect toHaveText or toContainText
+    {
+      regex: /expect\s*\([^)]+\)\.(?:toHaveText|toContainText)\s*\(\s*['"`/]([^'"`/]+)/gi,
+      format: (match) => ({ step: 'Verify text content', result: `Text '${match[1]}' is displayed` }),
+    },
+    // cy.get().should()
+    {
+      regex: /cy\.get\s*\([^)]+\)\.should\s*\(\s*['"`]([^'"`]+)['"`]/gi,
+      format: (match) => ({ step: 'Verify element state', result: `Element should ${match[1]}` }),
+    },
+  ];
+
+  for (const { regex, format } of patterns) {
+    let match;
+    regex.lastIndex = 0; // Reset regex state
+    while ((match = regex.exec(testCode)) !== null) {
+      try {
+        const step = format(match);
+        if (step && step.step) {
+          steps.push(step);
+        }
+      } catch (_) {
+        // Skip malformed matches
+      }
+    }
+  }
+
+  // If no steps extracted, provide a generic one
+  if (steps.length === 0) {
+    const fw = isCypress ? 'Cypress' : 'Playwright';
+    steps.push({
+      step: `Execute ${fw} automated test`,
+      result: 'Test passes with all assertions verified',
+    });
+  }
+
+  return steps;
+}
+
+/**
+ * Check if AI analysis is available (Ollama is running).
+ */
+export async function isAIAvailable() {
+  return await checkOllamaConnection();
+}
+
+/**
+ * Get AI configuration.
+ * @returns {{ provider: string, model: string }}
+ */
+export function getAIConfig(env) {
+  return {
+    provider: 'ollama',
+    apiKey: null,
+    model: env.OLLAMA_MODEL || DEFAULT_MODEL,
+  };
+}

package/lib/config.js

@@ -11,37 +11,19 @@ const CONFIG_FILES = [
   '.config/am-browserstack-sync.json',
 ];
 
-/**
- * Auto-detect e2e directory based on common framework structures.
- * Checks for existence in order: playwright/e2e, cypress/e2e, then fallback.
- */
-function detectE2eDir(resolvedCwd) {
-  const candidates = [
-    { e2eDir: 'playwright/e2e', csvOutputDir: 'playwright/e2e-csv' },
-    { e2eDir: 'cypress/e2e', csvOutputDir: 'cypress/e2e-csv' },
-    { e2eDir: 'e2e', csvOutputDir: 'e2e-csv' },  // Generic fallback
-  ];
-  for (const candidate of candidates) {
-    const fullPath = path.join(resolvedCwd, candidate.e2eDir);
-    if (fs.existsSync(fullPath)) {
-      return candidate;
-    }
-  }
-  // Default to playwright if nothing found (user will see "directory not found" error)
-  return { e2eDir: 'playwright/e2e', csvOutputDir: 'playwright/e2e-csv' };
-}
+const DEFAULTS = {
+  e2eDir: 'playwright/e2e',
+  csvOutputDir: 'playwright/e2e-csv',
+};
 
 /**
- * Load config from cwd: env > config file > package.json field > auto-detect.
+ * 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());
-  
-  // Auto-detect based on existing directory structure
-  const detected = detectE2eDir(resolvedCwd);
-  let e2eDir = detected.e2eDir;
-  let csvOutputDir = detected.csvOutputDir;
+  let e2eDir = DEFAULTS.e2eDir;
+  let csvOutputDir = DEFAULTS.csvOutputDir;
 
   // package.json field
   const pkgPath = path.join(resolvedCwd, 'package.json');

package/lib/enrich.js

@@ -1,8 +1,16 @@
 /**
  * Enrich test cases with state, type, steps, tags, description, etc.
  * Supports Playwright and Cypress; infer tags from spec name + title.
+ * Supports AI-powered step extraction using Ollama (FREE, local).
  */
 
+import {
+  analyzeTestWithAI,
+  extractStepsWithRegex,
+  getAIConfig,
+  checkOllamaConnection,
+} from './ai-analyzer.js';
+
 const DEFAULT_STATE = 'Active';
 const DEFAULT_CASE_TYPE = 'Functional';
 const DEFAULT_AUTOMATION_STATUS = 'automated';
@@ -34,16 +42,31 @@ function inferTags(specBaseName, title, isCypress) {
 
 /**
  * Enrich a single case with state, case_type, steps, expected_results, jira_issues, automation_status, tags, description.
+ * @param {Object} case_ - Test case with id, title, code
+ * @param {string} specBaseName - Base name of spec file
+ * @param {boolean} isCypress - Whether this is a Cypress test
+ * @param {Array} aiSteps - AI-generated steps (if available)
  */
-export function enrichCase(case_, specBaseName, isCypress = false) {
+export function enrichCase(case_, specBaseName, isCypress = false, aiSteps = null) {
   const title = case_.title || '';
   const id = case_.id || '';
+  const code = case_.code || '';
   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(' ');
+
+  // Determine steps: AI steps > regex-extracted steps > default
+  let steps;
+  if (aiSteps && aiSteps.length > 0) {
+    steps = aiSteps;
+  } else if (code) {
+    // Try regex-based extraction from code
+    steps = extractStepsWithRegex(code, isCypress);
+  } else {
+    // Fallback to generic step
+    steps = [{ step: fw.step, result: DEFAULT_EXPECTED_RESULT }];
+  }
+
+  const expectedResults = case_.expected_results ?? steps.map((s) => s.result).filter(Boolean).join(' | ');
   const description = case_.description ?? `${fw.desc}. ID: ${id}. ${title}`;
 
   return {
@@ -62,12 +85,74 @@ export function enrichCase(case_, specBaseName, isCypress = false) {
 }
 
 /**
- * Enrich all cases in specsMap. Mutates cases in place; returns specsMap.
+ * Enrich all cases in specsMap (synchronous, no AI).
+ * Use this when AI is not available or not desired.
  */
 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));
+    data.cases = data.cases.map((c) => enrichCase(c, baseName, isCypress, null));
+  }
+  return specsMap;
+}
+
+/**
+ * Enrich all cases in specsMap with AI-powered step analysis using Ollama.
+ * Falls back to regex extraction if Ollama is not running.
+ *
+ * Ollama runs 100% locally - no data sent to cloud, completely free.
+ * Install: https://ollama.ai
+ * Then: ollama pull llama3.2
+ *
+ * @param {Map} specsMap - Map of spec name -> { specFile, cases, isCypress }
+ * @param {Object} options - { useAI: boolean, model: string }
+ */
+export async function enrichSpecsMapWithAI(specsMap, options = {}) {
+  const wantsAI = options.useAI !== false;
+  const aiConfig = getAIConfig(process.env);
+  const model = options.model || aiConfig.model;
+
+  // Check if Ollama is running
+  let ollamaAvailable = false;
+  if (wantsAI) {
+    ollamaAvailable = await checkOllamaConnection();
   }
+
+  if (wantsAI && ollamaAvailable) {
+    console.log(`\n🦙 Ollama (FREE, local) - analyzing test steps (model: ${model})`);
+  } else if (wantsAI && !ollamaAvailable) {
+    console.log('\n📝 Using regex-based step extraction');
+    console.log('');
+    console.log('   💡 For AI-powered step analysis (FREE, runs locally):');
+    console.log('      1. Download Ollama from https://ollama.ai');
+    console.log('      2. Run: ollama pull llama3.2');
+    console.log('      3. Start: ollama serve');
+    console.log('');
+  } else {
+    console.log('\n📝 Using regex-based step extraction (AI disabled with --no-ai)');
+  }
+
+  for (const [baseName, data] of specsMap) {
+    const isCypress = data.isCypress === true;
+
+    if (wantsAI && ollamaAvailable) {
+      // Analyze each test with Ollama
+      for (let i = 0; i < data.cases.length; i++) {
+        const testCase = data.cases[i];
+        let aiSteps = null;
+
+        if (testCase.code) {
+          console.log(`  Analyzing: ${testCase.title}...`);
+          aiSteps = await analyzeTestWithAI(testCase.title, testCase.code, null, { model });
+        }
+
+        data.cases[i] = enrichCase(testCase, baseName, isCypress, aiSteps);
+      }
+    } else {
+      // Fallback: regex extraction
+      data.cases = data.cases.map((c) => enrichCase(c, baseName, isCypress, null));
+    }
+  }
+
   return specsMap;
 }

package/lib/index.js

@@ -1,7 +1,7 @@
 import dotenv from 'dotenv';
 import path from 'path';
 import { analyzeSpecs } from './parser.js';
-import { enrichSpecsMap } from './enrich.js';
+import { enrichSpecsMap, enrichSpecsMapWithAI } from './enrich.js';
 import { writeCsvFiles } from './csv.js';
 import { syncToBrowserStack } from './browserstack.js';
 import { loadConfig, getBrowserStackEnv } from './config.js';
@@ -18,6 +18,8 @@ import { promptSpecSelection } from './prompt.js';
  * @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)
+ * @param {boolean} [options.useAI] - If true, use AI to analyze test steps (requires OPENAI_API_KEY)
+ * @param {string} [options.model] - OpenAI model to use (default: gpt-4o-mini)
  */
 export async function runSync(options = {}) {
   const config = loadConfig(options.cwd);
@@ -28,13 +30,19 @@ export async function runSync(options = {}) {
   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;
+  const useAI = options.useAI !== false; // Default to true (use AI if key available)
 
   let specsMap = analyzeSpecs(e2eDir);
   if (specsMap.size === 0) {
     console.log('No spec files found in', e2eDir);
     return;
   }
-  enrichSpecsMap(specsMap);
+
+  // Enrich with AI-powered step analysis (falls back to regex if no API key)
+  await enrichSpecsMapWithAI(specsMap, {
+    useAI,
+    model: options.model,
+  });
 
   if (!csvOnly) {
     if (options.all) {

package/lib/parser.js

@@ -21,13 +21,83 @@ export function extractTestTitles(content) {
   return titles;
 }
 
+/**
+ * Extract test blocks with their full code body.
+ * Returns array of { title: string, code: string, startLine: number, endLine: number }
+ */
+export function extractTestBlocks(content) {
+  const tests = [];
+  const lines = content.split('\n');
+
+  // Regex to match start of a test: test('title', async ({ page }) => {
+  // Captures: 1=test/it, 2=title (single/double quote), 3=title (backtick)
+  const testStartRegex = /\b(test|it)\s*(?:\.\s*(?:only|skip))?\s*\(\s*(?:['"]([^'"]*)['"]\s*|`([^`]*)`\s*)/;
+
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const match = testStartRegex.exec(line);
+
+    if (match && !line.includes('describe')) {
+      const title = (match[2] || match[3] || '').trim();
+      if (!title) {
+        i++;
+        continue;
+      }
+
+      // Find the opening brace of the test function
+      let braceCount = 0;
+      let foundOpening = false;
+      let startLine = i;
+      let codeLines = [];
+
+      // Scan from this line to find the complete test block
+      for (let j = i; j < lines.length; j++) {
+        const currentLine = lines[j];
+        codeLines.push(currentLine);
+
+        // Count braces
+        for (const char of currentLine) {
+          if (char === '{') {
+            braceCount++;
+            foundOpening = true;
+          } else if (char === '}') {
+            braceCount--;
+          }
+        }
+
+        // If we found the opening brace and now braces are balanced, we found the end
+        if (foundOpening && braceCount === 0) {
+          tests.push({
+            title,
+            code: codeLines.join('\n'),
+            startLine: startLine + 1, // 1-indexed
+            endLine: j + 1,
+          });
+          i = j + 1;
+          break;
+        }
+      }
+
+      // If we didn't find balanced braces, just move to next line
+      if (braceCount !== 0) {
+        i++;
+      }
+    } else {
+      i++;
+    }
+  }
+
+  return tests;
+}
+
 /** 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 }> }>
+ * Returns Map<specBasename, { specFile, fileContent, cases: Array<{ id, title, code }> }>
  */
 export function analyzeSpecs(e2eDir) {
   if (!fs.existsSync(e2eDir)) {
@@ -38,13 +108,38 @@ export function analyzeSpecs(e2eDir) {
   for (const file of files) {
     const filePath = path.join(e2eDir, file);
     const content = fs.readFileSync(filePath, 'utf-8');
-    const titles = extractTestTitles(content);
+    const isCypress = /\.cy\.(ts|js)$/i.test(file);
+
+    // Extract full test blocks with code
+    const testBlocks = extractTestBlocks(content);
+
     const baseName = path.basename(file, path.extname(file));
-    const cases = titles.map((title, index) => ({
+    const cases = testBlocks.map((block, index) => ({
       id: `TC-${String(index + 1).padStart(3, '0')}`,
-      title: title.replace(/^\s*TC-\d+\s*[-–]\s*/i, '').trim() || title,
+      title: block.title.replace(/^\s*TC-\d+\s*[-–]\s*/i, '').trim() || block.title,
+      code: block.code, // Full test code for AI analysis
+      startLine: block.startLine,
+      endLine: block.endLine,
     }));
-    results.set(baseName, { specFile: file, cases, isCypress: /\.cy\.(ts|js)$/i.test(file) });
+
+    // Fallback: if extractTestBlocks found nothing, use extractTestTitles
+    if (cases.length === 0) {
+      const titles = extractTestTitles(content);
+      titles.forEach((title, index) => {
+        cases.push({
+          id: `TC-${String(index + 1).padStart(3, '0')}`,
+          title: title.replace(/^\s*TC-\d+\s*[-–]\s*/i, '').trim() || title,
+          code: '', // No code available
+        });
+      });
+    }
+
+    results.set(baseName, {
+      specFile: file,
+      fileContent: content, // Keep full file content for reference
+      cases,
+      isCypress,
+    });
   }
   return results;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ash-mallick/browserstack-sync",
-  "version": "1.0.6",
-  "description": "Sync Playwright & Cypress e2e specs to CSV and BrowserStack Test Management (one folder per spec)",
+  "version": "1.1.2",
+  "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",
   "main": "lib/index.js",
@@ -28,6 +28,12 @@
     "e2e",
     "test-management",
     "sync",
+    "ai",
+    "ollama",
+    "llama",
+    "test-steps",
+    "free",
+    "local",
     "ash-mallick"
   ],
   "license": "MIT",
@@ -36,13 +42,13 @@
     "url": ""
   },
   "dependencies": {
-    "dotenv": "^16.4.5"
+    "dotenv": "^16.4.5",
+    "ollama": "^0.6.3"
   },
   "devDependencies": {
     "@playwright/test": "^1.49.0",
     "playwright": "^1.49.0"
   },
-  "peerDependencies": {},
   "peerDependenciesMeta": {},
   "engines": {
     "node": ">=18"