Bte

Invocation context

/bte runs in two contexts. The flow differs slightly:

• Standalone — user types /bte unit <domain> or /bte integration <domain> directly. In bootstrap / write modes, /bte runs the full Dev Flow itself: pre-flight (read-only against main checkout: git fetch origin master, branch + worktree collision checks) → worktree creation (git worktree add ~/codebase-worktrees/PetCare-bte-bootstrap-<domain> -b claude/bte-bootstrap-<domain> origin/master, or the integration variant) → all subsequent work runs inside the worktree → write tests → pre-commit → commit → git push -u origin → gh pr create (ready-for-review) → final report with worktree path + cleanup hint. The user's main IDE checkout is never modified.
• Inline from /be — /be invokes /bte mid-flow inside the worktree /be already created. /bte does not run pre-flight and does not create a new worktree — it writes tests directly into /be's worktree at <abs-worktree-path> and adds a test(<domain>): ... commit that lands in /be's same PR. /be handles the push and PR creation, not /bte.

You can detect inline invocation by the parent skill's instruction in your task prompt. When in doubt, ask.

Two-tier test structure

Tests live under backend/tests/ and are split into two strict layers:

• backend/tests/unit/ — Unit tests. MUST NOT touch any third-party resource: no Postgres, no Google OAuth, no network, no real filesystem (except temp dirs). Runs on every commit / every PR via the CI unittest job. Each domain has its own file (e.g. unit/services/test_auth_service.py, unit/services/test_meal_service.py). Pure-function tests of services, models, validators, helpers. Apply clean-code rules: small tests, AAA structure, one logical assertion per test, no shared mutable state.
• backend/tests/integration/ — Integration tests. May connect to a real Postgres (POSTGRES_TEST), Google OAuth, etc. Run manually, NOT on every commit. Includes a schema-verification test that connects to the designated DB env, queries information_schema, and diffs against the parsed database/db_schema.sql to confirm the live schema matches the source-of-truth file. Integration tests are heavyweight and require explicit user discussion before adding new ones.

Mock strategy for unit tests (the agreed plan)

• DB client: patch backend.core.db_manager.get_db (or the service-level get_db import) to return an unittest.mock.AsyncMock. Configure read_one, read, insert_one, insert, execute, execute_returning per test via return_value or side_effect. Mock return values must match the real dict shape, not just {}.
• INSERT ... RETURNING * mock shape (read this before mocking execute_returning): PostgreSQL's RETURNING * returns columns from the single target table only — no joined columns from other tables. If the service then constructs a Pydantic model that takes joined fields as separate kwargs (e.g. weight_service.create_weight_record does WeightRecordInfo(**row, user_name=user_name)), your mock row must NOT contain those joined keys or you will get TypeError: got multiple values for keyword argument 'user_name'. Match the SQL: INSERT INTO weight_records (...) RETURNING * returns weight_records columns only. This bit the bootstrap pass for test_weight_service.py once — do not re-import a generic helper row into an execute_returning mock without trimming the joined columns.
• bcrypt: bcrypt is the biggest hidden cost in test runs (~100ms per hash). A session-scoped autouse fixture in backend/tests/unit/conftest.py must monkeypatch pwd_context.hash and pwd_context.verify to a fast no-op fake hasher. Patch at the canonical source (backend.models.auth.pwd_context), not per-service — that way every service importing pwd_context from backend.models.auth automatically picks up the fake. Never let real bcrypt run inside unit tests. Create conftest.py with this fixture if it does not yet exist.
• JWT / time / UUIDs: mock dt.now, uuid.uuid4, jwt.encode where determinism matters. For services like AuthService that read JWT_SECRET_KEY from env at construction time, override service.secret_key after instantiation in your fixture rather than relying on the env var being set in CI.
• No FastAPI app import: unit test files import only the service module under test, never from backend.main import app. This avoids dragging in every router and the asyncpg pool.
• Parallel execution: CI runs pytest backend/tests/unit -n auto via pytest-xdist. Tests must be independent — no shared mutable globals, no shared AsyncMock instances across tests.
• No pytest-mock unless the user changes their mind — stick with stdlib unittest.mock.

Backend layering recap (so you know where coverage gaps live)

router → service → db_client. Routers are thin; almost all business logic is in backend/services/*.py. Each service has a db property that lazily calls get_db(), which is the single seam where unit tests mock the DB.

Domains (each maps to a router + service + model file): auth, user, group, pet, food, meal, weight.

The standard API response envelope is {"status": 1, "data": {...}, "message": "..."}.

Group-based authorization: pets/foods/meals are scoped to a group_id, not a user_id. Roles are creator / member / viewer. Any service method that touches these resources must check group membership — coverage gaps in authorization checks are a priority finding and must be tested for the unauthorized-role path (member-vs-viewer-vs-stranger).

Files to know

• backend/services/<domain>_service.py — business logic (test target)
• backend/models/<domain>.py — Pydantic schemas + table-name constants
• backend/routers/<domain>_router.py — HTTP layer
• backend/core/db_manager.py — get_db() (mock seam)
• backend/core/postgres_database.py — db client API surface (6 methods: read, read_one, insert_one, insert, execute, execute_returning)
• database/db_schema.sql — source of truth for schema
• backend/tests/unit/ — where new unit tests go
• backend/tests/unit/conftest.py — bcrypt stub + shared fixtures (may need to be created)
• backend/tests/integration/ — where new integration tests go (with discussion)

Subcommand: unit

Invoked as /bte unit <domain> (e.g. /bte unit pet).

Step 0 — Validate

<domain> must be one of: auth, user, group, pet, food, meal, weight. If not, list the valid options in Traditional Chinese and stop.

Step 1 — Read the service

Read backend/services/<domain>_service.py fully. Also read backend/models/<domain>.py for the schema and table constants.

Step 2 — Check if a unit test file exists

Look for backend/tests/unit/services/test_<domain>_service.py.

• If it exists → go to Step 3A (review-only mode).
• If it does NOT exist → go to Step 3B (bootstrap mode, auto-write).

Step 3A — Review-only mode (existing test file)

The domain already has a unit test file. Review it; do not write or modify any code. Read files from the user's main checkout (no worktree needed — review-only mode is read-only and doesn't open a PR).

1. Build a coverage map: for each public method on the service class, list (a) what it does, (b) what code paths / branches exist (happy path, validation failures, authz failures, not-found, conflict, edge cases), (c) which paths are currently tested, (d) which are missing.
2. Review existing tests against the rules in the Shared Context:
   • Does any test import backend.main or AsyncClient? → flag as wrong layer (belongs in integration).
   • Does any test let real bcrypt run? → flag the bcrypt fixture as missing or bypassed.
   • Does any test rely on real get_db() / connect to Postgres? → flag.
   • Are tests parallel-safe (no module-level mutable state, no shared AsyncMock instances across tests)?
   • Are tests grouped by AAA / one-behaviour-per-test? Are names descriptive?
   • Is there obvious duplication that could be a fixture or parametrize?
   • Are mock return values realistic enough (matching the actual read_one dict shape, not just {})?
3. Produce a structured report in Traditional Chinese with these sections:
   • 覆蓋摘要 — table of methods × tested-or-not
   • 缺漏的測試案例 — concrete list of missing scenarios, grouped by method, each with a one-line description of what to assert
   • 可重構的地方 — duplication, fixture opportunities, naming, AAA violations, mock realism, parallel-safety issues
   • 違反 unit test 原則的測試 — anything that touches DB / bcrypt / FastAPI app / network
   • 建議的下一步 — prioritized list (P0 = blocks merge, P1 = should fix, P2 = nice-to-have)
4. Stop here. Do not offer to implement, do not ask the user a follow-up question, do not write any code. The user is in control of whether to act on the report.

Step 3B — Bootstrap mode (no test file exists)

The domain has no unit tests at all. Plan and write a fresh test file from scratch, inside a per-task git worktree per CLAUDE.md > Dev Flow.

1. Build a coverage plan from the service file: for each public method, list every important code path (happy path, validation failures, authz failures, not-found, conflict, edge cases). For group-scoped resources, every method that touches pets / foods / meals must include viewer / non-member / member / creator authorization cases. Read service files from main checkout (read-only).
2. Show the plan to the user in Traditional Chinese before writing. Use the same structure as the review report (覆蓋摘要 + planned cases per method) but framed as "我準備新增以下測試". This gives the user visibility into what is about to be written, even though no confirmation is required to proceed.
3. Worktree decision:
   • If invoked inline by /be → skip pre-flight and worktree creation. Write directly inside /be's existing worktree at <abs-worktree-path>. /be will commit + push + PR.
   • If invoked standalone → run pre-flight (read-only against main checkout): git fetch origin master, then check no collision (git ls-remote --heads origin claude/bte-bootstrap-<domain>, git branch --list ..., git worktree list, <path> not on disk). Compute worktree path ~/codebase-worktrees/PetCare-bte-bootstrap-<domain> (append -2, -3, ... on any collision), then create:

     git worktree add <abs-worktree-path> -b claude/bte-bootstrap-<domain> origin/master
     

     The worktree path AND branch name must appear in your reply to the user before any code is written. From here onward, every Bash call is cd <abs-worktree-path> && ... and every Read / Edit / Write uses an absolute path under <abs-worktree-path>.
4. Write the test file (inside the worktree):
   • Target: <abs-worktree-path>/backend/tests/unit/services/test_<domain>_service.py
   • If <abs-worktree-path>/backend/tests/unit/conftest.py does not exist, create it with the bcrypt stub + any shared fixtures
   • Write all the planned test cases following the unit test rules (no backend.main import, mock get_db(), stub bcrypt, parallel-safe, AAA, stdlib unittest.mock only)
5. Run pytest (inside the worktree):

   cd <abs-worktree-path> && python -m pytest backend/tests/unit/services/test_<domain>_service.py -n auto
   

   If any test fails, fix the test file and re-run. Do not commit broken tests.
6. Pre-commit gate (inside the worktree):

   cd <abs-worktree-path>/backend && pre-commit run --all-files
   

   Fix any failures. Never use --no-verify. Two failures in a row → stop and report.
7. Commit / push / PR (standalone only — skip if invoked inline by /be). All git commands run inside the worktree.

   • Commit message: test(<domain>): bootstrap unit tests for <domain> service. Commit messages do not include a Co-Authored-By: Claude trailer.

   • cd <abs-worktree-path> && git push -u origin <branch>

   • Open the PR ready-for-review (no --draft). Do not pass --label flags — labels live on issues, not PRs. gh pr create runs from inside <abs-worktree-path>.

     cd <abs-worktree-path>
     gh pr create --base master \
       --title "[bte] bootstrap unit tests for <domain>" \
       --body "$(cat <<'EOF'
     ## Summary
     - Bootstrap unit test file for <domain> service
     - <N> test cases covering: <brief list of method × scenario>
     
     ## Files created
     - backend/tests/unit/services/test_<domain>_service.py
     - backend/tests/unit/conftest.py  (only if newly created)
     
     ## pytest result
     

     <pytest summary line> ```

     Notes

     • <any non-obvious decisions>

     EOF )"

8. Report back in Traditional Chinese:
   • If standalone → PR URL, branch name, worktree path (absolute), files created, pytest result, cleanup hint (git worktree remove <abs-worktree-path> + git branch -D <branch> after PR is merged), confirmation that main IDE checkout was not modified
   • If inline → confirmation that work landed inside /be's worktree at <abs-worktree-path>, files created, pytest result, hand control back to /be

Subcommand: integration

Invoked as /bte integration <domain> (e.g. /bte integration meal).

Integration tests are heavyweight and the user has stated they require discussion before being added or changed. Discussion-first applies regardless of whether a test file exists — there is no bootstrap mode for integration.

Step 0 — Validate

<domain> must be one of: auth, user, group, pet, food, meal, weight, or the special value schema (refers to backend/tests/integration/test_schema_match.py, the live-DB-vs-db_schema.sql verifier).

Step 1 — Read

Read the service + router + model + existing integration test file (if any). For schema, read database/db_schema.sql and the existing schema-match test.

Step 2 — Discussion document

Produce a discussion document in Traditional Chinese:

1. Map out what an integration test for this domain SHOULD cover that a unit test cannot:
   • Real DB constraints (FK, CHECK, unique, trigger behaviour)
   • Multi-table flows that exercise FK cascades
   • Real bcrypt round-trips (only if security-relevant)
   • Real auth flow end-to-end (/auth/email/login → token → protected endpoint)
   • For schema: which tables / columns / indexes / enums / triggers / constraints the verification covers, and any drift detected
2. Review existing integration tests (if any) for:
   • Tests that could trivially be moved to unit (i.e. don't actually need DB) — flag as candidates for downgrade
   • Tests that depend on session ordering and would break under parallel execution
   • Cleanup correctness (does the test leave the DB in a state the next test can depend on?)
3. Output sections:
   • 這個 domain 的 integration test 應該保留 / 新增 哪些案例 — and the reason each one cannot be a unit test
   • 可以下放到 unit 的案例 — if any
   • 目前的覆蓋狀態
   • 手動跑這個 integration test 的指令（例如 APP_ENV=test POSTGRES_TEST=... python -m pytest backend/tests/integration/test_<domain>.py）
   • 需要使用者決定的問題 — explicit list of open questions

Step 3 — Ask for confirmation, then write on user approval

End the discussion document with:

1. An itemised list of the proposed cases, each numbered.
2. The selection prompt:

「以上案例要我實作哪幾個？回 1,3,5 指定編號、回 all 全寫、或回 no 停止。整合測試會新增到 backend/tests/integration/test_<domain>.py，不會被加入 CI。」

If, in their next message, the user confirms with a non-empty selection, proceed to write exactly the selected cases synchronously in main checkout per CLAUDE.md > Dev Flow. Otherwise stop.

When writing:

1. Pre-flight + worktree (standalone only — skip if /be invoked you inline):
   • Run pre-flight against main checkout (read-only): git fetch origin master, then collision checks (git ls-remote --heads origin claude/bte-integration-<domain>, git branch --list ..., git worktree list, <path> not on disk).
   • Compute worktree path ~/codebase-worktrees/PetCare-bte-integration-<domain> (append -2, -3, ... on any collision).
   • Create the worktree:

     git worktree add <abs-worktree-path> -b claude/bte-integration-<domain> origin/master
     

   • The worktree path AND branch name must appear in your reply to the user before any code is written.
   • From here onward, every Bash call is cd <abs-worktree-path> && ... and every Read / Edit / Write uses an absolute path under <abs-worktree-path>.
   • If invoked inline by /be → skip this step entirely. Write directly inside /be's existing worktree.
2. Write the integration test file (inside the worktree):
   • Target: <abs-worktree-path>/backend/tests/integration/test_<domain>.py (or test_schema_match.py for schema)
   • Document required env vars inline at the top: APP_ENV=test, POSTGRES_TEST, plus any others
   • For each approved case: write the test with scenario, setup steps, real third-party resource usage, assertions
   • Hard rules:
     • Justify in a docstring why each case cannot be a unit test
     • Must clean up its own DB state (no reliance on global cleanup)
     • Must NOT be added to .github/workflows/ci.yml — integration tests are manual-only
     • Must be runnable individually with the documented env vars
     • For schema: no business-logic assertions; only structural diffs
3. Pre-commit gate (inside the worktree):

   cd <abs-worktree-path>/backend && pre-commit run --all-files
   

   Fix any failures. Never use --no-verify. Two failures in a row → stop and report.
4. Commit / push / PR (standalone only). All git commands run inside the worktree.

   • Commit message: test(<domain>): add integration tests for <list of scenarios>. Commit messages do not include a Co-Authored-By: Claude trailer.

   • cd <abs-worktree-path> && git push -u origin <branch>

   • Open the PR ready-for-review (no --draft). Do not pass --label flags — labels live on issues, not PRs. gh pr create runs from inside <abs-worktree-path>.

     cd <abs-worktree-path>
     gh pr create --base master \
       --title "[bte] integration tests for <domain>" \
       --body "$(cat <<'EOF'
     ## Summary
     - Integration tests for <domain>: <list of scenarios>
     
     ## Files created / modified
     - backend/tests/integration/test_<domain>.py
     
     ## Manual run command
     ```bash
     APP_ENV=test POSTGRES_TEST=... python -m pytest backend/tests/integration/test_<domain>.py
     

     Notes

     • These tests are manual-only. CI workflow files were NOT touched.
     • <any non-obvious decisions>

     EOF )"

5. Report back in Traditional Chinese:
   • PR URL + branch name + worktree path (standalone) OR confirmation that work landed inside /be's worktree at <abs-worktree-path> (inline)
   • Files created / modified
   • Tests added (count + brief list of scenarios)
   • Manual run command the user should use to verify (highlight prominently — these tests are manual-only)
   • Confirmation that CI workflow files were NOT touched
   • Cleanup hint (standalone only): git worktree remove <abs-worktree-path> + git branch -D <branch> after PR is merged
   • Confirmation (standalone only): "Your main IDE checkout was NOT modified."

Subcommand: discuss

Invoked as /bte discuss <topic> (e.g. /bte discuss "should we mock bcrypt globally", /bte discuss "test naming convention").

This is open Q&A about backend testing. The topic can be anything: a specific method, a pattern, a tooling choice, a refactor, or a question the user has. discuss never writes code, regardless of what the user asks for inside the topic.

1. Read whatever files are needed to ground the discussion in actual code rather than abstract advice. If the topic mentions a service or test file, read it first.
2. Honour the Shared Context above — when giving recommendations, stay consistent with the agreed plan (AsyncMock, no bcrypt, two-tier structure, etc.). If the user is proposing something that contradicts the plan, explicitly call that out and ask whether they want to revise the plan.
3. Structure the response as a short discussion in Traditional Chinese:
   • 問題理解 — restate what you think the user is asking, in one or two sentences, so they can correct you
   • 相關事實 — what the code actually shows (with file:line refs)
   • 選項 — concrete options with trade-offs (speed, complexity, maintenance, coverage)
   • 建議 — your recommended path and why
   • 要使用者拍板的問題 — explicit decisions you need from them before any implementation
4. Do not implement anything in discuss mode. Even if the user's question implies a code change, the discuss subcommand always ends with options + a request for direction. If the user wants to act on the discussion, tell them to run /bte unit <domain> or /bte integration <domain>.

Usage block (show this when arguments are invalid)

/bte 用法：

  /bte unit <domain>          檢視某個 domain 的 unit test 覆蓋與重構機會。
                              若該 domain 完全沒有 unit test 檔，則直接 bootstrap
                              寫一份完整的初始測試。

  /bte integration <domain>   討論某個 domain 的 integration test。永遠先討論，
                              在使用者明確選擇要實作的 case 之後才會寫。

  /bte discuss <topic>        針對 backend test 任何主題進行討論。永遠不會實作。

可用 domain：auth, user, group, pet, food, meal, weight
（integration 額外支援：schema）

範例：
  /bte unit pet
  /bte integration meal
  /bte discuss "AsyncMock vs 自己寫 fake，哪個比較適合 group_service？"

note：bootstrap / integration 寫測試時，依 CLAUDE.md > Dev Flow 在獨立的
      git worktree 裡跑 — pre-flight (read-only on main checkout) →
      worktree 建立 → 寫檔 → pre-commit → commit → push → PR
      (ready-for-review)。Main IDE checkout 完全不會被動到。當 /be
      內聯呼叫 /bte 時，/bte 不會自己開 worktree 或 PR，而是寫到 /be
      已建好的 worktree 裡，由 /be 負責 commit / push / PR。