🛠️ chore(agent-testing): add local dev env bootstrap (#15757)

2026-06-14 03:30:19 +00:00 · 2026-06-13 13:54:13 +08:00
parent fa76928f62
commit be7b759820
4 changed files with 397 additions and 3 deletions
@@ -55,7 +55,94 @@ directory — a script launched while `cwd` is `apps/desktop` fails with
 `No such file or directory`. Verify `pwd` is the repo root before launching
 long-running scripts.

-### 0.3 Auth is green
+### 0.3 Init local dev env without `.env`
+
+For Web smoke against local code, start a **normal local dev environment**.
+First check the repo root for `.env`:
+
+- If `.env` exists, use the existing local configuration and start the dev
+  server normally.
+- If `.env` does not exist, use the agent-testing env bootstrap.
+
+Do not start the standalone e2e server as the product under test.
+
+Use `scripts/init-dev-env.sh`. It follows the e2e setup pattern — Postgres,
+migrations, auth/key-vault/S3 test env, seed user — but it is owned by this
+skill and starts the repo's dev server (`pnpm run dev:next` / `bun run dev`),
+not `e2e/scripts/setup.ts --start`. The script hard-blocks when root `.env`
+exists, so it cannot accidentally override a user's local config. When `.env`
+exists, do not call any `init-dev-env.sh` subcommand.
+
+Decision flow:
+
+```bash
+if [[ -f .env ]]; then
+  bun run dev
+else
+  ./.agents/skills/agent-testing/scripts/init-dev-env.sh setup-db
+  ./.agents/skills/agent-testing/scripts/init-dev-env.sh seed-user
+  ./.agents/skills/agent-testing/scripts/init-dev-env.sh dev
+fi
+```
+
+Bootstrap flow when no `.env` exists:
+
+```bash
+# From repo root. Managed DB flow requires Docker Desktop.
+./.agents/skills/agent-testing/scripts/init-dev-env.sh setup-db
+./.agents/skills/agent-testing/scripts/init-dev-env.sh seed-user
+./.agents/skills/agent-testing/scripts/init-dev-env.sh dev
+```
+
+If using an existing Postgres instead of the managed Docker DB, set
+`DATABASE_URL` and skip `setup-db`:
+
+```bash
+DATABASE_URL=postgresql://... ./.agents/skills/agent-testing/scripts/init-dev-env.sh migrate
+DATABASE_URL=postgresql://... ./.agents/skills/agent-testing/scripts/init-dev-env.sh seed-user
+DATABASE_URL=postgresql://... ./.agents/skills/agent-testing/scripts/init-dev-env.sh dev
+```
+
+For backend-only checks, `dev-next` is available, but Web smoke needs the
+full-stack `dev` command so Next can proxy the SPA HTML from Vite:
+
+```bash
+./.agents/skills/agent-testing/scripts/init-dev-env.sh dev-next
+```
+
+Useful subcommands:
+
+```bash
+./.agents/skills/agent-testing/scripts/init-dev-env.sh env      # print exports
+./.agents/skills/agent-testing/scripts/init-dev-env.sh write    # write .records/env/agent-testing-dev.env
+./.agents/skills/agent-testing/scripts/init-dev-env.sh migrate  # migrations only
+./.agents/skills/agent-testing/scripts/init-dev-env.sh clean-db # remove managed DB container
+```
+
+Default script env:
+
+- `APP_URL=http://localhost:3010`
+- `DATABASE_URL=postgresql://postgres:postgres@localhost:5433/postgres`
+- `DATABASE_DRIVER=node`
+- `FEATURE_FLAGS=-agent_self_iteration` so local smoke does not require QStash
+- `KEY_VAULTS_SECRET`, `AUTH_SECRET`, auth verification off
+- S3 mock vars
+- Managed DB container: `lobehub-agent-testing-postgres`
+
+`seed-user` creates `agent-testing@lobehub.com` / `TestPassword123!` with
+onboarding already completed for manual or agent-browser checks. When running
+Cucumber against this dev server, pass the same script env into the test process
+too; Cucumber has its own `BeforeAll` seed path and it must see `DATABASE_URL`
+instead of silently skipping setup:
+
+```bash
+cd e2e
+# Only in the no-.env branch.
+eval "$(../.agents/skills/agent-testing/scripts/init-dev-env.sh env)"
+BASE_URL=http://localhost:3010 HEADLESS=true bun run test:smoke
+```
+
+### 0.4 Auth is green

 **Auth is the gate for all automated testing.**

@@ -151,6 +238,7 @@ All under `.agents/skills/agent-testing/scripts/`:
 | Script                    | Usage                                                                        |
 | ------------------------- | ---------------------------------------------------------------------------- |
 | `setup-auth.sh`           | One-stop auth setup & status check (`status` / `cli` / `web`)                |
+| `init-dev-env.sh`         | Self-contained local dev env (`setup-db` / `seed-user` / `dev-next` / `dev`) |
 | `app-probe.sh`            | LobeHub app probes: `auth` / `route` / `ops` / `goto <path>` / `errors`      |
 | `record-gif.sh`           | Frame-sequence → GIF for time-based behavior (streaming, timers, animations) |
 | `report-init.sh`          | Scaffold a structured test report (Step 3)                                   |
@@ -8,7 +8,7 @@ surfaces (CLI, Electron, Web) hit.
 | Command             | What it runs                                              | Port                              |
 | ------------------- | --------------------------------------------------------- | --------------------------------- |
 | `pnpm run dev:next` | Next.js backend (API + auth)                              | `3010`                            |
-| `bun run dev`       | Full-stack (Next.js + Vite SPA, via `devStartupSequence`) | `3010` (API) + SPA                |
+| `bun run dev`       | Full-stack (Next.js + Vite SPA, via `devStartupSequence`) | `3010` (API) + SPA on `9876`      |
 | `bun run dev:spa`   | Vite SPA only, proxies API to `3010`                      | `9876` (prints a Debug Proxy URL) |

 In the **cloud repo** (where this repo is the `lobehub/` submodule) the dev
@@ -24,12 +24,25 @@ curl -s -o /dev/null -w '%{http_code}' http://localhost:3010/
 ## Start / restart

 ```bash
-# Start (from repo root)
+# Start backend only.
+# With root .env: use the existing local config.
 pnpm run dev:next

+# Without root .env: use the self-contained agent-testing env.
+./.agents/skills/agent-testing/scripts/init-dev-env.sh dev-next
+
+# Full-stack SPA + backend. Required for Web smoke.
+# With root .env:
+bun run dev
+
+# Without root .env:
+./.agents/skills/agent-testing/scripts/init-dev-env.sh dev
+
 # Restart — required to pick up server-side code changes
 lsof -ti:3010 | xargs kill
 pnpm run dev:next
+# or, when no root .env exists:
+# ./.agents/skills/agent-testing/scripts/init-dev-env.sh dev-next
 ```

 ## When a server restart is needed
@@ -0,0 +1,290 @@
+#!/usr/bin/env bash
+# init-dev-env.sh — self-contained local dev env for agent testing.
+#
+# This script initializes the env needed to run LobeHub's normal local dev
+# server without depending on a root .env file. It follows the same shape as
+# the e2e bootstrap (Postgres + migrations + auth/key-vault/S3 test env), but
+# starts the repo's dev server, not the standalone e2e server.
+#
+# Guardrail: if repo-root .env exists, every non-help command exits immediately.
+# Existing local config always wins.
+#
+# Usage:
+#   init-dev-env.sh env              # print shell exports
+#   init-dev-env.sh write [file]     # write a source-able env file
+#   init-dev-env.sh setup-db         # start local Postgres and run migrations
+#   init-dev-env.sh migrate          # run DB migrations against the configured DB
+#   init-dev-env.sh seed-user        # seed the baseline test user
+#   init-dev-env.sh dev-next         # exec `pnpm run dev:next` with this env
+#   init-dev-env.sh dev              # exec `bun run dev` with this env
+#   init-dev-env.sh clean-db         # remove the managed Postgres container
+#
+# Overrides:
+#   SERVER_PORT=3010 DB_PORT=5433 DB_CONTAINER=lobehub-agent-testing-postgres
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../.." && pwd)"
+ROOT_ENV_FILE="$REPO_ROOT/.env"
+
+SERVER_PORT="${SERVER_PORT:-3010}"
+DB_PORT="${DB_PORT:-5433}"
+DB_CONTAINER="${DB_CONTAINER:-lobehub-agent-testing-postgres}"
+DATABASE_URL="${DATABASE_URL:-postgresql://postgres:postgres@localhost:${DB_PORT}/postgres}"
+ENV_FILE_DEFAULT="$REPO_ROOT/.records/env/agent-testing-dev.env"
+
+ok() { printf '  \033[32m✔\033[0m %s\n' "$1"; }
+bad() { printf '  \033[31m✘\033[0m %s\n' "$1"; }
+note() { printf '      %s\n' "$1"; }
+
+guard_no_root_env() {
+  if [[ -f "$ROOT_ENV_FILE" ]]; then
+    bad "root .env exists: $ROOT_ENV_FILE"
+    note "Use the existing local configuration instead of init-dev-env.sh."
+    note "Start normally from repo root, e.g. pnpm run dev:next or bun run dev."
+    exit 1
+  fi
+}
+
+apply_env() {
+  export APP_URL="${APP_URL:-http://localhost:${SERVER_PORT}}"
+  export AUTH_EMAIL_VERIFICATION="${AUTH_EMAIL_VERIFICATION:-0}"
+  export AUTH_SECRET="${AUTH_SECRET:-agent-testing-local-auth-secret-32chars}"
+  export DATABASE_DRIVER="${DATABASE_DRIVER:-node}"
+  export DATABASE_URL
+  export FEATURE_FLAGS="${FEATURE_FLAGS:--agent_self_iteration}"
+  export KEY_VAULTS_SECRET="${KEY_VAULTS_SECRET:-r2gbBPKyJ8ZRKCLKt+I3DImfcL+wGxaQyRC56xtm9Uk=}"
+  export NEXT_PUBLIC_AUTH_EMAIL_VERIFICATION="${NEXT_PUBLIC_AUTH_EMAIL_VERIFICATION:-0}"
+  export NODE_OPTIONS="${NODE_OPTIONS:---max-old-space-size=6144}"
+  export PORT="${PORT:-$SERVER_PORT}"
+  export S3_ACCESS_KEY_ID="${S3_ACCESS_KEY_ID:-agent-testing-access-key}"
+  export S3_BUCKET="${S3_BUCKET:-agent-testing-bucket}"
+  export S3_ENDPOINT="${S3_ENDPOINT:-https://agent-testing-s3.localhost}"
+  export S3_SECRET_ACCESS_KEY="${S3_SECRET_ACCESS_KEY:-agent-testing-secret-key}"
+}
+
+env_keys() {
+  printf '%s\n' \
+    APP_URL \
+    AUTH_EMAIL_VERIFICATION \
+    AUTH_SECRET \
+    DATABASE_DRIVER \
+    DATABASE_URL \
+    FEATURE_FLAGS \
+    KEY_VAULTS_SECRET \
+    NEXT_PUBLIC_AUTH_EMAIL_VERIFICATION \
+    NODE_OPTIONS \
+    PORT \
+    S3_ACCESS_KEY_ID \
+    S3_BUCKET \
+    S3_ENDPOINT \
+    S3_SECRET_ACCESS_KEY
+}
+
+print_env() {
+  apply_env
+  while IFS= read -r key; do
+    printf 'export %s=%q\n' "$key" "${!key}"
+  done < <(env_keys)
+}
+
+write_env() {
+  local file="${1:-$ENV_FILE_DEFAULT}"
+  apply_env
+  mkdir -p "$(dirname "$file")"
+  {
+    printf '# Source this file before starting LobeHub local dev server.\n'
+    printf '# Generated by %s\n' "$0"
+    while IFS= read -r key; do
+      printf 'export %s=%q\n' "$key" "${!key}"
+    done < <(env_keys)
+  } > "$file"
+  ok "wrote env file: $file"
+  note "source it with: source $file"
+}
+
+require_docker() {
+  if ! command -v docker > /dev/null 2>&1; then
+    bad "docker CLI is not available"
+    note "Install/start Docker Desktop, or provide DATABASE_URL for an existing Postgres."
+    return 1
+  fi
+}
+
+wait_for_db() {
+  printf '      waiting for Postgres'
+  until docker exec "$DB_CONTAINER" pg_isready -U postgres > /dev/null 2>&1; do
+    printf '.'
+    sleep 2
+  done
+  printf '\n'
+}
+
+start_db() {
+  require_docker
+
+  if docker ps --format '{{.Names}}' | grep -Fxq "$DB_CONTAINER"; then
+    ok "Postgres container already running: $DB_CONTAINER"
+  elif docker ps -a --format '{{.Names}}' | grep -Fxq "$DB_CONTAINER"; then
+    docker start "$DB_CONTAINER" > /dev/null
+    ok "started existing Postgres container: $DB_CONTAINER"
+  else
+    docker run -d \
+      --name "$DB_CONTAINER" \
+      -e POSTGRES_PASSWORD=postgres \
+      -p "${DB_PORT}:5432" \
+      paradedb/paradedb:latest > /dev/null
+    ok "created Postgres container: $DB_CONTAINER"
+  fi
+
+  wait_for_db
+}
+
+migrate_db() {
+  apply_env
+  cd "$REPO_ROOT"
+  bun run db:migrate
+}
+
+seed_user() {
+  apply_env
+  cd "$REPO_ROOT"
+  node <<'NODE'
+const bcrypt = require('bcryptjs');
+const pg = require('pg');
+
+const databaseUrl = process.env.DATABASE_URL;
+if (!databaseUrl) {
+  throw new Error('DATABASE_URL is required to seed the baseline test user.');
+}
+
+const TEST_USER = {
+  email: 'agent-testing@lobehub.com',
+  fullName: 'Agent Testing User',
+  id: 'user_agent_testing_001',
+  password: 'TestPassword123!',
+  username: 'agent_testing_user',
+};
+
+const client = new pg.Client({ connectionString: databaseUrl });
+
+(async () => {
+  await client.connect();
+  const now = new Date().toISOString();
+  const onboarding = JSON.stringify({ finishedAt: now, version: 1 });
+  const passwordHash = await bcrypt.hash(TEST_USER.password, 10);
+
+  await client.query(
+    `INSERT INTO users (id, email, normalized_email, username, full_name, email_verified, onboarding, created_at, updated_at, last_active_at)
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $8, $8)
+     ON CONFLICT (id) DO UPDATE SET onboarding = $7, updated_at = $8`,
+    [
+      TEST_USER.id,
+      TEST_USER.email,
+      TEST_USER.email.toLowerCase(),
+      TEST_USER.username,
+      TEST_USER.fullName,
+      true,
+      onboarding,
+      now,
+    ],
+  );
+
+  await client.query(
+    `INSERT INTO accounts (id, user_id, account_id, provider_id, password, created_at, updated_at)
+     VALUES ($1, $2, $3, $4, $5, $6, $6)
+     ON CONFLICT DO NOTHING`,
+    [
+      'agent_testing_account_001',
+      TEST_USER.id,
+      TEST_USER.email,
+      'credential',
+      passwordHash,
+      now,
+    ],
+  );
+
+  console.log('seeded baseline user:');
+  console.log(`  email: ${TEST_USER.email}`);
+  console.log(`  password: ${TEST_USER.password}`);
+})()
+  .finally(() => client.end())
+  .catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+NODE
+}
+
+cmd_status() {
+  apply_env
+  echo "agent-testing local dev env:"
+  note "APP_URL=$APP_URL"
+  note "DATABASE_URL=$DATABASE_URL"
+  note "PORT=$PORT"
+  if command -v docker > /dev/null 2>&1; then
+    ok "docker CLI available"
+    if docker ps --format '{{.Names}}' | grep -Fxq "$DB_CONTAINER"; then
+      ok "managed Postgres running: $DB_CONTAINER"
+    else
+      note "managed Postgres is not running: $DB_CONTAINER"
+    fi
+  else
+    bad "docker CLI is not available"
+  fi
+}
+
+cmd_dev_next() {
+  apply_env
+  cd "$REPO_ROOT"
+  exec pnpm run dev:next
+}
+
+cmd_dev() {
+  apply_env
+  cd "$REPO_ROOT"
+  exec bun run dev
+}
+
+cmd_clean_db() {
+  require_docker
+  if docker ps --format '{{.Names}}' | grep -Fxq "$DB_CONTAINER"; then
+    docker stop "$DB_CONTAINER" > /dev/null
+  fi
+  if docker ps -a --format '{{.Names}}' | grep -Fxq "$DB_CONTAINER"; then
+    docker rm "$DB_CONTAINER" > /dev/null
+    ok "removed Postgres container: $DB_CONTAINER"
+  else
+    note "Postgres container not found: $DB_CONTAINER"
+  fi
+}
+
+usage() {
+  sed -n '3,24p' "$0" >&2
+}
+
+COMMAND="${1:-status}"
+
+case "$COMMAND" in
+  help|-h|--help) usage; exit 0 ;;
+  *) guard_no_root_env ;;
+esac
+
+case "$COMMAND" in
+  env) print_env ;;
+  write) shift; write_env "${1:-}" ;;
+  setup-db)
+    start_db
+    migrate_db
+    ;;
+  migrate) migrate_db ;;
+  seed-user) seed_user ;;
+  dev-next) cmd_dev_next ;;
+  dev) cmd_dev ;;
+  clean-db) cmd_clean_db ;;
+  status) cmd_status ;;
+  *)
+    usage
+    exit 2
+    ;;
+esac
@@ -351,5 +351,8 @@ export default defineConfig({
        './packages/agent-manager-runtime/src/**/*.ts',
      ],
    },
+    watch: {
+      ignored: ['**/e2e/reports/**', '**/e2e/screenshots/**'],
+    },
  },
 });