Mock sessions on pull requests

A mock session is started, controlled and ended from the pull request conversation. Sessions attach to the review environment assigned to the pull request, so the usual review-environment workflow applies first: open the PR, get an environment assigned, then mock.

Starting a session

sfp mock /all

codev checks out the pull request's merge state, reads every mocks.yaml on that branch, builds the mocks, and switches the review environment's Named Credentials to the mock endpoint. A summary comment lists each virtualized service and its stub count.

Variants:

Comment	Effect
sfp mock /all	virtualize every integration declared in the repository
sfp mock pkg1,pkg2	only the integrations declared by those packages
sfp mock reset	force-restart: restore credentials, drop session edits, mock everything again

Commenting sfp mock /all again on an active session refreshes the baseline from the branch (picking up committed rule changes) while preserving the session's edits — it does not start over. Use reset when you want a clean slate.

While the session is active

Run your flows and clickthroughs in the review environment as normal — callouts through the switched Named Credentials are answered by the mocks.

• Switch scenarios with comments (see Scenario playbooks):

  sfp mock scenarios                      ← list what is available
  sfp mock scenario order-delayed         ← arm one; its responses are served from now on
  sfp mock scenario rewind                ← replay the armed scenario from the top
  sfp mock scenario off                   ← back to the baseline rules

• Inspect and edit responses through the control-plane API linked in the session summary. The journal lists every request the org made — newest first, flagged with wasMatched: false when no mock answered; an undeclared integration shows up here. Rule edits are full replacements of a service's rule set and apply immediately, and a service's effective rules can be exported as yaml to be committed as the new baseline. The API is the same surface for developers, test automation and AI agents — listing the session, reading the journal, replacing rules and arming scenarios are all plain HTTP calls.

Ending a session

sfp unmock

This restores every switched Named Credential to its original endpoint and removes the session with its edits and captures. Two behaviours to note:

• If the restore fails — for example the review environment is briefly in use — the session is kept, including everything needed to retry. The reply explains the options: comment sfp unmock again once the cause is fixed, restore from a machine with org access using sfp project integrations restore --workspace <name> -o <env>, or comment sfp unmock force to remove the session anyway (the credentials then stay switched until restored manually).
• Closing or merging the pull request ends the session automatically — credentials are restored before the review environment is released.

Sessions left behind (force-removed environments, abandoned branches) are removed automatically after a retention period.

Things to keep in mind

• The session reflects the branch at the time of activation. Pushing new rules to the branch does not change a running session until you comment sfp mock /all again.
• One session exists per pull request. Re-running sfp mock with a different package list replaces the set of virtualized services.
• The mock endpoint is reachable only through an unguessable per-session URL; the original endpoints are recorded by codev the first time a credential is switched, so restore works regardless of where it is triggered from.