household-bot/docs/specs/HOUSEBOT-061-local-e2e-smoke-tests.md

HOUSEBOT-061: Local End-to-End Smoke Tests for Billing Flow

Summary

Add a pragmatic local smoke test that exercises the main billing path against a real database with deterministic assertions.

Goals

• Provide bun run test:e2e for local pre-deploy confidence.
• Cover purchase ingestion, manual utility entry, and statement generation in one flow.
• Ensure smoke data is isolated and cleaned up automatically.

Non-goals

• Full browser or Telegram API end-to-end automation.
• Running destructive write tests in the default CI quality matrix.
• Comprehensive scenario coverage for every finance edge case.

Scope

• In: write-gated smoke script, docs, typed env for the smoke test, deterministic assertions, cleanup.
• Out: full staging environment orchestration.

Interfaces and Contracts

• Command: bun run test:e2e
• Required env:
  • DATABASE_URL
  • E2E_SMOKE_ALLOW_WRITE=true
• Script behavior:
  • creates temporary household/member/cycle data
  • simulates Telegram topic purchase ingestion
  • simulates finance commands for rent, utilities, and statements
  • deletes created data in finally

Domain Rules

• Use integer minor units only.
• Statement totals must match deterministic settlement behavior.
• Purchase-topic ingestion must not swallow non-purchase slash commands.

Data Model Changes

• None.

Security and Privacy

• Test writes are disabled unless E2E_SMOKE_ALLOW_WRITE=true.
• No production secrets are logged by the smoke script.

Observability

• Script prints a single success line on pass.
• Failures surface assertion or runtime errors with non-zero exit code.

Edge Cases and Failure Modes

• Missing DATABASE_URL: fail fast in env validation.
• Missing explicit write guard: fail fast before DB writes.
• Middleware ordering regression: smoke test should fail when commands stop emitting statements.

Test Plan

• Unit: parser/topic candidate tests cover slash-command exclusion.
• Integration: bun run test:e2e against a migrated dev database.
• E2E: same smoke script verifies purchase ingestion -> statement -> recalculated statement after utility update.

Acceptance Criteria

• bun run test:e2e executes locally with deterministic output.
• Purchase ingestion and utility updates are both covered in the same smoke flow.
• Docs explain required env and safety guard.

Rollout Plan

• Keep the smoke test local-first.
• Consider adding an opt-in CI job later once a dedicated disposable database is available.