@timetotest/cli 0.1.1

package/README.md

@@ -0,0 +1,263 @@
+### Time to Test CLI (`@timetotest/cli`)
+
+AI-powered web testing from your terminal. Start tests against your app, stream real-time progress, and download shareable reports.
+
+## Quick Start
+
+1. Log in
+
+```bash
+ttt login
+```
+
+2. Start a test
+
+- Easiest (no URL needed, uses your project’s saved URL):
+
+```bash
+ttt start-test "Smoke test the main user journey" --execute --wait
+```
+
+- With an explicit URL:
+
+```bash
+ttt test --url https://your-app.com --type ui --execute --wait
+```
+
+3. Chat with the agent
+
+```bash
+ttt ask
+```
+
+Tips:
+
+- Use `--report [path]` to download a PDF when the test completes
+- Use `--share` to enable a public share link
+- Use `ttt stream <test-id>` to reattach to progress later
+
+- **Node requirement**: 18+
+- **Website**: [Time to Test](https://timetotest.tech)
+
+## Installation
+
+```bash
+npm i -g @timetotest/cli
+# or use npx without global install
+npx @timetotest/cli --help
+```
+
+## Quick Start
+
+1. Authenticate
+
+```bash
+ttt login
+# Opens a browser to authenticate. As a fallback, you may be prompted to paste a short-lived token.
+```
+
+2. Run a UI test against a local app
+
+```bash
+ttt test \
+  --url http://localhost:3000 \
+  --type ui \
+  --execute \
+  --mode priority \
+  --project-id 123 \
+  --team-id 456 \
+  --report ./report.pdf \
+  --wait
+```
+
+The CLI will automatically start an ngrok tunnel for local URLs and stream progress via Socket.IO.
+
+## Authentication
+
+- **Interactive**: `ttt login` opens the browser and stores a Firebase ID token in `~/.timetotest/config.json`.
+- **Headless/CI**: Use Firebase Email/Password (service user):
+
+```bash
+ttt login --email "$TTT_EMAIL" --password "$TTT_PASSWORD" --api-key "$TTT_FIREBASE_API_KEY"
+```
+
+- **Direct token**: `ttt login --token <FIREBASE_ID_TOKEN>`
+- **Env override**: Set `TTT_TOKEN` to inject the token for one-off runs.
+
+## Commands
+
+- **ttt login**
+
+  - Options:
+    - `--device` (reserved)
+    - `--email <email> --password <password> --api-key <firebase-web-api-key>`
+    - `--token <FIREBASE_ID_TOKEN>`
+
+- **ttt test**
+
+  - Starts a test and subscribes to real-time events.
+  - Key options:
+    - `--url <ui-url>`: app URL under test (required for UI/mixed)
+    - `--type <ui|api|mixed>`: defaults to `ui`
+    - `--execute`: execute generated test cases
+    - `--mode <all|priority|failed_only>`: defaults to `priority`
+    - `--project-id <id>` / `--team-id <id>`
+    - `--docs-url <openapi-url>`: API docs (OpenAPI/Swagger)
+    - `--no-tunnel`: disable auto ngrok tunnel for local URLs
+    - `--report [path]`: download PDF on completion (default `./report-<id>.pdf`)
+    - `--share`: enable public sharing after completion
+    - `--wait`: block until completion and set exit code based on result
+
+- **ttt start-test <prompt>**
+
+  - Start a test from a natural language prompt. The backend derives the URL from your selected/last project, so you don't need to pass `--url`.
+  - Examples:
+    ```bash
+    ttt start-test "Smoke test the main user journey and generate a PDF report" --execute --wait
+    ttt start-test "API regression for orders endpoints" --type api --docs-url https://api.example.com/openapi.json --execute
+    ```
+  - Options:
+    - `--type <ui|api|mixed>`: defaults to `ui`
+    - `--execute`: execute generated test cases
+    - `--mode <all|priority|failed_only>`: defaults to `priority`
+    - `--project-id <id>` / `--team-id <id>`
+    - `--docs-url <openapi-url>`: API docs (OpenAPI/Swagger)
+    - `--report [path]`: download PDF on completion (default `./report-<id>.pdf`)
+    - `--share`: enable public sharing after completion
+    - `--wait`: block until completion and set exit code based on result
+
+- **ttt stream <test-id>**
+
+  - Attach to an existing test and print textual progress only.
+
+- **ttt status <test-id>**
+
+  - Print the test status JSON.
+
+- **ttt restart <test-id>**
+
+  - Re-run a completed or failed test.
+
+- **ttt report <test-id> --out <file.pdf>**
+
+  - Create (if needed) and download a PDF report.
+
+- **ttt share <test-id>**
+  - Enable public sharing and print the public URL.
+
+## Real-time Streaming
+
+The CLI connects to Socket.IO at `/socket.io` and emits `subscribe_test` with the test ID. It prints minimal, time-stamped lines for events like `test_started`, `test_progress`, `test_completed`, `test_failed`.
+
+If websockets are blocked, use `ttt status <id>` to poll.
+
+## Tunnels (Local URLs)
+
+When `--url` (or `--docs-url`) points to `localhost`/`127.0.0.1`, the CLI auto-starts an ngrok tunnel and injects the public URL into the request. For reliability, provide an ngrok authtoken:
+
+```bash
+export TTT_NGROK_AUTHTOKEN=... # optional but recommended
+```
+
+## Configuration
+
+- **Precedence**: CLI flags > environment variables > config file.
+- **Config file**: `~/.timetotest/config.json`
+
+Example (values are examples; your file will reflect your environment):
+
+```json
+{
+  "apiUrl": "https://api.timetotest.tech",
+  "socketUrl": "https://api.timetotest.tech",
+  "auth": {"firebaseIdToken": "...", "expiresAt": 0},
+  "defaultProjectId": null,
+  "defaultTeamId": null,
+  "ngrok": {"authtoken": null}
+}
+```
+
+## Environment Variables
+
+- `TTT_API_URL` – override API base URL
+- `TTT_SOCKET_URL` – override Socket.IO base URL
+- `TTT_TOKEN` – Firebase ID token (overrides stored token)
+- `TTT_NGROK_AUTHTOKEN` – ngrok account token
+
+## GitHub Actions (Example)
+
+```yaml
+name: Time to Test
+on:
+  push:
+    branches: [main]
+
+jobs:
+  ttt:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install CLI
+        run: npm i -g @timetotest/cli
+
+      - name: Start App Under Test
+        run: |
+          npm ci
+          npm run build --if-present
+          npm start &
+          echo $! > app.pid
+          npx wait-on http://localhost:3000
+
+      - name: CLI Login (headless)
+        env:
+          TTT_EMAIL: ${{ secrets.TTT_EMAIL }}
+          TTT_PASSWORD: ${{ secrets.TTT_PASSWORD }}
+          TTT_FIREBASE_API_KEY: ${{ secrets.TTT_FIREBASE_API_KEY }}
+        run: ttt login --email "$TTT_EMAIL" --password "$TTT_PASSWORD" --api-key "$TTT_FIREBASE_API_KEY"
+
+      - name: Run Test
+        env:
+          TTT_API_URL: https://dev.timetotest.kinra.ng
+          TTT_SOCKET_URL: https://dev.timetotest.kinra.ng
+          TTT_NGROK_AUTHTOKEN: ${{ secrets.NGROK_AUTHTOKEN }}
+        run: |
+          ttt test \
+            --url http://localhost:3000 \
+            --type ui \
+            --execute \
+            --mode priority \
+            --project-id 123 \
+            --team-id 456 \
+            --report ./report.pdf \
+            --wait
+
+      - name: Upload Report (PDF)
+        uses: actions/upload-artifact@v4
+        with:
+          name: timetotest-report
+          path: ./report.pdf
+
+      - name: Stop App
+        if: always()
+        run: kill $(cat app.pid) || true
+```
+
+## Troubleshooting
+
+- **401 Unauthorized**: run `ttt login` again or set `TTT_TOKEN`.
+- **Tunnel issues**: set `TTT_NGROK_AUTHTOKEN`, ensure your local app is running and reachable.
+- **Socket blocked**: use `ttt status <id>` for polling.
+- **PDF not saving**: ensure the output path is writable.
+
+## Privacy & Security
+
+- Your token is stored in `~/.timetotest/config.json` with restricted permissions.
+- The CLI avoids logging secrets; still, prefer not to paste sensitive URLs directly in shared logs.
+
+## Feedback
+
+We’d love to hear from you. Visit [Time to Test](https://timetotest.tech) for updates and support.

package/dist/bin/ttt.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { login } from "../src/commands/login.js";
+import { test } from "../src/commands/test.js";
+import { status } from "../src/commands/status.js";
+import { restart } from "../src/commands/restart.js";
+import { stream } from "../src/commands/stream.js";
+import { report } from "../src/commands/report.js";
+import { share } from "../src/commands/share.js";
+import { ask } from "../src/commands/ask.js";
+import { startTest } from "../src/commands/start-test.js";
+import { applyStyledHelpRecursively } from "../src/lib/help.js";
+const program = new Command();
+program.name("ttt").description("Time to Test CLI").version("0.1.0");
+program.addCommand(login);
+program.addCommand(test);
+program.addCommand(status);
+program.addCommand(restart);
+program.addCommand(stream);
+program.addCommand(report);
+program.addCommand(share);
+program.addCommand(ask);
+program.addCommand(startTest);
+applyStyledHelpRecursively(program, "ttt");
+// Default to `ask` when no subcommand is provided
+if (process.argv.length <= 2) {
+    process.argv.push("ask");
+}
+program.parseAsync(process.argv);
+//# sourceMappingURL=ttt.js.map

package/dist/bin/ttt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ttt.js","sourceRoot":"","sources":["../../bin/ttt.ts"],"names":[],"mappings":";AACA,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAClC,OAAO,EAAC,KAAK,EAAC,MAAM,0BAA0B,CAAC;AAC/C,OAAO,EAAC,IAAI,EAAC,MAAM,yBAAyB,CAAC;AAC7C,OAAO,EAAC,MAAM,EAAC,MAAM,2BAA2B,CAAC;AACjD,OAAO,EAAC,OAAO,EAAC,MAAM,4BAA4B,CAAC;AACnD,OAAO,EAAC,MAAM,EAAC,MAAM,2BAA2B,CAAC;AACjD,OAAO,EAAC,MAAM,EAAC,MAAM,2BAA2B,CAAC;AACjD,OAAO,EAAC,KAAK,EAAC,MAAM,0BAA0B,CAAC;AAC/C,OAAO,EAAC,GAAG,EAAC,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAC,SAAS,EAAC,MAAM,+BAA+B,CAAC;AACxD,OAAO,EAAC,0BAA0B,EAAC,MAAM,oBAAoB,CAAC;AAE9D,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAC9B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AAErE,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;AAC1B,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACzB,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;AAC3B,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;AAC5B,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;AAC3B,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;AAC3B,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;AAC1B,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AACxB,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;AAE9B,0BAA0B,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AAC3C,kDAAkD;AAClD,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;IAC7B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AACD,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC"}