FlowMock

QA sessions

Give every tester their own sandbox on one shared proxy URL.

On this page

Shared staging is a roulette wheel. You mock the cart as empty; someone else's test suddenly sees an empty cart too. FlowMock fixes this with sessions — isolated override scopes on a single proxy URL.

The session key

A session is identified by a session key — any string your team agrees on:

  • qa-alice for manual testing
  • qa-bob for another tester
  • ci-run-4821 for a CI pipeline

Send it on every proxied request:

http
x-flowmock-session: qa-alice

FlowMock normalizes the key (trims whitespace, strips newlines, caps at 200 characters) and matches sessions by exact string equality.

What a session controls

Each session has its own:

  • Active scenario — a bundle of mocks you switch between
  • Individual mock activations — one-off overrides on top of the scenario
  • Global delay — simulate slow responses for the whole session
  • Label — a human-readable note ("Testing expired token flow")

Change Alice's session and Bob's session stays untouched.

How the proxy finds your session

The x-flowmock-session header is the simplest and most reliable method. FlowMock also supports:

  • JWT claims in Authorization (configured per environment)
  • Raw headers, cookies, or query parameters
  • Session cookies from your app

Configure session detection in your environment settings. For most teams, the explicit header is the way to go — especially for CI.

Sessions in the dashboard

Open your environment's Sessions tab to see active sessions, what scenario they're on, and when they were last seen. You can manually activate mocks, switch scenarios, or reset a session from here.

Sessions in CI

Automate session setup with the Public API. A typical flow:

  1. PUT /api/v1/sessions/ci-42 with your desired scenario
  2. Run tests with x-flowmock-session: ci-42
  3. DELETE /api/v1/sessions/ci-42?mode=delete when done

See Sessions API for the full reference.

Common questions

Can two people share a session key? Yes, but they'll see the same mocks. Usually you want one key per person or CI run.

What happens if I forget the header? FlowMock falls back to other detection methods or an anonymous default session. Your mocks might not apply — always send the header in CI.

Do sessions expire? Sessions stay active as long as traffic keeps coming. Idle sessions are cleaned up over time but can be recreated on the next request.