[Load Tests] Added load testing foundation and markdown file guide

.github/workflows/load-full-test.yml

@@ -0,0 +1,22 @@
+name: Load test (full)
+
+# The full load test against the dev API, once a week: 100 users for 120 seconds.
+# 100 users is Firebase's limit of 100 new accounts per hour from one IP address. Raising it needs a
+# higher sign-up quota in the Firebase console first.
+on:
+  schedule:
+    - cron: '0 6 * * 1' # Mondays at 06:00 UTC
+  workflow_dispatch: # adds a "Run workflow" button in the Actions tab
+
+permissions:
+  contents: read
+
+jobs:
+  full:
+    uses: ./.github/workflows/load-test.yml
+    with:
+      users: 100
+      duration: 120
+      max_error_rate: 1
+      max_p95: 800
+      report_name: load-full-report

.github/workflows/load-smoke-test.yml

@@ -0,0 +1,28 @@
+name: Load test (smoke)
+
+# A small JMeter run when a pull request changes API-related files, to check the test plan still works.
+# It tests the API deployed to dev, not the pull request's code: dev is only updated by running
+# backend/api/deploy-api.sh dev by hand. The weekly full run is in load-full-test.yml.
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'backend/api/**'
+      - 'backend/shared/**'
+      - 'common/src/api/**'
+      - 'tests/load/**'
+      - '.github/workflows/load-*.yml'
+  workflow_dispatch: # adds a "Run workflow" button in the Actions tab
+
+permissions:
+  contents: read
+
+jobs:
+  smoke:
+    uses: ./.github/workflows/load-test.yml
+    with:
+      users: 3
+      duration: 30
+      max_error_rate: 0
+      max_p95: 2000
+      report_name: load-smoke-report

.github/workflows/load-test.yml

@@ -0,0 +1,122 @@
+name: Load test
+
+# The steps shared by the smoke and full load tests. It doesn't run on its own: load-smoke-test.yml and
+# load-full-test.yml call it with their own settings. See docs/load-testing.md.
+#
+# It tests the API deployed to dev (the plan's default apiHost), not the code in this checkout.
+on:
+  workflow_call:
+    inputs:
+      users:
+        description: Threads for account creation and the load test (one account each)
+        type: number
+        required: true
+      duration:
+        description: Seconds the load test runs
+        type: number
+        required: true
+      max_error_rate:
+        description: Highest error rate allowed for any request, in percent
+        type: number
+        required: true
+      max_p95:
+        description: Highest p95 response time allowed for TEST requests, in milliseconds
+        type: number
+        required: true
+      report_name:
+        description: Name of the uploaded report artifact
+        type: string
+        required: true
+
+env:
+  JMETER_VERSION: '5.6.3'
+  PLAN: compass-testPlan.jmx
+  USERS: ${{ inputs.users }}
+  DURATION: ${{ inputs.duration }}
+  MAX_ERROR_RATE: ${{ inputs.max_error_rate }}
+  MAX_P95: ${{ inputs.max_p95 }}
+
+jobs:
+  load-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    # Never run two load tests at once: they hit the same dev API, so each would skew the other's results.
+    concurrency:
+      group: load-test
+      cancel-in-progress: false
+    defaults:
+      run:
+        working-directory: tests/load # folder holding the .jmx and check_results.py
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '17'
+
+      - name: Cache JMeter
+        id: jmeter-cache
+        uses: actions/cache@v4
+        with:
+          path: ~/jmeter
+          key: jmeter-${{ env.JMETER_VERSION }}
+
+      - name: Install JMeter
+        if: steps.jmeter-cache.outputs.cache-hit != 'true'
+        run: |
+          cd "$HOME"
+          base="https://archive.apache.org/dist/jmeter/binaries/apache-jmeter-${JMETER_VERSION}.tgz"
+          curl -fsSLO "$base"
+          # make sure the download wasn't corrupted or tampered with
+          echo "$(curl -fsSL "$base.sha512" | cut -d' ' -f1)  apache-jmeter-${JMETER_VERSION}.tgz" | sha512sum -c -
+          mkdir -p jmeter
+          tar -xzf "apache-jmeter-${JMETER_VERSION}.tgz" -C jmeter --strip-components=1
+
+      - name: Add JMeter to PATH
+        run: echo "$HOME/jmeter/bin" >> "$GITHUB_PATH"
+
+      - name: Make test accounts for this run
+        run: |
+          # one row per user: email,password,username,name (no header, no commas inside values)
+          # The run ID and attempt number make the accounts unique, including when a failed job is re-run.
+          id="${GITHUB_RUN_ID: -5}${GITHUB_RUN_ATTEMPT}"
+          rm -f accounts.csv
+          for i in $(seq 1 "$USERS"); do
+            echo "loadTest${id}x${i}@example.com,$(openssl rand -hex 8),loadUser${id}x${i},load Name${id}x${i}" >> accounts.csv
+          done
+          echo "Made $(wc -l < accounts.csv) accounts"
+
+      - name: Run load test
+        id: jmeter
+        run: |
+          mkdir -p results
+          jmeter -n -t "$PLAN" \
+            -JsetupThreads="$USERS" -Jthreads="$USERS" -Jduration="$DURATION" \
+            -l results/results.jtl -j jmeter.log -e -o report
+
+      - name: Check results
+        run: python3 check_results.py results/results.jtl --max-error-rate "$MAX_ERROR_RATE" --max-p95 "$MAX_P95"
+
+      # tearDown normally deletes the accounts. This only runs if JMeter crashed or the job was cancelled.
+      - name: Clean up accounts if the test didn't finish
+        if: always() && steps.jmeter.outcome != 'success'
+        run: |
+          [ -s created_accounts.txt ] || { echo "No accounts to clean up"; exit 0; }
+          jmeter -n -t "$PLAN" \
+            -JresetFile=0 -JsetupThreads=0 -Jthreads=0 \
+            -l results/cleanup.jtl -j cleanup.log
+
+      - name: Save report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ inputs.report_name }}
+          path: |
+            tests/load/report
+            tests/load/results
+            tests/load/errors.xml
+            tests/load/jmeter.log
+            tests/load/cleanup.log
+          if-no-files-found: ignore

.gitignore

@@ -17,6 +17,13 @@
 /tests/reports/playwright-report
 /tests/e2e/web/.auth/
 
+# JMeter load tests (generated by each run, see docs/load-testing.md)
+/tests/load/created_accounts.txt
+/tests/load/errors.xml
+/tests/load/jmeter.log
+/tests/load/results/
+/tests/load/report/
+
 # next.js
 /.next/
 /out/

CLAUDE.md

@@ -132,6 +132,7 @@ Cross-cutting: [`docs/compatibility-questions.md`](docs/compatibility-questions.
 compatibility prompts), [`docs/feed.md`](docs/feed.md),
 [`docs/internationalization.md`](docs/internationalization.md),
 [`docs/profile-fields.md`](docs/profile-fields.md), [`docs/testing.md`](docs/testing.md),
+[`docs/load-testing.md`](docs/load-testing.md) (JMeter load tests),
 [`docs/logging-monitoring.md`](docs/logging-monitoring.md),
 [`docs/troubleshooting.md`](docs/troubleshooting.md).
 Mobile: [`android/README.md`](android/README.md), [`ios/README.md`](ios/README.md),

README.md

@@ -196,53 +196,41 @@ Then, install the dependencies for this project:
 yarn install --frozen-lockfile
 ```
 
-### Tests
+### Running the app
 
-Make sure the Jest tests pass:
+There are two ways to run Compass locally:
 
-```bash
-yarn test
-```
+|                 | Quick start (`yarn dev`)              | Full isolation (`yarn dev:isolated`)                 |
+| --------------- | ------------------------------------- | ---------------------------------------------------- |
+| Database & auth | Shared remote dev environment         | Local Supabase + Firebase emulators                  |
+| Extra setup     | None                                  | Docker, Java 21+, Firebase CLI                       |
+| Best for        | UI changes, wording fixes, first look | Database, auth, or anything that writes lots of data |
 
-If they don't and you can't find out why, simply raise an issue! Sometimes it's something on our end that we overlooked.
+If you're unsure, start with the quick start. You can switch to full isolation later.
 
-### Running the Development Server
+After pulling new changes, run `yarn install --frozen-lockfile` before launching either one.
 
-Start the development server:
+#### Option A: Quick start (shared dev database)
 
 ```bash
 yarn dev
 ```
 
-[//]: # 'Note: the dev remote server is not available until further notice (to save money). The above command will start a local'
-[//]: # "server instead (same as `yarn dev:isolated` below). You'll have to set up Firebase and Supabase first (see below)."
-[//]: # 'Contact us if you need help; we may spin up the dev remote server for you.'
-
-Once the server is running, visit http://localhost:3000 to start using the app. You can sign up and visit the profiles;
-you should see a few synthetic profiles.
-
-Note: it's normal if page loading locally is much slower than the deployed version. It can take up to 10 seconds, it
-would be great to improve that though!
+> ⚠️ The remote dev database is shared by all contributors. Don't reset or wipe it. If you need a clean or disposable
+> database, use full isolation.
 
-If you update the database schema (in the SQL files) or the database is not super clean or too large (e.g., someone
-clogged it up), you can reset it to a clean state by running:
+#### Option B: Full isolation (local database)
 
-```bash
-yarn dev:db:reset
-```
-
-#### Full isolation
-
-Running `yarn dev:isolated` spins up a local Supabase and Firebase emulator instead of pointing at the shared remote
-database. This is strongly recommended for day-to-day development:
+`yarn dev:isolated` runs a local Supabase database and Firebase emulators instead of using the shared remote
+environment:
 
 - **Freedom** — Reset, wipe, and reseed your local database as many times as you want without affecting other
   contributors.
 - **No conflicts** — Multiple contributors can work simultaneously without stepping on each other's data or schema.
 - **Works offline** — No internet required once services are started locally.
 - **Faster** — No network latency on every database query.
 
-However, running in full isolation requires installing several heavy dependencies:
+The trade-off is heavier setup:
 
 - **Docker** (~500MB) — runs the Supabase Postgres container
 - **Supabase CLI** — manages the local Supabase stack (10+ Docker containers, ~1-2GB RAM when running)
@@ -252,11 +240,7 @@ However, running in full isolation requires installing several heavy dependencie
 First startup is slow (30-60s) and the stack uses significant memory. If your machine has less than 8GB RAM, you may
 notice slowdowns.
 
-If this feels like too much, you can skip isolation entirely — `yarn dev` works out of the box against the shared remote
-and is perfectly fine for most contributions, especially UI changes, wording fixes, or anything that doesn't touch the
-database or authentication.
-
-###### Setup instructions
+##### Prerequisites
 
 As always, don't hesitate to raise an issue if you run into any problems!
 
@@ -305,14 +289,34 @@ npm install -g firebase-tools
 firebase --version
 ```
 
-Run in isolation
+##### Run
+
+Start each session with a fresh local database that has all the latest migrations:
 
 ```bash
+yarn test:db:reset
 yarn dev:isolated
 ```
 
-Visit http://localhost:3000 as usual. Your local database comes preloaded with synthetic test profiles so the app
-looks and feels like the real thing.
+`yarn test:db:reset` only affects your local database and never touches the shared dev one. The Firebase emulator
+doesn't keep users between runs, so resetting the database each time keeps the two in sync.
+
+#### What to expect
+
+Visit http://localhost:3000. You can sign up and browse a few synthetic profiles.
+
+Local page loads can be much slower than the deployed site, up to 10 seconds. That's expected (though improvements are
+welcome!).
+
+### Tests
+
+Before opening a pull request, make sure the Jest tests pass:
+
+```bash
+yarn test
+```
+
+If they fail and you can't work out why, raise an issue. Sometimes it's something on our end that we overlooked.
 
 ### Contributing