qa-intelligence 1.1.3 → 1.1.4

package/README.md

@@ -12,158 +12,49 @@ The intelligence engine for Playwright CI pipelines — install it into any proj
 
 Use it **without the framework template** — install the package into your existing app repo.
 
-**Recommended layout:** create a `playwright/` subfolder at the repo root and keep all E2E tooling there, separate from your main app code. Full step-by-step guide (folder layout, `Dockerfile`, CI path changes): **[qa-intelligence-framework README](https://github.com/ardithaqi/qa-intelligence-framework#add-to-an-existing-project-npm-package)**.
 
 ---
 
-## Install
+## Quick start
 
-Run inside your `playwright/` folder (or your Playwright project root if tests already live there):
+Run from your **repo root** (not inside `playwright/`). You do **not** need a `playwright/` folder beforehand — `init` creates it.
 
 ```bash
+npx qa-intelligence init
 cd playwright
-npm install qa-intelligence @playwright/test
+cp .env.example .env   # set BASE_URL
+npm install            # installs qa-intelligence + @playwright/test (see playwright/package.json)
+npx playwright install
 ```
 
-npm automatically installs peer dependencies (`typescript`, `@types/node`) — no separate dev-deps step needed.
+`init` scaffolds:
 
----
-
-## Setup
-
-All paths below are relative to `playwright/` when using the recommended subfolder layout.
-
-### 1. Environment (`.env`)
-
-```env
-BASE_URL=https://your-app.example.com
-HEADLESS=true
-PW_WORKERS=2
-PW_RETRIES=1
-```
+- `playwright/` — `.env.example`, `package.json`, `tsconfig.json`, `playwright.config.ts`, example test
+- `.github/workflows/qa-intelligence.yml` — PR diff, history, and comment (skip with `--no-ci`)
 
-### 2. `tsconfig.json` (TypeScript projects)
-
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "Node16",
-    "moduleResolution": "Node16",
-    "strict": true,
-    "esModuleInterop": true,
-    "types": ["node"],
-    "skipLibCheck": true
-  },
-  "include": ["tests/**/*", "playwright.config.ts"]
-}
-```
-
-> `module` and `moduleResolution` must both be `"Node16"` so TypeScript resolves the package `exports` map.
+**Then:** add `OPENAI_API_KEY` to GitHub secrets and set `BASE_URL` in the workflow file.
 
-### 3. `playwright.config.ts`
-
-```ts
-import { defineConfig } from "@playwright/test";
-import { env } from "qa-intelligence/config/env";
-
-export default defineConfig({
-  testDir: "./tests",
-  retries: env.PW_RETRIES,
-  workers: env.PW_WORKERS,
-  globalSetup: require.resolve("qa-intelligence/playwright/globalSetup"),
-  globalTeardown: require.resolve("qa-intelligence/playwright/globalTeardown"),
-  use: {
-    baseURL: env.BASE_URL,
-    headless: env.HEADLESS,
-    trace: "on-first-retry",
-    screenshot: "only-on-failure",
-    video: "retain-on-failure",
-  },
-});
-```
-
-### 4. Write tests
-
-**Important** — always import `test` and `expect` from the package:
+**Tests** — always import from the package, not Playwright directly:
 
 ```ts
 import { test, expect } from "qa-intelligence/playwright";
 ```
 
-**Not** directly from Playwright:
-
-```ts
-// ❌ No AI artifacts, no PR diff, no flaky detection
-import { test, expect } from "@playwright/test";
-```
-
-Using `qa-intelligence/playwright` enables:
-
-- AI failure analysis (`meta.json` → `ai.txt`)
-- Artifact generation on failure
-- Flaky detection (retry-aware)
-- CI diff intelligence and PR comments
-
-Example test:
-
-```ts
-import { test, expect } from "qa-intelligence/playwright";
-
-test("user can login", async ({ page }) => {
-  await page.goto("/");
-  await expect(page).toHaveTitle(/My App/);
-});
-```
+### `init` options
 
-> **Using the [framework template](https://github.com/ardithaqi/qa-intelligence-framework)?** Import from local `src/core/baseTest` instead — same hooks, different path for that repo layout.
+By default, `init` skips any file that already exists so it won't overwrite your work.
 
-Optional helpers:
+| Flag | What it does |
+|------|----------------|
+| `--no-ci` | Only scaffold `playwright/` (config, env, tests). Does **not** create `.github/workflows/qa-intelligence.yml`. Use this if you already have CI or use GitLab/Jenkins. |
+| `--force` | Overwrite existing scaffold files. Use when re-running `init` and you want a fresh copy from the templates. |
 
-```ts
-import { step } from "qa-intelligence/playwright/steps";
-import { BasePage } from "qa-intelligence/playwright/basePage";
+```bash
+npx qa-intelligence init              # playwright/ + GitHub workflow
+npx qa-intelligence init --no-ci      # playwright/ only
+npx qa-intelligence init --force      # overwrite files that already exist
 ```
 
-### 5. What you provide
-
-| You write | Package provides |
-|-----------|------------------|
-| `playwright/tests/` | Test hooks, artifact capture |
-| `playwright/.env` | Env validation |
-| `playwright/playwright.config.ts` | `globalSetup`, `globalTeardown`, AI teardown |
-| `playwright/Dockerfile` | — (copy from [framework](https://github.com/ardithaqi/qa-intelligence-framework/blob/master/Dockerfile)) |
-| `.github/workflows/ci.yml` | `qa-intelligence-diff`, `qa-intelligence-history`, `qa-intelligence-comment` |
-| Page objects (optional) | `BasePage`, `step()` |
-
----
-
-## CI setup (GitHub Actions)
-
-Copy [`.github/workflows/ci.yml`](https://github.com/ardithaqi/qa-intelligence-framework/blob/master/.github/workflows/ci.yml) and [`Dockerfile`](https://github.com/ardithaqi/qa-intelligence-framework/blob/master/Dockerfile) from the framework repo.
-
-When using the `playwright/` subfolder layout, apply the CI path changes documented in the [framework adoption guide](https://github.com/ardithaqi/qa-intelligence-framework#add-to-an-existing-project-npm-package) (`working-directory: playwright`, artifact paths, etc.).
-
-The workflow includes:
-
-- Docker test execution
-- Artifact upload on every run
-- Baseline download from `main` on pull requests
-- `qa-intelligence-diff`, `qa-intelligence-history`, `qa-intelligence-comment`
-- PR blocking on new non-flaky failures
-
-Then update:
-
-- `BASE_URL` in the `docker run` step
-- GitHub secrets (see below)
-
-### Required GitHub secrets
-
-- `OPENAI_API_KEY` — enables AI failure analysis in teardown
-- `TEST_USERNAME` / `TEST_PASSWORD` — if your tests need credentials
-
-Set `AI_ANALYSIS=true` in CI when running tests inside Docker.
-
 ---
 
 ## PR behavior
@@ -177,20 +68,21 @@ Set `AI_ANALYSIS=true` in CI when running tests inside Docker.
 
 ---
 
-## CLI tools
+## CLI
 
 | Command | Purpose |
 |---------|---------|
+| `qa-intelligence init` | Scaffold project files |
 | `qa-intelligence-diff` | Compare baseline vs current failures |
-| `qa-intelligence-history` | Add recurrence tracking |
-| `qa-intelligence-comment` | Post/update PR summary comment |
+| `qa-intelligence-history` | Recurrence tracking |
+| `qa-intelligence-comment` | Post/update PR summary |
 
 ---
 
 ## Package exports
 
-| Import path | What it gives you |
-|-------------|-------------------|
+| Import | What you get |
+|--------|--------------|
 | `qa-intelligence/playwright` | `test`, `expect`, `env` |
 | `qa-intelligence/playwright/globalSetup` | Artifact run setup |
 | `qa-intelligence/playwright/globalTeardown` | AI failure analysis |
@@ -200,19 +92,11 @@ Set `AI_ANALYSIS=true` in CI when running tests inside Docker.
 
 ---
 
-## Alternative: use the full template
-
-If you prefer a ready-made project with examples, Docker, and CI pre-wired:
-
-**[qa-intelligence-framework](https://github.com/ardithaqi/qa-intelligence-framework)** — click "Use this template".
-
-The template uses this package under the hood.
-
----
+## Full template (optional)
 
-## Author
+Prefer a ready-made project with Docker, example tests, and CI pre-wired? Use the **[qa-intelligence-framework](https://github.com/ardithaqi/qa-intelligence-framework)** template — click "Use this template".
 
-Built as the intelligence engine behind QA automation — Playwright hooks, AI failure analysis, and PR-aware CI. If you use this package, consider leaving a star or linking back—contributions are welcome.
+For adding to an existing repo with a `playwright/` subfolder, see the [framework adoption guide](https://github.com/ardithaqi/qa-intelligence-framework#add-to-an-existing-project-npm-package) (`Dockerfile`, CI path changes).
 
 ---
 

package/dist/cli/index.js

@@ -1,5 +1,38 @@
 #!/usr/bin/env node
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 const child_process_1 = require("child_process");
 function getArg(name) {
@@ -9,6 +42,12 @@ function getArg(name) {
     return process.argv[idx + 1];
 }
 async function main() {
+    const subcommand = process.argv[2];
+    if (subcommand === "init") {
+        const { main: runInit } = await Promise.resolve().then(() => __importStar(require("./init")));
+        await runInit();
+        return;
+    }
     const baseline = getArg("baseline") ?? "baseline-artifacts";
     const current = getArg("current") ?? "artifacts";
     const repo = getArg("repo");

package/dist/cli/init.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+export declare function runInit(options?: {
+    root?: string;
+    force?: boolean;
+    withCi?: boolean;
+}): {
+    written: string[];
+    skipped: string[];
+};
+export declare function main(): Promise<void>;

package/dist/cli/init.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInit = runInit;
+exports.main = main;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const PLAYWRIGHT_SCAFFOLD = [
+    { template: "playwright/.env.example", dest: "playwright/.env.example" },
+    { template: "playwright/tsconfig.json", dest: "playwright/tsconfig.json" },
+    {
+        template: "playwright/playwright.config.ts",
+        dest: "playwright/playwright.config.ts",
+    },
+    { template: "playwright/package.json", dest: "playwright/package.json" },
+    {
+        template: "playwright/tests/example.spec.ts",
+        dest: "playwright/tests/example.spec.ts",
+    },
+];
+const CI_SCAFFOLD = [
+    {
+        template: "github/workflows/qa-intelligence.yml",
+        dest: ".github/workflows/qa-intelligence.yml",
+    },
+];
+function hasFlag(name) {
+    return process.argv.includes(`--${name}`);
+}
+function templatesDir() {
+    return path_1.default.join(__dirname, "..", "..", "templates");
+}
+function copyScaffold(root, entries, force) {
+    const written = [];
+    const skipped = [];
+    const sourceRoot = templatesDir();
+    for (const { template, dest } of entries) {
+        const source = path_1.default.join(sourceRoot, template);
+        const target = path_1.default.join(root, dest);
+        if (!fs_1.default.existsSync(source)) {
+            throw new Error(`Missing template: ${template}`);
+        }
+        if (fs_1.default.existsSync(target) && !force) {
+            skipped.push(dest);
+            continue;
+        }
+        fs_1.default.mkdirSync(path_1.default.dirname(target), { recursive: true });
+        fs_1.default.copyFileSync(source, target);
+        written.push(dest);
+    }
+    return { written, skipped };
+}
+function runInit(options) {
+    const root = path_1.default.resolve(options?.root ?? process.cwd());
+    const force = options?.force ?? false;
+    const withCi = options?.withCi ?? true;
+    const entries = [...PLAYWRIGHT_SCAFFOLD];
+    if (withCi) {
+        entries.push(...CI_SCAFFOLD);
+    }
+    return copyScaffold(root, entries, force);
+}
+async function main() {
+    const force = hasFlag("force");
+    const noCi = hasFlag("no-ci");
+    console.log("Scaffolding qa-intelligence in:", process.cwd());
+    const { written, skipped } = runInit({
+        force,
+        withCi: !noCi,
+    });
+    for (const file of written) {
+        console.log(`  created ${file}`);
+    }
+    for (const file of skipped) {
+        console.log(`  skipped ${file} (exists — use --force to overwrite)`);
+    }
+    if (written.length === 0 && skipped.length > 0) {
+        console.log("\nNothing new was written.");
+        return;
+    }
+    console.log("\nNext steps:");
+    console.log("  1. cd playwright && cp .env.example .env  # set BASE_URL");
+    console.log("  2. cd playwright && npm install");
+    console.log("  3. npx playwright install");
+    console.log("  4. Add OPENAI_API_KEY to GitHub repo secrets (for CI)");
+    if (!noCi) {
+        console.log("  5. Update BASE_URL in .github/workflows/qa-intelligence.yml");
+    }
+    console.log("  6. Write tests — import from qa-intelligence/playwright");
+}
+if (require.main === module) {
+    main().catch((e) => {
+        console.error(e);
+        process.exit(1);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "qa-intelligence",
-    "version": "1.1.3",
+    "version": "1.1.4",
     "engines": {
         "node": ">=18"
     },
@@ -57,6 +57,7 @@
     },
     "bin": {
         "qa-intelligence": "dist/cli/index.js",
+        "qa-intelligence-init": "dist/cli/init.js",
         "qa-intelligence-diff": "dist/cli/diff.js",
         "qa-intelligence-history": "dist/cli/history.js",
         "qa-intelligence-comment": "dist/cli/postComment.js"
@@ -82,6 +83,7 @@
         "typescript": "^5.9.3"
     },
     "files": [
-        "dist"
+        "dist",
+        "templates"
     ]
 }

package/templates/github/workflows/qa-intelligence.yml

@@ -0,0 +1,129 @@
+name: QA Intelligence CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+permissions:
+  contents: read
+  actions: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: playwright
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Clean artifacts
+        if: always()
+        run: rm -rf artifacts
+
+      - name: Run Playwright tests
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          AI_ANALYSIS: true
+          BASE_URL: https://your-app.example.com
+          HEADLESS: true
+          PW_WORKERS: 2
+          PW_RETRIES: 1
+          TEST_USERNAME: ${{ secrets.TEST_USERNAME }}
+          TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
+        run: |
+          set +e
+          npx playwright test
+          EXIT=$?
+          if [ "$GITHUB_EVENT_NAME" = "pull_request" ]; then exit 0; fi
+          exit $EXIT
+
+      - name: Upload Playwright HTML report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: playwright/playwright-report/
+
+      - name: Upload AI failure artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: ai-failure-artifacts
+          path: playwright/artifacts/
+
+      - name: Parse AI failure reports
+        if: always()
+        run: |
+          echo "Parsing AI failure reports..."
+          if [ -d "artifacts" ]; then
+            find artifacts -name "ai.txt" | while read file; do
+              echo "-----"
+              echo "File: $file"
+              json=$(awk '/^{/{flag=1} flag' "$file")
+              echo "$json" | jq .
+            done
+          else
+            echo "No artifacts directory found."
+          fi
+
+      - name: Download baseline artifacts from main
+        if: always() && github.event_name == 'pull_request'
+        uses: dawidd6/action-download-artifact@v6
+        with:
+          workflow: qa-intelligence.yml
+          branch: ${{ github.base_ref }}
+          name: ai-failure-artifacts
+          path: baseline-artifacts
+          if_no_artifact_found: warn
+
+      - name: Debug baseline contents
+        if: always() && github.event_name == 'pull_request'
+        run: |
+          echo "Baseline:"
+          ls -la ../baseline-artifacts || true
+          echo "Current:"
+          ls -la artifacts || true
+
+      - name: Compute failure diff
+        if: always() && github.event_name == 'pull_request'
+        run: npx qa-intelligence-diff --baseline ../baseline-artifacts --current artifacts
+
+      - name: Restore failure history cache
+        if: always() && github.event_name == 'pull_request'
+        uses: actions/cache@v4
+        with:
+          path: playwright/.cache
+          key: failure-history-${{ github.repository }}-${{ github.sha }}
+          restore-keys: |
+            failure-history-${{ github.repository }}-
+
+      - name: Update failure history (recurrence)
+        if: always() && github.event_name == 'pull_request'
+        run: npx qa-intelligence-history
+
+      - name: Comment PR with AI summary
+        if: always() && github.event_name == 'pull_request'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          npx qa-intelligence-comment \
+            --diff failure-diff.json \
+            --repo ${{ github.repository }} \
+            --pr ${{ github.event.pull_request.number }} \
+            --token $GITHUB_TOKEN

package/templates/playwright/.env.example

@@ -0,0 +1,8 @@
+BASE_URL=https://your-app.example.com
+HEADLESS=true
+PW_WORKERS=2
+PW_RETRIES=1
+
+# Optional — enable AI failure analysis in teardown
+# OPENAI_API_KEY=sk-...
+# AI_ANALYSIS=true

package/templates/playwright/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "e2e-tests",
+  "private": true,
+  "scripts": {
+    "test": "playwright test"
+  },
+  "dependencies": {
+    "@playwright/test": "^1.58.0",
+    "qa-intelligence": "^1.1.4"
+  }
+}

package/templates/playwright/playwright.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from "@playwright/test";
+import { env } from "qa-intelligence/config/env";
+
+export default defineConfig({
+  testDir: "./tests",
+  retries: env.PW_RETRIES,
+  workers: env.PW_WORKERS,
+  globalSetup: require.resolve("qa-intelligence/playwright/globalSetup"),
+  globalTeardown: require.resolve("qa-intelligence/playwright/globalTeardown"),
+  use: {
+    baseURL: env.BASE_URL,
+    headless: env.HEADLESS,
+    trace: "on-first-retry",
+    screenshot: "only-on-failure",
+    video: "retain-on-failure",
+  },
+  reporter: [["html", { open: "never" }]],
+});

package/templates/playwright/tests/example.spec.ts

@@ -0,0 +1,6 @@
+import { test, expect } from "qa-intelligence/playwright";
+
+test("example — replace with your first test", async ({ page }) => {
+  await page.goto("/");
+  await expect(page).toHaveTitle(/.*/);
+});

package/templates/playwright/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "strict": true,
+    "esModuleInterop": true,
+    "types": ["node"],
+    "skipLibCheck": true
+  },
+  "include": ["tests/**/*", "playwright.config.ts"]
+}