codebyplan 1.11.1 → 1.11.2

package/templates/skills/cbp-e2e-setup/reference/maestro.md

@@ -0,0 +1,200 @@
+# Maestro Reference
+
+Full install, config, flows, and CI walkthrough for Maestro on an Expo/React Native project.
+Source: vendor/maestro/v2.6 + `.claude/context/testing/e2e.md`.
+
+## Prerequisites
+
+- Java 17 or later: `java -version` (install via `brew install openjdk@17` on macOS)
+- Android emulator (for android targets) or iOS Simulator (for ios targets)
+- Expo app bundled and running on the target device/emulator
+
+## Install
+
+```bash
+# macOS — recommended
+curl -fsSL "https://get.maestro.mobile.dev" | bash
+
+# Alternative: Homebrew tap
+brew tap mobile-dev-inc/tap
+brew install maestro
+```
+
+Verify:
+
+```bash
+maestro --version
+```
+
+Update later with: `maestro upgrade`
+
+## maestro/config.yaml
+
+Create at repo root under `maestro/config.yaml`:
+
+```yaml
+# Maestro workspace configuration
+# See: https://docs.maestro.dev/maestro-flows/workspace-management/repository-configuration
+
+appId: com.yourorg.yourapp   # must match app.config.ts / expo config
+env:
+  TEST_EMAIL: ${TEST_EMAIL}
+  TEST_PASSWORD: ${TEST_PASSWORD}
+  APP_ID: com.yourorg.yourapp
+```
+
+`appId` must match the value in `app.config.ts` `ios.bundleIdentifier` /
+`android.package`. If they differ across platforms, use the Android package ID for
+Maestro's `appId` on Android and the iOS bundle ID on iOS tests.
+
+## Shared login flow
+
+Create `maestro/flows/_shared/login.yaml`:
+
+```yaml
+appId: ${APP_ID}
+---
+- launchApp:
+    clearState: true
+- assertVisible: "Sign in"
+- tapOn: "Email"
+- inputText: ${TEST_EMAIL}
+- tapOn: "Password"
+- inputText: ${TEST_PASSWORD}
+- tapOn: "Sign in"
+- assertVisible:
+    text: ".*"        # Replace with a post-login element (e.g. "Dashboard")
+    timeout: 15000
+```
+
+Reference it from any other flow:
+
+```yaml
+- runFlow: _shared/login.yaml
+```
+
+## Auth probe flow
+
+`maestro/flows/_probe/auth.yaml` — minimal login verification:
+
+```yaml
+appId: ${APP_ID}
+tags:
+  - probe
+---
+- launchApp:
+    clearState: true
+- assertVisible: "Sign in"
+- tapOn: "Email"
+- inputText: ${TEST_EMAIL}
+- tapOn: "Password"
+- inputText: ${TEST_PASSWORD}
+- tapOn: "Sign in"
+- assertVisible:
+    text: ".*"
+    timeout: 15000
+```
+
+Run the probe before the full suite: `maestro test maestro/flows/_probe/auth.yaml`
+
+## Platform targeting
+
+Maestro v2.6 exposes `-p` / `--platform` as a global option (placed BEFORE the `test`
+subcommand). Values: `android`, `ios`, or `web`.
+
+Run on Android: start an Android emulator, then
+
+```bash
+maestro --platform=android test maestro/flows/
+```
+
+Run on iOS: boot an iOS Simulator, then
+
+```bash
+maestro --platform=ios test maestro/flows/
+```
+
+Omitting the flag is also valid — platform is then implicit from whichever single
+emulator/simulator is currently running.
+
+Target a specific device by UDID / emulator name:
+
+```bash
+maestro test --device <device-id> maestro/flows/
+```
+
+## Directory structure
+
+```
+maestro/
+  config.yaml
+  flows/
+    _shared/
+      login.yaml
+      open-side-menu.yaml
+    _probe/
+      auth.yaml
+    onboarding/
+      signup.yaml
+    home/
+      dashboard.yaml
+```
+
+One subdirectory per app module under `maestro/flows/`. Shared flows under `_shared/`.
+
+## Screenshots
+
+```yaml
+- takeScreenshot: "after-login"
+```
+
+Configure a repo-local screenshots path in `maestro/config.yaml`:
+
+```yaml
+screenshotsDir: maestro/screenshots
+```
+
+## pnpm scripts
+
+Add to root `package.json`:
+
+```json
+{
+  "scripts": {
+    "maestro:test": "maestro test maestro/flows/",
+    "maestro:test:probe": "maestro test maestro/flows/_probe/",
+    "maestro:studio": "maestro studio"
+  }
+}
+```
+
+## CI (GitHub Actions)
+
+Maestro CI runs require a connected device. For GitHub Actions use
+[Maestro Cloud](https://cloud.maestro.dev) or a self-hosted runner with a connected
+device. A minimal Maestro Cloud step:
+
+```yaml
+- name: Run Maestro flows
+  uses: mobile-dev-inc/action-maestro-cloud@v1
+  with:
+    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}
+    app-file: path/to/app.apk   # or .ipa
+    flow-file: maestro/flows/
+  env:
+    TEST_EMAIL: ${{ secrets.TEST_EMAIL }}
+    TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
+```
+
+For local self-hosted runner, set `TEST_EMAIL` and `TEST_PASSWORD` as runner env vars.
+
+## Pitfalls
+
+**App ID mismatch** — `appId` in config.yaml must exactly match the compiled bundle
+identifier. Re-run `expo prebuild` if you changed the identifier after prebuild.
+
+**clearState: true** — always clear app state in `launchApp` for the login flow so
+each run starts from a signed-out state.
+
+**Java version** — Maestro requires Java 17+. If `maestro --version` fails, check
+`JAVA_HOME` or install via Homebrew.

package/templates/skills/cbp-e2e-setup/reference/playwright.md

@@ -0,0 +1,212 @@
+# Playwright Reference
+
+Full install, config, auth, and CI walkthrough for Playwright on a Next.js monorepo.
+Source: vendor/playwright/v1.60 + `.claude/context/testing/e2e.md`.
+
+## Install
+
+```bash
+pnpm add -D @playwright/test
+pnpm exec playwright install chromium
+```
+
+For CI with system dependencies:
+
+```bash
+pnpm exec playwright install --with-deps chromium
+```
+
+## playwright.config.ts
+
+Derive `baseURL` from `.codebyplan/server.json` at config-read time:
+
+```ts
+import { defineConfig, devices } from "@playwright/test";
+import { execSync } from "child_process";
+import path from "path";
+
+// Pull the Web Dev port from server.json so config stays in sync. Match by label
+// rather than server_type — a repo can have several nextjs allocations, so
+// array-position head -1 is not stable.
+function getBaseUrl(): string {
+  try {
+    const raw = execSync(
+      "jq -r '.port_allocations[] | select(.label==\"Web Dev\") | .port' .codebyplan/server.json 2>/dev/null | head -1",
+      { encoding: "utf-8" }
+    ).trim();
+    const port = parseInt(raw, 10);
+    return `http://localhost:${port}`;
+  } catch {
+    return "http://localhost:3010"; // fallback
+  }
+}
+
+export default defineConfig({
+  testDir: "apps/web/e2e",
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: 1, // serialize against shared remote Supabase — see e2e.md § Supabase Parallelism
+  reporter: process.env.CI ? "github" : "html",
+  globalSetup: "./apps/web/e2e/global-setup", // string path — resolved relative to config; safe under ESM
+  use: {
+    baseURL: getBaseUrl(),
+    trace: "on-first-retry",
+    screenshot: "only-on-failure",
+  },
+  projects: [
+    { name: "setup", testMatch: /global\.setup\.ts/ },
+    {
+      name: "web",
+      use: { ...devices["Desktop Chrome"], storageState: "apps/web/e2e/.auth/user.json" },
+      dependencies: ["setup"],
+    },
+  ],
+  webServer: {
+    command: "pnpm --filter @codebyplan/web dev",
+    url: getBaseUrl(),
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+  },
+});
+```
+
+Key options:
+
+| Option | Why |
+| --- | --- |
+| `workers: 1` | Prevents auth/RLS races on a shared remote Supabase project |
+| `globalSetup` | Logs in once, writes `storageState` so tests start authenticated |
+| `reuseExistingServer` | Skip dev-server startup when already running locally |
+
+## Auth — global setup + storage state
+
+Create `apps/web/e2e/global-setup.ts`:
+
+```ts
+import { chromium, FullConfig } from "@playwright/test";
+import path from "path";
+
+const AUTH_FILE = path.join(__dirname, ".auth/user.json");
+
+export default async function globalSetup(config: FullConfig) {
+  const email = process.env.E2E_TEST_EMAIL;
+  const password = process.env.E2E_TEST_PASSWORD;
+
+  if (!email || !password) {
+    throw new Error(
+      "E2E_TEST_EMAIL and E2E_TEST_PASSWORD must be set.\n" +
+        "Copy .env.local.example to .env.local, then run: pnpm e2e:provision"
+    );
+  }
+
+  const { baseURL } = config.projects[0].use;
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  await page.goto(`${baseURL}/login`);
+  await page.getByLabel(/email/i).fill(email);
+  await page.getByLabel(/password/i).fill(password);
+  await page.getByRole("button", { name: /sign in|log in/i }).click();
+  await page.waitForURL(/\/(dashboard|home|app)/, { timeout: 15_000 });
+
+  // Warm up the first route to avoid cold-start timeouts in specs
+  await page.goto(baseURL!);
+  await page.context().storageState({ path: AUTH_FILE });
+  await browser.close();
+}
+```
+
+Gitignore the auth state — run before first use:
+
+```bash
+mkdir -p apps/web/e2e/.auth
+echo "apps/web/e2e/.auth/" >> .gitignore
+```
+
+## Auth probe spec
+
+`apps/web/e2e/_probe/auth.spec.ts` — validates the login path directly (outside
+storage-state flow) so credential failures are diagnosed cleanly:
+
+```ts
+import { test, expect } from "@playwright/test";
+
+test("auth probe: can log in with E2E_TEST_EMAIL/E2E_TEST_PASSWORD", async ({
+  page,
+}) => {
+  const email = process.env.E2E_TEST_EMAIL;
+  const password = process.env.E2E_TEST_PASSWORD;
+  expect(email, "E2E_TEST_EMAIL env var is required").toBeTruthy();
+  expect(password, "E2E_TEST_PASSWORD env var is required").toBeTruthy();
+
+  await page.goto("/login");
+  await page.getByLabel(/email/i).fill(email!);
+  await page.getByLabel(/password/i).fill(password!);
+  await page.getByRole("button", { name: /sign in|log in/i }).click();
+
+  await expect(page).toHaveURL(/\/(dashboard|home|app)/, { timeout: 15_000 });
+});
+```
+
+Run the probe before the full suite: `pnpm exec playwright test --project=web _probe/auth`.
+
+## Provision script convention
+
+Every repo with Playwright auth ships `scripts/provision-e2e-user.ts` — an idempotent
+script that creates the test user in the dev Supabase project. Wire it to `package.json`:
+
+```json
+{
+  "scripts": {
+    "e2e:provision": "tsx scripts/provision-e2e-user.ts"
+  }
+}
+```
+
+The skill records the path; the repo author writes the script. See
+`.claude/context/testing/e2e.md` § Provisioning Playwright credentials for the full
+contract (idempotency, multi-tenant subdomain, `.env.local.example`).
+
+## CI secrets
+
+Add these four secrets to the GitHub repo (Settings → Secrets → Actions):
+
+| Secret | Purpose |
+| --- | --- |
+| `E2E_TEST_EMAIL` | Test account email |
+| `E2E_TEST_PASSWORD` | Test account password |
+| `NEXT_PUBLIC_SUPABASE_URL` | Supabase project URL |
+| `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` | Supabase publishable (anon) key |
+
+## GitHub Actions snippet
+
+```yaml
+- name: Install Playwright browsers
+  run: pnpm exec playwright install --with-deps chromium
+
+- name: Run Playwright tests
+  run: pnpm exec playwright test
+  env:
+    E2E_TEST_EMAIL: ${{ secrets.E2E_TEST_EMAIL }}
+    E2E_TEST_PASSWORD: ${{ secrets.E2E_TEST_PASSWORD }}
+    NEXT_PUBLIC_SUPABASE_URL: ${{ secrets.NEXT_PUBLIC_SUPABASE_URL }}
+    NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY: ${{ secrets.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY }}
+```
+
+## Pitfalls
+
+**Cold-start timeouts** — Next.js dev mode compiles routes lazily. The warmup fetch in
+`globalSetup` (after `page.goto(baseURL!)`) primes the compiler before specs run.
+
+**SCSS Module selectors** — prefer `[class*='componentName']` with `.first()` over
+positional `.nth(N)` locators. Prefer `getByRole`/`getByLabel`/`getByTestId` when
+accessible names are available.
+
+**SCSS import errors in tests** — Playwright runs in Node, not webpack. If your test
+imports a component that imports SCSS, configure `playwright.config.ts` to use
+`@playwright/test`'s built-in transform or exclude such imports.
+
+**Port mismatch** — before running, compare `playwright.config.ts` `baseURL` port with
+`.codebyplan/server.json`. On mismatch, the `cbp-e2e-playwright` agent will ask which is
+correct — do not guess.

package/templates/skills/cbp-e2e-setup/reference/tauri.md

@@ -0,0 +1,147 @@
+# Tauri Reference
+
+Full install, config, and test walkthrough for Tauri desktop apps using WebDriverIO +
+tauri-driver. Source: upstream WebDriverIO docs + `.claude/context/testing/e2e.md`.
+
+## Prerequisites
+
+- Rust toolchain: `rustup --version` (install via https://rustup.rs)
+- `tauri-driver` binary: installed via Cargo (see Install below)
+- Built Tauri binary: `cargo build` must complete before any tests run
+- Node.js / pnpm available
+
+## Install
+
+```bash
+# WebDriverIO runner + framework
+pnpm add -D @wdio/cli @wdio/local-runner @wdio/mocha-framework @wdio/spec-reporter
+
+# Tauri driver (native binary — needs Cargo)
+cargo install tauri-driver
+```
+
+Verify:
+
+```bash
+which tauri-driver
+tauri-driver --version
+```
+
+## wdio.conf.ts
+
+Place at `apps/desktop/wdio.conf.ts` (or repo root for single-app repos):
+
+```ts
+import { spawn, spawnSync } from "child_process";
+import type { Options } from "@wdio/types";
+
+// Path to your built Tauri binary
+const BINARY_PATH = "./src-tauri/target/debug/your-app-name";
+
+let tauriDriver: ReturnType<typeof spawn>;
+
+export const config: Options.Testrunner = {
+  specs: ["./e2e/**/*.spec.ts"],
+  maxInstances: 1,
+  capabilities: [
+    {
+      "tauri:options": { application: BINARY_PATH },
+      maxInstances: 1,
+    },
+  ],
+  services: ["chromedriver"],
+  framework: "mocha",
+  reporters: ["spec"],
+  mochaOpts: { timeout: 60_000 },
+
+  beforeSession: async () => {
+    // Start tauri-driver before each session
+    tauriDriver = spawn("tauri-driver", [], {
+      stdio: [null, process.stdout, process.stderr],
+    });
+  },
+
+  afterSession: async () => {
+    // Kill tauri-driver after each session
+    tauriDriver.kill();
+  },
+};
+```
+
+## Build before running
+
+Tests will fail if the binary is stale or absent. Always build before running tests:
+
+```bash
+# Build the Tauri app
+cargo build --manifest-path apps/desktop/src-tauri/Cargo.toml
+
+# Then run WebDriverIO
+pnpm --filter @codebyplan/desktop wdio run wdio.conf.ts
+```
+
+Or as a combined pnpm script:
+
+```json
+{
+  "scripts": {
+    "e2e": "cargo build --manifest-path src-tauri/Cargo.toml && wdio run wdio.conf.ts",
+    "e2e:test": "wdio run wdio.conf.ts"
+  }
+}
+```
+
+## Writing tests
+
+Use `data-testid` attributes for stable targeting (Tauri WebView renders HTML):
+
+```ts
+import { browser, $ } from "@wdio/globals";
+import { expect } from "@wdio/globals";
+
+describe("Desktop app", () => {
+  it("opens the main window", async () => {
+    const navBar = await $("[data-testid='nav']");
+    await expect(navBar).toBeDisplayed();
+  });
+
+  it("navigates to settings", async () => {
+    await $("[data-testid='settings-link']").click();
+    await expect($("[data-testid='settings-panel']")).toBeDisplayed();
+  });
+});
+```
+
+Prefer `data-testid` over CSS class selectors — SCSS Modules mangle class names.
+
+## Auth probe
+
+`apps/desktop/e2e/_probe/auth.spec.ts`:
+
+```ts
+import { browser, $ } from "@wdio/globals";
+import { expect } from "@wdio/globals";
+
+describe("auth probe", () => {
+  it("can reach the main window", async () => {
+    // Tauri desktop apps often skip network auth — adapt if your app has auth
+    const root = await $("[data-testid='app-root']");
+    await expect(root).toBeDisplayed();
+  });
+});
+```
+
+## Pitfalls
+
+**Must build before run** — tauri-driver launches the binary; if the binary doesn't
+exist or is stale the session fails immediately with a confusing error.
+
+**Binary path** — the `application` path in `capabilities` must be the exact path
+to the compiled binary. Debug builds are under `src-tauri/target/debug/`, release
+builds under `src-tauri/target/release/`.
+
+**Port conflicts** — tauri-driver listens on port 4444 by default. Ensure no other
+WebDriver session is running on the same port.
+
+**CI** — Tauri desktop E2E on CI requires a display (Xvfb on Linux) and the full Rust
+build toolchain. Use GitHub-hosted `ubuntu-latest` or `macos-latest` runners.

package/templates/skills/cbp-e2e-setup/reference/vscode.md

@@ -0,0 +1,154 @@
+# VS Code Extension Reference
+
+Full install, config, and test walkthrough for VS Code extension testing using
+`@vscode/test-cli` and `@vscode/test-electron`. Source: upstream VS Code extension
+testing docs.
+
+## Prerequisites
+
+- VS Code installed (used as the test host)
+- Node.js / pnpm available
+- On Linux CI: Xvfb for a display server (extensions require a GUI)
+
+## Install
+
+```bash
+pnpm add -D @vscode/test-cli @vscode/test-electron
+```
+
+Verify:
+
+```bash
+pnpm exec vscode-test --version
+```
+
+## .vscode-test.mjs
+
+Create `.vscode-test.mjs` at the extension package root (e.g. `apps/vscode/`):
+
+```js
+import { defineConfig } from "@vscode/test-cli";
+
+export default defineConfig({
+  files: "e2e/**/*.test.js",      // compiled output path (JS, not TS)
+  extensionDevelopmentPath: ".",  // path to the extension package root
+  workspaceFolder: "test-fixtures/workspace", // optional: open a fixture workspace
+  mocha: {
+    timeout: 20_000,
+    ui: "bdd",
+  },
+});
+```
+
+For TypeScript source, compile tests before running:
+
+```json
+{
+  "scripts": {
+    "test:e2e": "tsc -p tsconfig.test.json && vscode-test",
+    "test:e2e:watch": "vscode-test --watch"
+  }
+}
+```
+
+## Extension host lifecycle
+
+`@vscode/test-electron` downloads an isolated VS Code instance, installs your extension,
+opens the workspace, and runs the Mocha suite inside the extension host process.
+
+Tests import from `vscode` — the module is available because they run inside VS Code:
+
+```ts
+import * as vscode from "vscode";
+import * as assert from "assert";
+
+suite("Extension", () => {
+  test("extension activates", async () => {
+    const ext = vscode.extensions.getExtension("yourpublisher.yourextension");
+    assert.ok(ext, "extension not found");
+    await ext.activate();
+    assert.ok(ext.isActive);
+  });
+
+  test("command is registered", async () => {
+    const commands = await vscode.commands.getCommands();
+    assert.ok(
+      commands.includes("yourextension.yourCommand"),
+      "command not registered"
+    );
+  });
+});
+```
+
+The test file runs inside the VS Code extension host — full `vscode` API is available,
+including workspace, editors, commands, and diagnostics.
+
+## Directory structure
+
+```
+apps/vscode/
+  .vscode-test.mjs
+  e2e/
+    _probe/
+      activation.test.ts
+    commands/
+      my-command.test.ts
+  test-fixtures/
+    workspace/          # optional: committed fixture files opened in tests
+```
+
+## Activation probe
+
+`apps/vscode/e2e/_probe/activation.test.ts`:
+
+```ts
+import * as vscode from "vscode";
+import * as assert from "assert";
+
+suite("Activation probe", () => {
+  test("extension activates without error", async () => {
+    // Replace with your publisher.extensionname from package.json
+    const ext = vscode.extensions.getExtension("yourpublisher.yourextension");
+    assert.ok(ext, "Extension not installed in test host");
+    if (!ext.isActive) {
+      await ext.activate();
+    }
+    assert.ok(ext.isActive, "Extension did not activate");
+  });
+});
+```
+
+## CI (GitHub Actions)
+
+Linux runners require Xvfb. Use the `xvfb-run` wrapper:
+
+```yaml
+- name: Install dependencies
+  run: pnpm install
+
+- name: Compile extension tests
+  run: pnpm --filter @codebyplan/vscode test:compile
+
+- name: Run VS Code extension tests
+  run: xvfb-run -a pnpm --filter @codebyplan/vscode test:e2e
+  env:
+    DISPLAY: ':99.0'
+```
+
+On macOS/Windows runners, Xvfb is not needed — `vscode-test` uses the native display.
+
+## Pitfalls
+
+**Wrong extensionDevelopmentPath** — if the path in `.vscode-test.mjs` doesn't point
+to the package root (where `package.json` has the `contributes` block), VS Code won't
+find the extension and activation tests will fail silently.
+
+**TypeScript source vs compiled output** — `@vscode/test-cli` runs compiled JS.
+Always compile before invoking `vscode-test` in CI.
+
+**Extension host isolation** — each test run downloads a fresh VS Code binary into a
+temp dir. This is intentional; do not try to reuse the system VS Code installation.
+
+**`vscode` module availability** — tests run inside the extension host, so `import
+* as vscode from "vscode"` resolves correctly. The same import will fail if you try
+to run these files with plain Node.js outside the host.