[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: 1200
+      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,117 @@
+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
+    # GitHub keeps only one pending run per concurrency group and cancels the one it replaces, so a single
+    # shared group would let a PR push silently cancel a queued run of another PR or the weekly full run.
+    # Instead each PR gets its own smoke group, where a newer push replaces the older run (its accounts are
+    # still deleted by the cleanup step, which runs on cancel), and the full run gets a group of its own.
+    # Smoke runs use only a few users, so one overlapping another run barely skews its results.
+    concurrency:
+      group: load-test-${{ inputs.report_name }}-${{ github.event.pull_request.number || github.ref }}
+      cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+    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: Run load test
+        id: jmeter
+        run: |
+          mkdir -p results
+          # The plan puts the run ID in each account's email and username. The run ID and attempt number keep
+          # them unique, including when a failed job is re-run.
+          jmeter -n -t "$PLAN" -JrunId="${GITHUB_RUN_ID: -5}${GITHUB_RUN_ATTEMPT}" \
+            -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" \
+            -JcheckLeftovers=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
 

backend/email/emails/functions/send-email.ts

@@ -20,6 +20,11 @@ export const sendEmail = async (
     return null
   }
 
+  if (sendsOnlyToTestDomains(payload.to)) {
+    debug(`Skipping email to reserved test domain: ${payload.to}`)
+    return null
+  }
+
   if (!resend) return null
 
   const {data, error} = await resend.emails.send(
@@ -44,6 +49,21 @@ export const sendEmail = async (
   return data
 }
 
+// Domains reserved for testing (RFC 2606) can never receive mail. The load tests sign up with them, so
+// sending would only bounce and hurt the sender reputation.
+const isTestDomainAddress = (address: string) => {
+  const domain = address.trim().replace(/>$/, '').split('@').pop()?.toLowerCase() ?? ''
+  return (
+    ['example.com', 'example.net', 'example.org'].includes(domain) ||
+    ['.example', '.test', '.invalid'].some((tld) => domain.endsWith(tld))
+  )
+}
+
+const sendsOnlyToTestDomains = (to: string | string[]) => {
+  const addresses = Array.isArray(to) ? to : [to]
+  return addresses.length > 0 && addresses.every(isTestDomainAddress)
+}
+
 let resend: Resend | null = null
 const getResend = () => {
   if (resend) return resend