@testcollab/cli 1.3.0

package/docs/frameworks.md

@@ -0,0 +1,485 @@
+# Framework Setup Guide
+
+How to generate test result files compatible with `tc report` for each supported framework.
+
+`tc report` accepts two formats:
+- **Mochawesome JSON** (`--format mochawesome`)
+- **JUnit XML** (`--format junit`)
+
+Your test names must include a TestCollab case ID (e.g., `[TC-123]`, `TC-123`, `id-123`, or `testcase-123`) so results can be matched to test cases. See the [README](../README.md#mapping-test-cases) for all supported patterns.
+
+### Supported frameworks
+
+[Cypress](#cypress) | [Playwright](#playwright) | [Jest](#jest) | [Pytest](#pytest) | [TestNG](#testng) | [JUnit 4/5](#junit-45) | [Robot Framework](#robot-framework) | [PHPUnit](#phpunit) | [Cucumber.js](#cucumberjs) | [Cucumber JVM](#cucumber-jvm) | [WebDriverIO](#webdriverio) | [TestCafe](#testcafe) | [Newman (Postman)](#newman-postman) | [Behave (Python)](#behave-python) | [Go (`go test`)](#go-go-test) | [Kaspresso / Kotlin](#kaspresso--kotlin)
+
+### JUnit XML example
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<testsuites name="My Test Suite">
+  <testsuite name="Authentication" tests="3" failures="1" skipped="1">
+    <testcase classname="Authentication.Login" name="[TC-123] should login with valid credentials" time="0.12" />
+    <testcase classname="Authentication.Login" name="[TC-124] should reject invalid password" time="0.43">
+      <failure message="Expected 401 but got 200">AssertionError: expected status 401 but got 200</failure>
+    </testcase>
+    <testcase classname="Authentication.Login" name="[TC-125] should support SSO login" time="0.07">
+      <skipped />
+    </testcase>
+  </testsuite>
+</testsuites>
+```
+
+### Mochawesome JSON example
+
+```json
+{
+  "results": [
+    {
+      "title": "Authentication",
+      "tests": [
+        {
+          "title": "[TC-123] should login with valid credentials",
+          "fullTitle": "Authentication [TC-123] should login with valid credentials",
+          "state": "passed",
+          "pass": true,
+          "fail": false
+        },
+        {
+          "title": "[TC-124] should reject invalid password",
+          "state": "failed",
+          "pass": false,
+          "fail": true,
+          "err": { "message": "Expected 401 but got 200" }
+        },
+        {
+          "title": "[TC-125] should support SSO login",
+          "state": "pending",
+          "pass": false,
+          "fail": false,
+          "pending": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+The key requirement is that each test name contains a TestCollab case ID (e.g., `[TC-123]`). The CLI extracts this ID to match results to the correct test case in your test plan.
+
+All examples below assume you've set the `TESTCOLLAB_TOKEN` environment variable (or pass `--api-key` to each command). See [Authentication](../README.md#authentication).
+
+---
+
+## Cypress
+
+Cypress has native Mochawesome support.
+
+**Install:**
+
+```bash
+npm install --save-dev mochawesome mochawesome-merge mochawesome-report-generator
+```
+
+**Configure** (`cypress.config.js`):
+
+```js
+module.exports = {
+  reporter: 'mochawesome',
+  reporterOptions: {
+    reportDir: 'mochawesome-report',
+    overwrite: false,
+    html: false,
+    json: true
+  }
+};
+```
+
+**Run and upload:**
+
+```bash
+npx cypress run
+tc report --project 123 --test-plan-id 456 \
+  --format mochawesome --result-file ./mochawesome-report/mochawesome.json
+```
+
+---
+
+## Playwright
+
+Playwright has a built-in JUnit reporter.
+
+**Run:**
+
+```bash
+npx playwright test --reporter=junit
+```
+
+This writes to stdout by default. To write to a file, set the `PLAYWRIGHT_JUNIT_OUTPUT_NAME` env var:
+
+```bash
+PLAYWRIGHT_JUNIT_OUTPUT_NAME=results.xml npx playwright test --reporter=junit
+```
+
+Or configure in `playwright.config.ts`:
+
+```ts
+export default {
+  reporter: [['junit', { outputFile: 'results.xml' }]]
+};
+```
+
+**Upload:**
+
+```bash
+tc report --project 123 --test-plan-id 456 \
+  --format junit --result-file ./results.xml
+```
+
+---
+
+## Jest
+
+Use the `jest-junit` package to generate JUnit XML.
+
+**Install:**
+
+```bash
+npm install --save-dev jest-junit
+```
+
+**Run:**
+
+```bash
+JEST_JUNIT_OUTPUT_DIR=./reports npx jest --reporters=default --reporters=jest-junit
+```
+
+Or configure in `package.json`:
+
+```json
+{
+  "jest": {
+    "reporters": [
+      "default",
+      ["jest-junit", { "outputDirectory": "./reports", "outputName": "results.xml" }]
+    ]
+  }
+}
+```
+
+**Upload:**
+
+```bash
+tc report --project 123 --test-plan-id 456 \
+  --format junit --result-file ./reports/results.xml
+```
+
+---
+
+## Pytest
+
+Pytest has built-in JUnit XML output.
+
+**Run:**
+
+```bash
+pytest --junitxml=results.xml
+```
+
+**Upload:**
+
+```bash
+tc report --project 123 --test-plan-id 456 \
+  --format junit --result-file ./results.xml
+```
+
+---
+
+## TestNG
+
+TestNG generates JUnit-compatible XML by default.
+
+**Run:**
+
+The default output is at `test-output/junitreports/`. You can also configure the output in your `testng.xml` or build tool.
+
+**Maven example:**
+
+```bash
+mvn test
+```
+
+**Upload:**
+
+```bash
+tc report --project 123 --test-plan-id 456 \
+  --format junit --result-file ./test-output/junitreports/TEST-TestSuite.xml
+```
+
+---
+
+## JUnit 4/5
+
+JUnit is the native source of the XML format — no extra setup needed.
+
+**Maven:**
+
+```bash
+mvn test
+# Results at target/surefire-reports/
+```
+
+**Gradle:**
+
+```bash
+gradle test
+# Results at build/test-results/test/
+```
+
+**Upload:**
+
+```bash
+tc report --project 123 --test-plan-id 456 \
+  --format junit --result-file ./target/surefire-reports/TEST-com.example.MyTest.xml
+```
+
+---
+
+## Robot Framework
+
+Use the `--xunit` flag to generate JUnit-compatible XML.
+
+**Run:**
+
+```bash
+robot --xunit results.xml tests/
+```
+
+**Upload:**
+
+```bash
+tc report --project 123 --test-plan-id 456 \
+  --format junit --result-file ./results.xml
+```
+
+---
+
+## PHPUnit
+
+PHPUnit has built-in JUnit XML logging.
+
+**Run:**
+
+```bash
+phpunit --log-junit results.xml
+```
+
+**Upload:**
+
+```bash
+tc report --project 123 --test-plan-id 456 \
+  --format junit --result-file ./results.xml
+```
+
+---
+
+## Cucumber.js
+
+Use a JUnit formatter plugin.
+
+**Install:**
+
+```bash
+npm install --save-dev cucumber-junit
+```
+
+**Run:**
+
+```bash
+npx cucumber-js --format json:./reports/cucumber.json
+npx cucumber-junit < ./reports/cucumber.json > ./reports/results.xml
+```
+
+Or use `cucumber-junit-formatter` directly:
+
+```bash
+npm install --save-dev @cucumber/junit-xml-formatter
+npx cucumber-js --format @cucumber/junit-xml-formatter:./reports/results.xml
+```
+
+**Upload:**
+
+```bash
+tc report --project 123 --test-plan-id 456 \
+  --format junit --result-file ./reports/results.xml
+```
+
+---
+
+## Cucumber JVM
+
+Cucumber JVM has a built-in JUnit XML plugin.
+
+**Configure** (in `@CucumberOptions` or `cucumber.properties`):
+
+```java
+@CucumberOptions(plugin = {"junit:target/cucumber-reports/results.xml"})
+```
+
+Or in `cucumber.properties`:
+
+```
+cucumber.plugin=junit:target/cucumber-reports/results.xml
+```
+
+**Upload:**
+
+```bash
+tc report --project 123 --test-plan-id 456 \
+  --format junit --result-file ./target/cucumber-reports/results.xml
+```
+
+---
+
+## WebDriverIO
+
+Use the `@wdio/junit-reporter` package.
+
+**Install:**
+
+```bash
+npm install --save-dev @wdio/junit-reporter
+```
+
+**Configure** (`wdio.conf.js`):
+
+```js
+exports.config = {
+  reporters: [
+    ['junit', {
+      outputDir: './reports',
+      outputFileFormat: () => 'results.xml'
+    }]
+  ]
+};
+```
+
+**Upload:**
+
+```bash
+tc report --project 123 --test-plan-id 456 \
+  --format junit --result-file ./reports/results.xml
+```
+
+---
+
+## TestCafe
+
+Use the `testcafe-reporter-junit` package.
+
+**Install:**
+
+```bash
+npm install --save-dev testcafe-reporter-junit
+```
+
+**Run:**
+
+```bash
+npx testcafe chrome tests/ --reporter junit:results.xml
+```
+
+**Upload:**
+
+```bash
+tc report --project 123 --test-plan-id 456 \
+  --format junit --result-file ./results.xml
+```
+
+---
+
+## Newman (Postman)
+
+Use the `newman-reporter-junit` package.
+
+**Install:**
+
+```bash
+npm install --save-dev newman-reporter-junit
+```
+
+**Run:**
+
+```bash
+npx newman run collection.json --reporters cli,junit --reporter-junit-export results.xml
+```
+
+**Upload:**
+
+```bash
+tc report --project 123 --test-plan-id 456 \
+  --format junit --result-file ./results.xml
+```
+
+---
+
+## Behave (Python)
+
+Behave has built-in JUnit output.
+
+**Run:**
+
+```bash
+behave --junit --junit-directory ./reports
+```
+
+**Upload:**
+
+```bash
+tc report --project 123 --test-plan-id 456 \
+  --format junit --result-file ./reports/TESTS-features.xml
+```
+
+---
+
+## Go (`go test`)
+
+Use `go-junit-report` to convert Go test output to JUnit XML.
+
+**Install:**
+
+```bash
+go install github.com/jstemmer/go-junit-report/v2@latest
+```
+
+**Run:**
+
+```bash
+go test ./... -v 2>&1 | go-junit-report > results.xml
+```
+
+**Upload:**
+
+```bash
+tc report --project 123 --test-plan-id 456 \
+  --format junit --result-file ./results.xml
+```
+
+---
+
+## Kaspresso / Kotlin
+
+Kaspresso and Kotlin test frameworks inherit from the JUnit runner, so they produce JUnit XML natively.
+
+**Run (Gradle):**
+
+```bash
+./gradlew connectedAndroidTest
+# Results at app/build/outputs/androidTest-results/
+```
+
+**Upload:**
+
+```bash
+tc report --project 123 --test-plan-id 456 \
+  --format junit --result-file ./app/build/outputs/androidTest-results/TEST-results.xml
+```

package/docs/specgen.md

@@ -0,0 +1,77 @@
+## TODO
+- [x] Wire `specgen` command with structured-output feature generation.
+- [x] Add AI-assisted discovery (cached to `.testcollab/specgen.json`).
+- [x] Support Gemini/Claude provider selection and document key requirements.
+- [x] Update `package-lock.json` after installing new deps (Gemini SDK).
+- [ ] Smoke-test both providers with real keys; add tests for provider selection/discovery parsing/error handling.
+- [ ] Expand CLI help with model examples and first-run vs cached behavior.
+
+`specgen` crawls your source code and generates `.feature` files with ready-to-run scenarios.
+
+## Terminology
+
+- **Target family:** A domain bucket (e.g., QA Copilot, Billing, BDD) that groups related code paths and sets defaults like parsing strategy, priority, and output folder.
+
+- **Target:** A concrete unit inside a family (e.g., `ChatPanel.tsx`, `qacconversationthread` API handler, `testplan` service). Each target has entry files, supporting context, and its own `.feature` output path.
+
+### Attributes
+- **Target family:** `name`, `kind` (backend/ui/cli/job), `paths` (globs), `priority`, `owner` (optional), `notes`/exclusions, `output_root` for the family.
+- **Target:** `id`, `family`, `type` (api_controller/model/ui_component/job/cli_command), `entry` files, `context` (supporting code/docs/tests), `routes/events` or `states/flows`, `priority`, `confidence_flags` (e.g., low-context), `output_path` for the `.feature` file.
+
+### JSON shapes
+Target family
+```json
+{
+  "name": "qa_copilot",
+  "kind": "backend",
+  "paths": ["api/qacopilot/**", "api/qacconversation*/**"],
+  "priority": "high",
+  "owner": "team-copilot",
+  "notes": "skip legacy/v1 controllers",
+  "output_root": "features/qa_copilot"
+}
+```
+
+Target
+```json
+{
+  "id": "qacconversationthread",
+  "family": "qa_copilot",
+  "type": "api_controller",
+  "entry": ["api/qacconversationthread/controllers/qacconversationthread.js"],
+  "context": ["api/qacconversationthread/services/**", "tests/qacconversationthread/**"],
+  "routes": ["GET /qacconversationthreads", "POST /qacconversationthreads"],
+  "priority": "core",
+  "confidence_flags": ["low-context"],
+  "output_path": "features/qa_copilot/qacconversationthread.feature"
+}
+```
+
+## State/cache
+- Discovered target families/targets and their output paths are cached in `.testcollab/specgen.json` at repo root. Commit it for reproducible runs, or add it to `.gitignore` if you prefer ephemeral caching.
+
+## How to run it
+Requires an AI key:
+- Claude models (default): set `ANTHROPIC_API_KEY`.
+- Gemini 3 models: set `GOOGLE_GENAI_API_KEY` (or `GEMINI_API_KEY`).
+
+1) From your project root, run `tc specgen --src ./src --out ./features` (or `npx tc specgen ...` if installed locally). If you omit `--out`, it defaults to `./features`.  
+2) Point `--src` at the codebase you want crawled; point `--out` at where you want the generated `.feature` files to land.  
+3) Review the generated Gherkin, adjust wording/step names to match your domain language, then commit.
+
+### Dev workspace example
+From a workspace root with `tc-cli` installed locally:
+```bash
+cd tc-cli
+ANTHROPIC_API_KEY=... node ./src/index.js specgen --src ../qac_widget/src --out ../qac_widget/features --cache ../qac_widget/.testcollab/specgen.json --model claude-opus-4-5-20251101
+```
+Swap `--model` to a Gemini model (e.g., `gemini-2.0-pro`) and set `GOOGLE_GENAI_API_KEY` instead if you prefer Gemini.
+
+## Quality checks
+
+- **Small codebase (20–30 project files):** Quick skim of every generated `.feature` file, remove obvious duplicates, tighten scenario names, and ensure steps mirror the real user flows.
+
+- **Medium & large (30+ source files):** Generate per module/folder to control noise, spot-check high-traffic paths first, dedupe cross-module scenarios, and keep a short backlog of follow-up edits for any low-confidence sections marked by the generator.
+
+    "@anthropic-ai/sdk": "^0.71.0",
+    "@google/generative-ai": "^0.11.0",

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@testcollab/cli",
+  "version": "1.3.0",
+  "description": "Command-line interface for TestCollab operations",
+  "main": "src/index.js",
+  "bin": {
+    "tc": "./src/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "NODE_OPTIONS=\"--experimental-vm-modules\" jest"
+  },
+  "jest": {
+    "testEnvironment": "node"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "keywords": [
+    "testcollab",
+    "testing",
+    "bdd",
+    "gherkin",
+    "cli"
+  ],
+  "author": "TestCollab",
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.71.2",
+    "@cucumber/gherkin": "^33.1.0",
+    "@cucumber/messages": "^28.1.0",
+    "@google/generative-ai": "^0.24.1",
+    "commander": "^11.1.0",
+    "simple-git": "^3.28.0",
+    "testcollab-cypress-plugin": "^1.0.3",
+    "testcollab-sdk": "^2.1.1-SNAPSHOT.202509242236"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TCSoftInc/testcollab-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/TCSoftInc/testcollab-cli/issues"
+  },
+  "homepage": "https://github.com/TCSoftInc/testcollab-cli#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public",
+    "provenance": true
+  }
+}

package/samples/reports/junit.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<testsuites name="TestCollab CLI Sample JUnit">
+  <testsuite name="Authentication" tests="3" failures="1" skipped="1" time="0.62">
+    <testcase classname="Authentication.Login" name="[TC-1913] should login with valid credentials" time="0.12" />
+    <testcase classname="Authentication.Login" name="[TC-1914] should reject invalid password" time="0.43">
+      <failure message="Expected invalid password error">AssertionError: expected status 401 but got 200</failure>
+    </testcase>
+    <testcase classname="Authentication.Login" name="[TC-1915] should support SSO login" time="0.07">
+      <skipped />
+    </testcase>
+  </testsuite>
+</testsuites>