@cementic/cementic-test 0.2.3

package/README.md

@@ -0,0 +1,625 @@
+**README.md** for CementicTest (CT).
+
+# CementicTest CLI (v0.2)
+
+Turn messy human test ideas into runnable Playwright tests — while staying 100% compatible with classic Playwright + POM.
+
+## Installation
+
+```bash
+# Run directly (no install needed)
+npx @cementic/cementic-test new my-app
+
+# Or install globally
+npm install -g @cementic/cementic-test
+```
+
+## Quick Start
+
+```bash
+# 1. Scaffold a new project
+ct new "Demo"
+
+# 2. Generate test cases with AI
+cd Demo
+ct tc --ai --feature "Login" --count 3
+
+# 3. Generate & Run
+ct flow
+```
+
+---
+
+# 🧪 CementicTest (CT)
+
+### **AI-Assisted Playwright Automation — From Test Cases to POM Test Suites in Minutes**
+
+CementicTest (CT) is a CLI tool that turns **written or AI-generated test cases** into a complete, production-ready **Playwright + Page Object Model** automation framework.
+
+CT can:
+
+* Scaffold new Playwright projects
+* Scrape real URLs for UI context
+* Generate test cases using LLMs (Bring Your Own API Key)
+* Normalize test cases
+* Generate full Playwright tests using POM standards
+* Run everything instantly via `ct test`
+* Enhance existing Playwright projects
+* Allow optional migration from raw PW → CT-powered PW
+
+CT removes boilerplate, enforces good practices, and massively accelerates setup and test authoring.
+
+---
+
+# ⭐️ Features Overview
+
+## ✅ **1. Project Initialization (POM-ready workspace)**
+
+`ct new "<projectName>"` creates a complete, ready-to-run test project:
+
+```
+pages/
+tests/
+utils/
+test-data/
+cases/
+.cementic/
+  normalized/
+playwright.config.ts
+```
+
+Includes:
+
+* Installed Playwright & browsers
+* Sample login page
+* Sample test
+* Opinionated project structure
+* POM-first architecture layout
+
+---
+
+## ✅ **2. AI-powered Test Case Writer**
+
+Using your own LLM API key (`CT_LLM_API_KEY`, `OPENAI_API_KEY`, etc.):
+
+* Scrapes page content
+* Extracts headings, buttons, inputs, metadata
+* Sends prompt + test spec to LLM
+* Generates structured Markdown test cases:
+
+```
+# AUTH-001 — Valid Login @smoke @auth
+## Steps
+1. Navigate to /login
+...
+## Expected
+- Dashboard loads
+- User profile visible
+```
+
+Supports:
+
+### **Interactive writing**
+
+```
+ct tc
+```
+
+### **AI-writing**
+
+```
+ct tc --ai
+```
+
+### **URL-aware AI-writing (scrape + understand UI)**
+
+```
+ct tc url https://mini-bank.testamplify.com/login --ai
+```
+
+---
+
+## ✅ **3. Test Case Normalization**
+
+CT normalizes Markdown test cases into structured machine-readable JSON.
+
+```
+ct normalize ./cases
+```
+
+Output goes to:
+
+```
+.cementic/normalized/*.json
+```
+
+Each JSON contains:
+
+* ID
+* Title
+* Steps (array)
+* Expected results
+* Metadata / tags
+
+---
+
+## ✅ **4. Automatic Playwright Test Generation**
+
+Once normalized, CT can generate full Playwright tests using the POM architecture:
+
+```
+ct gen --lang ts
+```
+
+Generated tests go into:
+
+```
+tests/*.spec.ts
+```
+
+Generated tests **import your Page Objects**:
+
+```ts
+import { LoginPage } from "../pages/login.page";
+
+test('AUTH-001 — Valid Login', async ({ page }) => {
+  const login = new LoginPage(page);
+  await login.goto();
+  await login.login("user", "pass");
+});
+```
+
+---
+
+## ✅ **5. Normalize + Generate in one shot**
+
+Most developers will use:
+
+```
+ct normalize ./cases --and-gen --lang ts
+```
+
+This:
+
+1. Normalizes test cases → JSON
+2. Generates Playwright tests immediately
+
+---
+
+## ✅ **6. Execute Playwright tests**
+
+CT wraps Playwright for convenience:
+
+```
+ct test
+```
+
+Equivalent to:
+
+```
+npx playwright test
+```
+
+---
+
+## ✅ **7. Bring Your Own LLM (BYO LLM API key)**
+
+CT is **LLM-agnostic**, meaning it does NOT force you to use OpenAI.
+
+You can set:
+
+```
+CT_LLM_API_KEY
+OPENAI_API_KEY
+CT_LLM_MODEL
+CT_LLM_BASE_URL
+```
+
+Works with:
+
+* OpenAI
+* Anthropic (Claude-compatible proxies)
+* Gemini (OpenAI-compatible API wrappers)
+* DeepSeek
+* Any **OpenAI-compatible LLM server**
+
+If AI fails or no key exists?
+✨ CT gracefully falls back to manual templates.
+
+---
+
+## ✅ **8. URL Scraper (Headless page scanner)**
+
+Given a URL, CT extracts:
+
+* Page title
+* Headings
+* Buttons
+* Inputs
+* Basic layout info
+
+This helps the LLM generate highly accurate test cases.
+
+---
+
+## ⭐️ CLI Commands Reference
+
+Below is every command CT currently supports.
+
+---
+
+# 📦 **CLI Commands**
+
+---
+
+## `ct new "<projectName>"`
+
+Scaffold a new CementicTest + Playwright project from scratch.
+
+**Examples:**
+
+```bash
+ct new "Bank"
+ct new "Bank" --no-browsers  # Skip browser download
+```
+
+What it does:
+
+* Installs Playwright
+* Runs browser install
+* Creates POM structure
+* Adds sample pages & test
+* Ready in under 30 seconds
+
+---
+
+## `ct tc`
+
+Interactive test case writer.
+
+```bash
+# Interactive mode
+ct tc
+
+# Non-interactive mode (CI/Scripting)
+ct tc --feature "Login" --desc "Login page" --count 5
+```
+
+Prompts (Interactive):
+
+* Feature/page name
+* Optional app description
+* Number of test cases
+
+Generates Markdown inside `/cases`.
+
+---
+
+## `ct tc --ai`
+
+Same as above, but uses AI (requires API key):
+
+```bash
+ct tc --ai
+```
+
+---
+
+## `ct tc url <url> --ai`
+
+Scrape + AI test case writer.
+
+```bash
+ct tc url https://mini-bank.testamplify.com/login --ai
+```
+
+This is the most powerful mode.
+
+---
+
+## `ct normalize <path>`
+
+Convert human-readable test cases into machine-readable JSON format.
+
+```bash
+ct normalize ./cases
+```
+
+Outputs:
+
+```
+.cementic/normalized/*.json
+```
+
+---
+
+## `ct normalize <path> --and-gen --lang ts`
+
+Normalize AND generate tests in one step.
+
+```bash
+ct normalize ./cases --and-gen --lang ts
+```
+
+---
+
+## `ct gen --lang ts`
+
+Generate Playwright test files from normalized JSON cases.
+
+```bash
+ct gen --lang ts
+ct gen --lang ts --out tests/e2e  # Custom output directory
+```
+
+---
+
+## `ct test`
+
+Runs Playwright test runner.
+
+```bash
+ct test
+```
+
+---
+
+## `ct flow`
+
+**One-Shot Command**: Normalizes cases, generates tests, and runs them in sequence.
+
+```bash
+ct flow
+ct flow --lang js
+ct flow --no-run  # Normalize & Generate only (skip execution)
+```
+
+---
+
+## `ct report`
+
+Opens the Playwright HTML report in your default browser.
+
+```bash
+ct report
+```
+
+---
+
+## `ct serve`
+
+Starts the Allure report server (if Allure is configured).
+
+```bash
+ct serve
+```
+
+---
+
+## `ct ci`
+
+Generates a GitHub Actions workflow file (`.github/workflows/cementic.yml`) for CI/CD.
+
+```bash
+ct ci
+```
+
+---
+
+# ⚙️ Environment Variables
+
+| Variable          | Description                             |
+| ----------------- | --------------------------------------- |
+| `CT_LLM_API_KEY`  | Primary AI key                          |
+| `OPENAI_API_KEY`  | Secondary AI key                        |
+| `CT_LLM_MODEL`    | Override default model (`gpt-4.1-mini`) |
+| `CT_LLM_BASE_URL` | Custom LLM endpoint                     |
+| `CT_DEBUG`        | Enables verbose logging                 |
+
+---
+
+# 📁 Project Structure
+
+After running `ct new “MyProject”`:
+
+```
+project/
+  pages/
+    login.page.ts
+    ...
+  tests/
+    sample.spec.ts
+  test-data/
+  utils/
+  cases/
+  .cementic/
+    normalized/
+  playwright.config.ts
+```
+
+---
+
+# 🧩 Architecture Overview
+
+### **Input**
+
+* Human test cases (Markdown)
+* AI-generated test cases
+* Scraped UI context
+
+### **Processing**
+
+1. Normalize (Markdown → JSON)
+2. Generate POM-based Playwright tests
+3. Maintain test ID prefixes (AUTH-###, DASH-###, etc.)
+
+### **Output**
+
+* Full Playwright automation suite ready to run
+
+---
+
+# 🚀 Developer Setup (For Internal Development)
+
+### Clone & install dependencies
+
+```bash
+git clone <repo>
+cd cementic-test
+npm install
+```
+
+### Build the CLI
+
+```bash
+npm run build
+```
+
+### Link locally
+
+```bash
+npm link
+```
+
+Test globally:
+
+```bash
+ct --help
+```
+
+---
+
+# 🧪 Developer Testing Loop
+
+1. Modify code
+2. Run:
+
+```
+npm run build && npm link
+```
+
+3. In a sample project:
+
+```
+mkdir demo && cd demo
+ct new "Shop"
+ct tc url https://example.com/login --ai
+ct normalize ./cases --and-gen --lang ts
+ct test
+```
+
+---
+
+# 🏗 Implementation Notes (For Your Developer)
+
+### Key directories:
+
+```
+src/
+  cli.ts
+  commands/
+    new.ts
+    tc.ts
+    normalize.ts
+    gen.ts
+    test.ts
+  core/
+    prefix.ts
+    normalize.ts
+    llm.ts
+    scrape.ts
+    generator.ts
+  templates/
+```
+
+### Important details:
+
+* **`tc.ts`** manually checks `process.argv` for `--ai`
+  (because Commander is inconsistent with subcommands)
+* URL mode scrapes with `scrapePageSummary()`
+* LLM integration is fully isolated inside `core/llm.ts`
+* Test generation happens in `core/generator.ts`
+* Normalization lives in `core/normalize.ts`
+* Pages generator/templates live inside `templates/pages`
+
+### Code standards:
+
+* TypeScript everywhere
+* ESM modules
+* No external runtime dependencies except Playwright
+* Everything async
+* Clear separation between:
+
+  * Commands (CLI)
+  * Logic (core)
+  * Templates (scaffolding)
+  * Outputs (.cementic, tests, pages, cases)
+
+---
+
+# 📦 Release Process
+
+We use GitHub Actions for automated releases.
+
+### 1. Bump Version
+Update `package.json` version:
+```bash
+npm version patch # or minor/major
+```
+
+### 2. Push to Main
+```bash
+git push origin main
+```
+*CI will run tests and build.*
+
+### 3. Create Release Tag
+```bash
+git push --tags
+```
+*CI will detect the `v*` tag and automatically publish to NPM.*
+
+---
+
+# 📅 Roadmap
+
+### Phase 1 (Current)
+
+✔️ CLI scaffolding
+✔️ AI test case generator
+✔️ URL scraping
+✔️ Normalization pipeline
+✔️ POM test generator
+✔️ Playwright runner wrapper
+
+---
+
+### Phase 2 (Next)
+
+🔜 Self-healing locators
+🔜 Page synchronizer (`ct update pages`)
+🔜 API automation support (`ct api`)
+🔜 Test coverage reports
+
+---
+
+### Phase 3 (Future)
+
+🔜 CT Desktop App (UI version of CLI)
+🔜 VS Code extension
+🔜 CI/CD pipeline builder
+🔜 Visual assertion generator
+🔜 CT Agent (continuous learning on test failures)
+
+---
+
+# 🤝 Contributing
+
+1. Fork the repo
+2. Create a feature branch
+3. Follow code conventions
+4. Build & test locally (`npm link`)
+5. Submit PR# cementic-test
+6. What's Next?
+
+We created an org on NPMjs

package/dist/chunk-J63TUHIV.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+
+// src/commands/gen.ts
+import { Command } from "commander";
+import fg from "fast-glob";
+import { readFileSync, mkdirSync, writeFileSync } from "fs";
+import { join, basename, relative, resolve } from "path";
+function buildTestTitle(norm) {
+  const idPart = norm.id ? norm.id : "";
+  const cleanTitle = norm.title || "Untitled";
+  const tagSuffix = (norm.tags ?? []).map((t) => `@${t}`).join(" ");
+  return [idPart, cleanTitle, tagSuffix].filter(Boolean).join(" ").trim();
+}
+function buildTestBody(norm, relPomImport) {
+  const title = buildTestTitle(norm);
+  const stepsComment = (norm.steps ?? []).map((s) => `- ${s}`).join("\n  // ");
+  const expectations = (norm.expected ?? []).map(
+    (e) => `  // expect: ${e}
+  // TODO: map this to a real assertion using LoginPage`
+  ).join("\n\n");
+  let importPath = relPomImport.replace(/\\/g, "/");
+  if (!importPath.startsWith(".")) {
+    importPath = `./${importPath}`;
+  }
+  return `import { test, expect } from '@playwright/test';
+import { LandingPage } from '${importPath}';
+
+test('${title}', async ({ page }) => {
+  const pageObj = new LandingPage(page);
+
+  // Steps inferred from case:
+  // ${stepsComment || "TODO: no steps detected"}
+
+  // Example flow (replace with real mapping later):
+  await pageObj.goto();
+  // await pageObj.login('user@example.com', 'password');
+
+${expectations || "  // TODO: add assertions with LandingPage"}
+});
+`;
+}
+async function gen(opts) {
+  if (opts.lang !== "ts" && opts.lang !== "js") {
+    console.error("MVP supports --lang ts and --lang js only for now.");
+    process.exit(1);
+  }
+  const normalized = await fg([".cementic/normalized/*.json", "!.cementic/normalized/_index.json"]);
+  mkdirSync(opts.out, { recursive: true });
+  const projectRoot = process.cwd();
+  const pagesDir = join(projectRoot, "pages");
+  const outDir = resolve(projectRoot, opts.out);
+  const relPathToPages = relative(outDir, pagesDir);
+  const relPomImport = join(relPathToPages, "LandingPage");
+  for (const f of normalized) {
+    const norm = JSON.parse(readFileSync(f, "utf8"));
+    const stem = basename(f).replace(/\.json$/, "");
+    const fileStem = stem.replace(/[^\w-]+/g, "-");
+    const body = buildTestBody(norm, relPomImport);
+    const ext = opts.lang === "js" ? "spec.js" : "spec.ts";
+    const outFile = join(opts.out, `${fileStem}.${ext}`);
+    writeFileSync(outFile, body);
+  }
+  console.log(`\u2705 Generated ${normalized.length} POM-style test file(s) \u2192 ${opts.out}`);
+}
+function genCmd() {
+  const cmd = new Command("gen").description("Generate Playwright test files from normalized JSON cases").addHelpText("after", `
+Examples:
+  $ ct gen --lang ts
+  $ ct gen --lang js --out tests/e2e
+`).option("--lang <lang>", "Target language for test files (ts|js)", "ts").option("--out <dir>", "Output directory for generated tests", "tests/generated").action(async (opts) => {
+    await gen({ lang: opts.lang, out: opts.out });
+  });
+  return cmd;
+}
+
+export {
+  gen,
+  genCmd
+};
+//# sourceMappingURL=chunk-J63TUHIV.js.map

package/dist/chunk-J63TUHIV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commands/gen.ts"],"sourcesContent":["import { Command } from 'commander';\nimport fg from 'fast-glob';\nimport { readFileSync, mkdirSync, writeFileSync } from 'node:fs';\nimport { join, basename, relative, resolve } from 'node:path';\n\ntype NormalizedCase = {\n  id?: string;\n  title: string;\n  tags?: string[];\n  steps?: string[];\n  expected?: string[];\n  needs_review?: boolean;\n  source?: string;\n};\n\nfunction buildTestTitle(norm: NormalizedCase): string {\n  const idPart = norm.id ? norm.id : '';\n  const cleanTitle = norm.title || 'Untitled';\n  const tagSuffix = (norm.tags ?? []).map(t => `@${t}`).join(' ');\n  return [idPart, cleanTitle, tagSuffix].filter(Boolean).join(' ').trim();\n}\n\nfunction buildTestBody(norm: NormalizedCase, relPomImport: string): string {\n  const title = buildTestTitle(norm);\n  const stepsComment = (norm.steps ?? []).map(s => `- ${s}`).join('\\n  // ');\n  const expectations = (norm.expected ?? []).map(\n    e => `  // expect: ${e}\\n  // TODO: map this to a real assertion using LoginPage`\n  ).join('\\n\\n');\n\n  // Ensure import path starts with ./ or ../\n  let importPath = relPomImport.replace(/\\\\/g, '/');\n  if (!importPath.startsWith('.')) {\n    importPath = `./${importPath}`;\n  }\n\n  return `import { test, expect } from '@playwright/test';\nimport { LandingPage } from '${importPath}';\n\ntest('${title}', async ({ page }) => {\n  const pageObj = new LandingPage(page);\n\n  // Steps inferred from case:\n  // ${stepsComment || 'TODO: no steps detected'}\n\n  // Example flow (replace with real mapping later):\n  await pageObj.goto();\n  // await pageObj.login('user@example.com', 'password');\n\n${expectations || '  // TODO: add assertions with LandingPage'}\n});\n`;\n}\n\nexport async function gen(opts: { lang: string; out: string }) {\n  if (opts.lang !== 'ts' && opts.lang !== 'js') {\n    console.error('MVP supports --lang ts and --lang js only for now.');\n    process.exit(1);\n  }\n\n  const normalized = await fg(['.cementic/normalized/*.json', '!.cementic/normalized/_index.json']);\n  mkdirSync(opts.out, { recursive: true });\n\n  // Calculate relative path from output dir to 'pages/LandingPage'\n  // Assumption: project root has 'pages/'\n  const projectRoot = process.cwd();\n  const pagesDir = join(projectRoot, 'pages');\n  const outDir = resolve(projectRoot, opts.out);\n  \n  // path.relative(from, to)\n  const relPathToPages = relative(outDir, pagesDir);\n  const relPomImport = join(relPathToPages, 'LandingPage');\n\n  for (const f of normalized) {\n    const norm = JSON.parse(readFileSync(f, 'utf8')) as NormalizedCase;\n    const stem = basename(f).replace(/\\.json$/, '');\n    const fileStem = stem.replace(/[^\\w-]+/g, '-');\n\n    const body = buildTestBody(norm, relPomImport);\n    const ext = opts.lang === 'js' ? 'spec.js' : 'spec.ts';\n    const outFile = join(opts.out, `${fileStem}.${ext}`);\n    writeFileSync(outFile, body);\n  }\n\n  console.log(`✅ Generated ${normalized.length} POM-style test file(s) → ${opts.out}`);\n}\n\nexport function genCmd() {\n  const cmd = new Command('gen')\n    .description('Generate Playwright test files from normalized JSON cases')\n    .addHelpText('after', `\nExamples:\n  $ ct gen --lang ts\n  $ ct gen --lang js --out tests/e2e\n`)\n    .option('--lang <lang>', 'Target language for test files (ts|js)', 'ts')\n    .option('--out <dir>', 'Output directory for generated tests', 'tests/generated')\n    .action(async (opts) => {\n      await gen({ lang: opts.lang, out: opts.out });\n    });\n  return cmd;\n}"],"mappings":";;;AAAA,SAAS,eAAe;AACxB,OAAO,QAAQ;AACf,SAAS,cAAc,WAAW,qBAAqB;AACvD,SAAS,MAAM,UAAU,UAAU,eAAe;AAYlD,SAAS,eAAe,MAA8B;AACpD,QAAM,SAAS,KAAK,KAAK,KAAK,KAAK;AACnC,QAAM,aAAa,KAAK,SAAS;AACjC,QAAM,aAAa,KAAK,QAAQ,CAAC,GAAG,IAAI,OAAK,IAAI,CAAC,EAAE,EAAE,KAAK,GAAG;AAC9D,SAAO,CAAC,QAAQ,YAAY,SAAS,EAAE,OAAO,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK;AACxE;AAEA,SAAS,cAAc,MAAsB,cAA8B;AACzE,QAAM,QAAQ,eAAe,IAAI;AACjC,QAAM,gBAAgB,KAAK,SAAS,CAAC,GAAG,IAAI,OAAK,KAAK,CAAC,EAAE,EAAE,KAAK,SAAS;AACzE,QAAM,gBAAgB,KAAK,YAAY,CAAC,GAAG;AAAA,IACzC,OAAK,gBAAgB,CAAC;AAAA;AAAA,EACxB,EAAE,KAAK,MAAM;AAGb,MAAI,aAAa,aAAa,QAAQ,OAAO,GAAG;AAChD,MAAI,CAAC,WAAW,WAAW,GAAG,GAAG;AAC/B,iBAAa,KAAK,UAAU;AAAA,EAC9B;AAEA,SAAO;AAAA,+BACsB,UAAU;AAAA;AAAA,QAEjC,KAAK;AAAA;AAAA;AAAA;AAAA,OAIN,gBAAgB,yBAAyB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAM9C,gBAAgB,4CAA4C;AAAA;AAAA;AAG9D;AAEA,eAAsB,IAAI,MAAqC;AAC7D,MAAI,KAAK,SAAS,QAAQ,KAAK,SAAS,MAAM;AAC5C,YAAQ,MAAM,oDAAoD;AAClE,YAAQ,KAAK,CAAC;AAAA,EAChB;AAEA,QAAM,aAAa,MAAM,GAAG,CAAC,+BAA+B,mCAAmC,CAAC;AAChG,YAAU,KAAK,KAAK,EAAE,WAAW,KAAK,CAAC;AAIvC,QAAM,cAAc,QAAQ,IAAI;AAChC,QAAM,WAAW,KAAK,aAAa,OAAO;AAC1C,QAAM,SAAS,QAAQ,aAAa,KAAK,GAAG;AAG5C,QAAM,iBAAiB,SAAS,QAAQ,QAAQ;AAChD,QAAM,eAAe,KAAK,gBAAgB,aAAa;AAEvD,aAAW,KAAK,YAAY;AAC1B,UAAM,OAAO,KAAK,MAAM,aAAa,GAAG,MAAM,CAAC;AAC/C,UAAM,OAAO,SAAS,CAAC,EAAE,QAAQ,WAAW,EAAE;AAC9C,UAAM,WAAW,KAAK,QAAQ,YAAY,GAAG;AAE7C,UAAM,OAAO,cAAc,MAAM,YAAY;AAC7C,UAAM,MAAM,KAAK,SAAS,OAAO,YAAY;AAC7C,UAAM,UAAU,KAAK,KAAK,KAAK,GAAG,QAAQ,IAAI,GAAG,EAAE;AACnD,kBAAc,SAAS,IAAI;AAAA,EAC7B;AAEA,UAAQ,IAAI,oBAAe,WAAW,MAAM,kCAA6B,KAAK,GAAG,EAAE;AACrF;AAEO,SAAS,SAAS;AACvB,QAAM,MAAM,IAAI,QAAQ,KAAK,EAC1B,YAAY,2DAA2D,EACvE,YAAY,SAAS;AAAA;AAAA;AAAA;AAAA,CAIzB,EACI,OAAO,iBAAiB,0CAA0C,IAAI,EACtE,OAAO,eAAe,wCAAwC,iBAAiB,EAC/E,OAAO,OAAO,SAAS;AACtB,UAAM,IAAI,EAAE,MAAM,KAAK,MAAM,KAAK,KAAK,IAAI,CAAC;AAAA,EAC9C,CAAC;AACH,SAAO;AACT;","names":[]}