From efc221f95e74c9e31eed94ef01a4a3b1c50d0c46 Mon Sep 17 00:00:00 2001
From: whekin <stanislavkalishin@gmail.com>
Date: Thu, 5 Mar 2026 20:48:09 +0400
Subject: [PATCH] docs(test): add e2e runbook and use .bun-version in CI/CD

---
 .github/workflows/cd.yml   |  2 +-
 .github/workflows/ci.yml   |  2 +-
 docs/runbooks/e2e-tests.md | 64 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 66 insertions(+), 2 deletions(-)
 create mode 100644 docs/runbooks/e2e-tests.md

diff --git a/.github/workflows/cd.yml b/.github/workflows/cd.yml
index d7ae0a1..6bbc3c4 100644
--- a/.github/workflows/cd.yml
+++ b/.github/workflows/cd.yml
@@ -85,7 +85,7 @@ jobs:
         if: ${{ needs.check-secrets.outputs.db_secret_ok == 'true' }}
         uses: oven-sh/setup-bun@v2
         with:
-          bun-version: 1.3.10
+          bun-version-file: .bun-version
 
       - name: Install dependencies for migrations
         if: ${{ needs.check-secrets.outputs.db_secret_ok == 'true' }}
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c32c78d..176486f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -38,7 +38,7 @@ jobs:
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
         with:
-          bun-version: 1.3.10
+          bun-version-file: .bun-version
 
       - name: Restore Bun cache
         uses: actions/cache@v4
diff --git a/docs/runbooks/e2e-tests.md b/docs/runbooks/e2e-tests.md
new file mode 100644
index 0000000..1c33b83
--- /dev/null
+++ b/docs/runbooks/e2e-tests.md
@@ -0,0 +1,64 @@
+# End-to-End Smoke Tests
+
+## Overview
+
+The `scripts/e2e/billing-flow.ts` script runs a deterministic end-to-end
+smoke test for the billing pipeline. It exercises:
+
+- Purchase ingestion from a simulated topic message
+- Utility bill entry via bot commands
+- Monthly statement generation and balance verification
+
+## Prerequisites
+
+- Bun 1.3+ installed
+- A running Supabase/Postgres database with the schema applied
+- `DATABASE_URL` set (via `.env` or environment)
+
+## Running locally
+
+```bash
+# 1. Ensure .env has a valid DATABASE_URL
+cp .env.example .env
+# edit .env with real DATABASE_URL
+
+# 2. Apply database migrations
+bun run db:migrate
+
+# 3. Run the e2e smoke test
+bun run test:e2e
+```
+
+The test seeds its own data (household + 3 roommates), runs the full
+purchase → utility → statement flow, asserts deterministic totals, and
+cleans up after itself.
+
+## Expected output
+
+On success:
+
+```
+E2E smoke passed: purchase ingestion, utility updates, and statements are deterministic
+```
+
+On failure the script exits with code 1 and prints the assertion error.
+
+## CI integration
+
+The e2e smoke test runs in CI as part of the quality matrix when the
+`DATABASE_URL` secret is configured. Without the secret, the job is
+skipped automatically.
+
+## Test data
+
+The test creates temporary records with random UUIDs:
+
+| Entity    | Details                    |
+| --------- | -------------------------- |
+| Household | "E2E Smoke Household"      |
+| Alice     | Admin, telegram ID 900001  |
+| Bob       | Member, telegram ID 900002 |
+| Carol     | Member, telegram ID 900003 |
+
+All test data is cleaned up in a `finally` block via cascade delete on
+the household row.