@cementic/cementic-test 0.2.6 → 0.2.7

package/README.md

@@ -1,460 +1,372 @@
-# CementicTest CLI
+# 🚀 CementicTest CLI
 
-CementicTest CLI (`ct`) turns plain-English test cases into runnable Playwright tests with a Page Object Model-oriented workflow.
+Turn plain English into **production-ready Playwright tests** — instantly.
 
-## Project links
+No setup headaches. No framework confusion. Just run and automate.
 
-- Website: https://cementic.testamplify.io/
-- Community: https://t.me/+Wbx7oK7ivqgxZGJh
-- Web app: browser-based AI testing workflow coming soon
+---
 
-Current pipeline:
+## ⚡ Run instantly (no install)
 
-```text
-ct tc -> ct normalize -> ct gen -> ct test
+```bash
+npx @cementic/cementic-test
 ```
 
-It can scaffold a project, write or AI-generate case files, normalize them into JSON, generate Playwright specs plus page objects, and run the resulting suite.
+Works even if your npm environment isn’t perfectly configured.
 
-## Project status
+---
 
-This repository currently ships the CLI workflow.
+## 💡 What this does
 
-The browser-based web app is in progress and early product updates will be shared on the website and in the community channel.
+CementicTest converts:
 
-## What this version does
+👉 Plain English
+👉 Into structured test cases
+👉 Into Playwright specs + Page Objects
+👉 Then runs them
 
-- Scaffolds new Playwright projects in JavaScript or TypeScript
-- Generates Markdown test cases manually or with AI
-- Supports URL-aware case generation with live page capture
-- Normalizes case files into structured JSON
-- Generates Playwright specs and POM classes from normalized cases
-- Avoids overwriting existing generated page-object files
-- Runs Playwright tests through a CLI wrapper
-- Opens Playwright HTML reports
-- Serves Allure reports if Allure is installed in the target project
-- Generates a GitHub Actions workflow for Playwright CI
+All from your terminal.
 
-## Installation
+---
 
-```bash
-# Run without a global install
-npx @cementic/cementic-test --help
+## 🧠 Why it’s different
 
-# Or install globally
-npm install -g @cementic/cementic-test
-```
+* No framework setup required
+* No Playwright expertise needed
+* No manual scripting to get started
+* AI-assisted test generation
+* Built-in Page Object Model (POM) structure
+* Works from **day one**
+
+---
 
-Requirements:
+## 🧪 What you can do
 
-- Node.js 18+
-- npm
+* Generate test cases (manual or AI)
+* Capture real websites and generate tests
+* Convert cases → JSON → Playwright code
+* Run tests instantly
+* Generate CI workflows
+* View reports (Playwright + Allure)
 
-## Quick start
+---
 
-### JavaScript project
+## ⚡ 60-second quick start
 
 ```bash
-ct new demo-js --lang js
-cd demo-js
-ct tc --feature "Login form" --count 2
-ct normalize ./cases --and-gen --lang js
-ct test
+npx @cementic/cementic-test
 ```
 
-### TypeScript project
+Then:
 
 ```bash
-ct new demo-ts --lang ts
-cd demo-ts
-ct tc url https://mini-bank.testamplify.com/login --feature "Login" --count 2
-ct normalize ./cases --and-gen --lang ts
+ct new demo
+cd demo
+
+ct tc --feature "Login form" --count 2
+ct normalize ./cases --and-gen
 ct test
 ```
 
-## Command flow
+Done. You just created and ran automation.
 
-### 1. `ct new <projectName>`
+---
 
-Scaffolds a new CementicTest + Playwright project.
+## 🌐 Generate tests from a real website
 
 ```bash
-ct new my-suite
-ct new my-suite --lang ts
-ct new my-suite --no-browsers
+ct tc url https://mini-bank.testamplify.com/login --ai --feature "Login" --count 2
 ```
 
-Current scaffold support:
-
-- `--lang js`: JavaScript template with:
-  - `pages/BasePage.js`
-  - `pages/LoginPage.js`
-  - `pages/DashboardPage.js`
-  - `pages/FormPage.js`
-  - `tests/login.spec.js`
-  - `tests/dashboard.spec.js`
-- `--lang ts`: TypeScript template with:
-  - `pages/LandingPage.ts`
-  - `tests/landing.spec.ts`
-  - `tsconfig.json`
-  - `playwright.config.ts`
+This will:
 
-What `ct new` does:
+* Capture the page
+* Understand elements
+* Generate realistic test scenarios
+* Produce runnable Playwright tests
 
-- creates the project directory
-- copies the selected template
-- initializes git
-- runs `npm install`
-- optionally runs `npx playwright install`
+Important:
 
-### 2. `ct tc`
+* Live capture resolves Playwright from your current project first
+* If you are inside a project created with `ct new`, `ct tc url --ai` uses that project's local `@playwright/test`
+* If Playwright is missing or Chromium is not installed, the CLI now prints the exact next step instead of failing with a package-resolution stack trace
 
-Creates Markdown case files in `./cases`.
+---
 
-Interactive mode:
+## 🧱 How it works
 
-```bash
-ct tc
+```text
+Plain English → Markdown Cases
+           → Normalized JSON
+           → Playwright Specs + POM
+           → Test Execution
 ```
 
-Non-interactive mode:
+---
 
-```bash
-ct tc --feature "Checkout" --desc "Guest checkout flow" --count 3
-```
+## ⚠️ If install fails (important)
 
-AI mode:
+If you see something like:
 
-```bash
-ct tc --ai --feature "Login" --count 3
 ```
+npm ERR! Cannot read properties of null (reading 'matches')
+```
+
+👉 That’s an npm issue, not CementicTest.
 
-### 3. `ct tc url <url>`
+### ✅ Fix instantly
 
-Generates cases with awareness of a live page.
+Just run:
 
 ```bash
-ct tc url https://mini-bank.testamplify.com/login --feature "Login" --count 2
-ct tc url https://mini-bank.testamplify.com/login --ai --feature "Login" --count 2
-ct tc url https://mini-bank.testamplify.com/login --ai --headed --feature "Login"
-ct tc url https://mini-bank.testamplify.com/login --ai --capture-only --feature "Login"
+npx @cementic/cementic-test
 ```
 
-Current behavior:
-
-- captures a live page with Playwright and extracts headings, buttons, links, inputs, status regions, and selector candidates
-- sends that captured element map to the capture-aware AI flow when `--ai` is enabled
-- saves the full capture artifact to `.cementic/capture/capture-*.json`
-- saves a runnable preview spec to `tests/preview/spec-preview-*.spec.cjs` when AI scenarios are generated
-- writes `<!-- ct:url ... -->` metadata plus selector and `playwright` hints into generated Markdown so normalization and generation preserve the capture output
+No install needed.
 
-### 4. `ct normalize <path>`
+---
 
-Converts case files into normalized JSON in `.cementic/normalized/`.
+## 🧰 Optional install
 
 ```bash
-ct normalize ./cases
-ct normalize "cases/**/*.md"
-ct normalize ./cases --and-gen --lang ts
+npm install -g @cementic/cementic-test
 ```
 
-Current normalized output includes:
-
-- `id`
-- `title`
-- `tags`
-- `steps`
-- `expected`
-- `needs_review`
-- `review_reasons`
-- `source`
-- `url`
-
-Important current behavior:
+If you use the global CLI, live capture still expects Playwright to be installed in the project you are working in.
 
-- title is stored without duplicating the case ID prefix
-- URL metadata is read from `<!-- ct:url ... -->` first
-- if no metadata exists, normalization falls back to URL extraction from steps
+---
 
-### 5. `ct gen`
+## 🧪 Core commands
 
-Generates Playwright specs and page-object files from normalized JSON.
+### Create project
 
 ```bash
-ct gen --lang ts
-ct gen --lang js
-ct gen --lang ts --out tests/e2e
+ct new my-suite
 ```
 
-Current output locations:
-
-- specs: `tests/generated/` by default
-- page objects: `pages/`
+### Generate test cases
 
-Current generator behavior:
+```bash
+ct tc --feature "Checkout" --count 3
+```
 
-- maps common natural-language steps to Playwright actions
-- maps common expected-result phrases to Playwright assertions
-- derives one POM class per feature prefix where possible
-- uses `norm.url` for page-object `goto()`
-- avoids duplicate navigation when setup already handles the target URL
-- does not overwrite existing POM files
-- emits correct relative imports for generated specs
+### Generate from live site
 
-### 6. `ct test`
+```bash
+ct tc url <url> --ai
+```
 
-Runs Playwright tests.
+Common setup after scaffolding:
 
 ```bash
-ct test
-ct test --headed
-ct test --project chromium
+cd my-suite
+npm install
+npx playwright install chromium
+ct tc url https://example.com/login --ai --feature "Login"
 ```
 
-This is a thin wrapper over:
+### Normalize + generate tests
 
 ```bash
-npx playwright test
+ct normalize ./cases --and-gen
 ```
 
-Arguments after `ct test` are passed through to Playwright.
+### Run tests
 
-### 7. `ct flow`
-
-Runs the end-to-end workflow:
+```bash
+ct test
+```
 
-1. normalize
-2. generate
-3. test
+### Full workflow
 
 ```bash
 ct flow
-ct flow ./cases
-ct flow --lang js
-ct flow --no-run
 ```
 
-### 8. `ct report`
+---
 
-Opens the Playwright HTML report.
+## 📊 Reports
 
 ```bash
-ct report
+ct report        # Playwright report
+ct serve         # Allure report (if installed)
 ```
 
-Equivalent behavior:
+---
+
+## ⚙️ CI (GitHub Actions)
 
 ```bash
-npx playwright show-report
+ct ci
 ```
 
-### 9. `ct serve`
+Generates a ready-to-run workflow.
 
-Serves the Allure report if `allure-commandline` is available in the current project.
+---
 
-```bash
-ct serve
-```
+## 🤖 AI support
 
-Current behavior:
+Supports multiple providers:
 
-- prefers the local `node_modules/allure-commandline/bin/allure` binary
-- falls back to `npx allure serve ./allure-results`
+* OpenAI
+* Anthropic
+* Gemini
+* DeepSeek
+* Qwen
+* Kimi
 
-### 10. `ct ci`
+Set your key:
 
-Generates a GitHub Actions workflow at `.github/workflows/cementic.yml`.
+```bash
+export OPENAI_API_KEY=your_key
+```
+or 
 
 ```bash
-ct ci
+export ANTHROPIC_API_KEY=your_key
+export GEMINI_API_KEY=your_key
+export DEEPSEEK_API_KEY=your_key
+export QWEN_API_KEY=your_key
+export KIMI_API_KEY=your_key
 ```
 
-Current workflow behavior:
+# Optional (generic / override)
+```bash
+export CT_LLM_API_KEY=your_key
+export CT_LLM_PROVIDER=openai
+export CT_LLM_MODEL=your_model
+export CT_LLM_BASE_URL=https://your-api-base-url
+```
 
-- skips generation if the workflow file already exists
-- installs dependencies
-- installs Playwright browsers
-- runs `npx playwright test`
-- uploads the Playwright HTML report as an artifact
+Provider notes:
 
-## AI provider support
+* `DEEPSEEK_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `QWEN_API_KEY`, `KIMI_API_KEY`, and `OPENAI_API_KEY` are all detected directly
+* `CT_LLM_API_KEY` + `CT_LLM_BASE_URL` works for OpenAI-compatible endpoints
+* `CT_LLM_PROVIDER` can explicitly select `deepseek`, `anthropic`, `gemini`, `qwen`, `kimi`, or `openai`
+---
 
-Current AI flows live in `src/core/llm.ts` and `src/core/analyse.ts`.
+## 🛠️ Troubleshooting
 
-Provider behavior in this version:
+### `ct tc url --ai` says Playwright is not found
 
-- `ct tc --ai` uses the standard Markdown case writer in `src/core/llm.ts`
-- `ct tc url --ai` uses the capture-aware analysis flow in `src/core/analyse.ts`
-- manual template generation is used if AI generation fails
+Run:
 
-Supported environment variables:
+```bash
+npm install
+npx playwright install chromium
+```
 
-| Variable | Purpose |
-| --- | --- |
-| `DEEPSEEK_API_KEY` | DeepSeek key for capture-aware analysis |
-| `ANTHROPIC_API_KEY` | Primary Anthropic key |
-| `CT_ANTHROPIC_API_KEY` | Alternate Anthropic key |
-| `GEMINI_API_KEY` | Gemini key for capture-aware analysis |
-| `OPENAI_API_KEY` | OpenAI key |
-| `QWEN_API_KEY` | Qwen key for capture-aware analysis |
-| `KIMI_API_KEY` | Kimi / Moonshot key for capture-aware analysis |
-| `CT_LLM_API_KEY` | Generic OpenAI-compatible API key |
-| `CT_LLM_PROVIDER` | Optional provider override (`deepseek`, `anthropic`, `gemini`, `qwen`, `kimi`, or `openai`) |
-| `CT_LLM_MODEL` | Model override |
-| `CT_LLM_BASE_URL` | OpenAI-compatible base URL override |
+This command resolves Playwright from the active project directory first, not from the CLI's global install.
 
-Current defaults:
+### `ct tc url --ai` says Chromium is not installed
 
-- DeepSeek default: `deepseek-chat`
-- Anthropic default: `claude-sonnet-4-5`
-- Gemini default: `gemini-2.5-flash`
-- Qwen default: `qwen-plus`
-- Kimi default: `moonshot-v1-8k`
-- OpenAI-compatible default: `gpt-4o-mini`
+Run:
 
-## URL capture
+```bash
+npx playwright install chromium
+```
 
-Current capture behavior lives in `src/core/capture.ts`.
+### No AI key found
 
-Primary path:
+Set one of:
 
-- uses a real Playwright browser
-- extracts:
-  - page title
-  - headings
-  - buttons
-  - links
-  - inputs with label, placeholder, name, type, and `data-testid`
-  - status and alert regions
-  - selector confidence and alternative selectors
-- builds a structured `ElementMap`
-- passes that capture into `src/core/analyse.ts` for evidence-backed scenario generation
-- formats markdown, JSON, and preview-spec outputs through `src/core/report.ts`
+```bash
+export OPENAI_API_KEY=your_key
+export ANTHROPIC_API_KEY=your_key
+export GEMINI_API_KEY=your_key
+export DEEPSEEK_API_KEY=your_key
+export QWEN_API_KEY=your_key
+export KIMI_API_KEY=your_key
+```
+
+Or use:
+
+```bash
+export CT_LLM_API_KEY=your_key
+export CT_LLM_BASE_URL=https://your-api-base-url
+```
+
+### Legacy macOS project setup
 
-## Generated project structure
+On macOS 13 and older, `ct new` installs Chromium only during Playwright browser setup to avoid unsupported WebKit failures.
 
-After a typical run:
+## 📁 Output structure
 
 ```text
 project/
   cases/
   pages/
-  tests/
-    generated/
-  .cementic/
-    normalized/
-  playwright.config.js|ts
+  tests/generated/
+  .cementic/normalized/
 ```
 
-Typical file flow:
+---
 
-```text
-cases/*.md
-  -> .cementic/normalized/*.json
-  -> tests/generated/*.spec.ts|js
-  -> pages/*.ts|js
-```
+## 🎯 Who this is for
 
-## Example case file
+* QA engineers moving into automation
+* Beginners learning Playwright
+* Teams needing fast test generation
+* Developers who want speed over setup
 
-```md
-# AUTH-001 — User can log in @smoke @auth
-<!-- ct:url https://mini-bank.testamplify.com/login -->
-## Steps
-1. Navigate to https://mini-bank.testamplify.com/login
-2. Fill in email with [EMAIL_ADDRESS]'
-3. Fill in password with 'secret'
-4. Click the 'Sign In' button
+---
 
-## Expected Results
-- Page redirects to /dashboard
-- Welcome message is visible
-```
+## 🚀 Philosophy
 
-## Current implementation notes
+> Meaning → Structure → System → Resilience
 
-This version is intentionally heuristic and file-oriented.
+CementicTest flips automation from:
 
-Important current characteristics:
-
-- generated specs are POM-oriented, not raw recorded scripts
-- capture-generated selector and assertion hints are preserved through `normalize` and `gen`
-- generator rules still cover non-capture cases heuristically, but capture-backed cases now keep exact selectors and assertions
-- Playwright itself is used for capture and test execution
-- Playwright CLI and Playwright agents are not yet first-class runtime backends in this version
-
-## Developer setup
-
-```bash
-git clone <repo>
-cd cementic-test-cli
-npm install
+```
+Code → Tests
 ```
 
-Build the CLI:
+to:
 
-```bash
-npm run build
+```
+Intent → Tests
 ```
 
-Run the repo test suite:
+---
 
-```bash
-npm test
-```
+## 🔗 Links
 
-What `npm test` currently verifies:
+* 🌐 Website: [https://cementic.testamplify.io/](https://cementic.testamplify.io/)
+* 💬 Community: [https://t.me/+Wbx7oK7ivqgxZGJh](https://t.me/+Wbx7oK7ivqgxZGJh)
 
-- build succeeds
-- `ct tc url` writes URL metadata
-- capture-generated selector and `playwright` hints survive `normalize` and `gen`
-- `ct normalize` and `ct gen` preserve the recent generator fixes
-- the JavaScript scaffold contains the expected page objects and sample specs
+---
 
-## Local development loop
+## 🧪 Status
 
-```bash
-npm run build
-npm link
+* CLI: ✅ Production-ready
+* Web App (Agentic UI): 🚧 Coming soon
 
-ct --help
-```
+---
 
-Manual smoke flow:
+## 💬 Final note
 
-```bash
-mkdir demo
-cd demo
+You don’t need to install anything.
+You don’t need to configure anything.
 
-ct new sample --lang ts --no-browsers
-cd sample
+Just run:
 
-ct tc url https://mini-bank.testamplify.com/login --ai --feature "Login" --count 1
-ct normalize ./cases --and-gen --lang ts
-ct test
+```bash
+npx @cementic/cementic-test
 ```
 
-## Key source files
+And start automating.
 
-```text
-src/cli.ts
-src/commands/new.ts
-src/commands/tc.ts
-src/commands/normalize.ts
-src/commands/gen.ts
-src/commands/test.ts
-src/commands/flow.ts
-src/core/capture.ts
-src/core/analyse.ts
-src/core/llm.ts
-src/core/report.ts
-src/core/prefix.ts
-templates/student-framework/
-templates/student-framework-ts/
-```
 
 ## Changelog
 
+### v0.2.7
+
+- fixed project-first Playwright resolution for `ct tc url --ai`, including global and `npx` CLI usage
+- added clearer capture failure categories and setup guidance for missing Playwright, missing browsers, and page-load failures
+- centralized AI provider detection so `tc --ai` and capture analysis recognize the same providers and env vars
+- fixed missing DeepSeek guidance in the CLI help path
+- changed legacy macOS browser setup to install Chromium only by default and avoid WebKit unsupported failures
+
 ### v0.2.6
 
 - added an install-time banner with links to the website and community