1. Install and open PayloadPigeon
- Open PayloadPigeon in the Chrome Web Store.
- Click Add to Chrome.
- Confirm the permissions requested by Chrome.
- Open the PayloadPigeon Side Panel.
- For sample traffic, open the public Playground.
Choose the ordinary HTTP/HTTPS tab you are authorised to test.
Watch Getting Started for the complete workflow.
2. Start Capture
In the Side Panel, select Start capture this tab. Capture targets that exact tab in the panel’s browser window; opening the panel or switching windows does not capture every tab. In a Detached Window the control says Start capture tested tab.
You can start on an already-loaded page. Once Capture reports Capturing, supported automatic Actions work without a user reload. If it reports Capturing traffic · Actions unavailable, traffic collection is running but action observation is not ready; see Troubleshooting.
3. Understand Actions
Supported trusted clicks, submits and Enter activation are observed automatically. Meaningful HTTP activity, WebSocket frames or failures make an Action available. Empty actions and actions with only successful supporting traffic do not create filters or replace your current selection.
The selector reads After: <Action> · N. It shows the latest meaningful occurrence of each semantic action for that transport; All HTTP traffic or All WebSocket traffic retains earlier captured records. HTTP counts retained relevant exchanges; WebSockets counts associated captured frames. An action without traffic for a transport does not appear in that transport’s selector.
Auto-focus new actions selects the newest meaningful action in the current transport when enabled. Turn it off in the action selector or main … menu to keep your chosen filter. HTTP and WebSockets keep separate selections; auto-focus does not switch transports or take you out of Test Plans or Results.
After describes observed association, not strict causality. Grouping uses timing, behavior and protocol relationships. Paired WebSocket responses can remain with their original action after the initial burst; immediate meaningful follow-up messages may continue the same flow. Some later HTTP follow-up can remain in All traffic instead. This is not perfect causal tracing.
Reload and historical Actions
Reload does not erase retained historical Actions or Traffic. Page bootstrap traffic is not added to an old Action. Observation recovers in the new document; the next real supported user action creates a fresh occurrence. History is temporary and bounded by retention, not a permanent session archive. A top-level cross-origin navigation stops Capture and preserves retained history.
4. Focus Traffic
Meaningful application traffic comes first. Successful supporting assets and analytics are hidden from the main view; pending activity, failures and modifications remain visible within the selected scope. The N hidden ▾ control shows hidden categories and counts. Choose Show everything to restore captured records, or Use focused view to return to the focused presentation.
Supporting categories include images, scripts, stylesheets, fonts, media and other resources. Recurring traffic has a visibility option within an Action. Hidden records keep their original chronology; hiding is not deletion. Search can reveal matching hidden HTTP records within the current Action scope.
5. Search HTTP traffic
Open the top magnifier in HTTP. The field is collapsed by default and searches URL, method, status and retained textual request/response bodies. Binary, unavailable or released body bytes are not searched or recovered.
HTTP and WebSocket queries are independent. A non-empty HTTP query keeps its field open and its filter active across transport switches within the captured-tab UI session. The query stays active until you explicitly clear or change it. Search keeps the current Action and Inspector selection.
6. Search WebSocket activity
Use the top magnifier in WebSockets. One WebSocket search searches across connections, frames/messages, retained textual payloads and pairs, including both sides of a pair. Connection URL, message name/type, direction and retained JSON keys and values are searchable. A matching message keeps its connection discoverable.
The same query applies to Frames and Pairs, within the selected Action scope. Direction is a separate filter. Binary/control payloads and released data are not decoded or refetched. Collapsing the search field keeps the query active; the magnifier indicates an active filter. Clear the query explicitly when finished.
7. Inspect HTTP
Select a captured exchange. Overview shows its summary; Request shows the request headers and body; Response shows the response, status and available original/delivered comparison. Headers start collapsed so the body stays in view. The Inspector remembers your tab while browsing retained exchanges in the same captured-tab UI session.
If a supported text response has only a reduced preview, choose Capture full response before modifying or saving its full body. Follow the capture prompt and repeat the application action when requested. This does not restore bytes already unavailable or released, and retention limits still apply.
On a wide workspace, Traffic and Inspector sit side by side with a resizable divider. On a narrow panel, the Inspector takes the working area; use ← Traffic to return. Search and visibility changes do not discard an open Inspector.
8. Inspect WebSockets
Start Capture before opening a new supported page WebSocket connection. Send a text/JSON message if identification requires it; modification becomes available once the connection is identified. Frames shows individual messages; Pairs shows associated requests and replies. A paired reply is not simply the next incoming message.
App → Server means an outgoing message sent by the application. Server → App means an incoming message delivered to the application. Select a frame or pair to open the existing WebSocket Inspector. A normal supported socket created after Capture starts does not require reload. Stop Capture → Start Capture → reconnect is supported without reload.
9. Modify & send
For HTTP, open Request → Modify & send, edit supported request values and choose Send. This sends a real backend request and shows the actual server response in PayloadPigeon. A valid unchanged request can also be sent.
For an outgoing App → Server WebSocket message on a supported connection, use Modify & send and then Send. This is a real send to the server; outgoing messages do not use Ready.
Credential choices
For supported backend HTTP credential headers, choose Current session, Don't send or Test value. Current session requires one eligible recent value from the same tab and compatible context. Don't send omits the selected header; cookies are separate. Test value is literal and remains unchanged after a 401. Arbitrary body/query credential rebinding is not promised. Stop or Cancel cannot undo an action already performed by the server.
10. Modify & test
For an HTTP response, open Response → Modify & test, prepare the supported body, status or delay behavior and choose Ready. Repeat the action in the app so a fresh matching response receives the prepared change.
For an incoming Server → App WebSocket message, use Modify & test → Ready, then trigger a new matching message in the app. Depending on the supported connection, you can change its payload, delay it or drop the matching server message. An unrelated message does not complete the check.
Fresh response or exact body
An exact saved body is a frozen payload. Field changes apply to the fresh matching response, preserving unrelated live fields. Selecting zero field changes uses the fresh response unchanged; a status-only or delay-only change does not replace its body with an older copy. A supported unchanged response can use Ready and be saved as a Test.
11. View Activity
Select a specific Action, then choose View activity. It brings visible HTTP and WebSocket events from that one captured occurrence together on a relative timeline, including failures and modifications. HTTP and WebSockets remain separate working views. Open an event to use its existing Inspector; ← Traffic returns to Traffic.
Current Traffic visibility settings apply. Copy activity copies bounded, sanitised metadata without bodies, credentials, URL queries or hashes. Activity is a temporary projection of retained traffic, not a separately saved library and not a Result. Stop and reload preserve it while its records remain retained; Clear traffic deletes it.
12. Save as Test
Choose Save as Test when a useful network scenario is worth repeating. A Test is a reusable definition: request/response or message behavior, matching conditions, and optional guidance. Choose an existing Test Plan or explicitly create a new one. A one-off action is not a saved Test or a Result.
If saved data is locked, protect or unlock the local library first. Then complete the Test form and save. Repeat the Test after a fix or product change rather than rebuilding its setup. Test Plans organise manual checks; they do not run automatically.
13. Starting state
Use Starting state to describe what must be true before this check: for example, “Open a cart containing one item.” This optional guidance is saved with the Test and shown in its testing context. It does not automatically set up the application.
14. Expected behavior
Use Expected behavior to describe what the tester should see or be able to do: for example, “Show the unavailable state and recover after a successful retry.” This optional guidance helps you repeat the same behavioral or regression check. You assess the actual application yourself.
15. Ready / Send
Send executes the backend HTTP request or outgoing App → Server message. Ready arms a supported frontend HTTP response or incoming Server → App behavior and waits for fresh matching traffic after you repeat the app action. Ready is not a success verdict.
Review the Test/Plan context, Starting state and Expected behavior in Current Test. Follow the execution state, inspect the application and record your verdict. No change is required for a valid unchanged check. Stop or Cancel cannot reverse a server action already performed.
16. Works correctly / Found a problem
After running a saved Test, choose Works correctly if the application behaves as expected, or Found a problem and describe the difference before saving the Result. Network verification and an applied modification do not establish business success; the verdict is your manual assessment.
17. Results and evidence
A Result is an immutable record of one completed manual check. It keeps the verdict, notes and applied scenario snapshot, plus any evidence you selected for that run. Editing a Test later does not rewrite its previous Result. Activity is temporary; Results belong to the saved library.
Full retains the available body after recognised sensitive values are removed or replaced; Selected JSON retains selected fields. Automatic detection may miss sensitive values. Full cannot restore unavailable bytes. The Test configuration and its Result snapshot may still contain values saved for the scenario. If a limit is exceeded, the extension reports an error instead of silently trimming evidence.
Export Results as Markdown with the available option to include already saved evidence. Excluding evidence from an export leaves it out of that file; it does not delete evidence already stored in the library. Use the dedicated evidence-removal action to delete saved evidence.
18. Stop vs Clear traffic
Stop stops collecting new traffic and ends active execution. It preserves retained HTTP, WebSocket, Actions and Activity for inspection. Start or Resume continues collection without deleting those records.
Clear traffic is destructive: use the trash control and confirm Clear captured traffic? to delete the temporary captured HTTP/WebSocket, Activity and navigation history. Capture can continue. Cancel, closing the dialog or Escape preserves the history. Saved Tests, Test Plans and Results are not affected by Clear traffic.
Clear also removes temporary WebSocket pairing context and related temporary work. It does not close the app’s native socket or guarantee that its previous modification capability is retained. Reconnect a supported socket when needed. Clear traffic and Stop are not Lock.
19. Detached Window
Open Detached Window to keep the full application viewport available while PayloadPigeon runs in a separate window. It stays bound to the exact captured tab. Focus page activates that tab; Return to Side Panel restores the Side Panel before closing Detached Window.
Closing the last controlling PayloadPigeon surface ends Capture; the Floating Monitor cannot keep it running alone. Chrome owns the debugging banner and can display it across the browser. The banner does not mean every tab is being captured.
20. Floating Monitor
The optional Floating Monitor shows the current testing context over the captured application. It does not own Capture and is suppressed when the Side Panel is open for that same target. It has no payload or sensitive text entry. Works correctly applies to the current saved-Test execution; Found a problem hands off to the full extension UI for the required note.
21. Local saved data
Saved Tests, Test Plans and Results use a local encrypted library. No account or cloud backend is required for that library. One-off Traffic and Modify work before setup. When first saving durable data, set a password and keep the separate recovery key. Unlock covers the extension session in that Chrome profile.
Unlock again after a full Chrome restart, extension reload/update/disable, loss of the session key or explicit Lock. When Saved Data is locked, Test Plans, Results, and Advanced Rules show an Unlock action instead of appearing empty. After you unlock the local library, existing saved items become available again. Empty states are shown only when the unlocked library genuinely contains no corresponding saved items. The recovery key is not a backup; if both password and recovery key are lost while locked, the developer cannot restore access.
Backend Send contacts your selected destination and Playground uses the demo service. Optional anonymous usage telemetry requires opt-in and sends aggregate feature-use counters, not captured traffic. Read Data & Security and the Privacy Policy for the full boundaries.
22. Import and export
Protect or unlock your local library before importing. Choose the file, enter its separate password only for a protected package, review destinations, matching conditions and saved values, then explicitly confirm Import. Teammates use their own local passwords.
JSON and Markdown are readable files. A protected Test Plan package uses a separate file password and is not a complete backup. Review saved data and evidence before sharing; file-based sharing does not provide cloud synchronisation.
23. Current limits and observe-only boundaries
Incognito, cloud synchronisation and automatic Test Plan execution are not supported. Minimum Chrome is 125; this does not mean every browser/OS combination is tested. Backend HTTP Send does not automatically follow redirects. Capture uses Chrome’s debugger/network capabilities for the tab you explicitly select.
Pre-existing sockets, Worker-created sockets, binary-only traffic, unsupported or ambiguously identified connections may remain observe-only. A socket created before instrumentation can require reconnecting; an app that cached the native WebSocket constructor may require reinitialisation or reload. This differs from automatic Actions, which normally work on an already-loaded page once Capture is ready.
Traffic, body retention, imports and local storage are bounded. The installed version reports limits and errors; hidden data is not unlimited archived history.
24. Troubleshooting
- READY has no match. Check the URL, method or message condition, repeat the real page action and check that the connection supports modification.
- No Action after a click. Empty/supporting-only activity creates no filter. Check All traffic, the selected transport and Auto-focus new actions. If Capture says Actions unavailable, use Stop and Start capture this tab to retry observation.
- Current session cannot find credentials. Capture an eligible recent request in the same tab and compatible context, or choose another mode.
- Traffic is empty. Check Capture, Action/search filters and visibility. A cross-origin navigation stops Capture; reload within a captured page preserves retained history.
- Storage write failed. Reduce selected evidence or free profile space. unlimitedStorage does not mean infinite disk.
- Wrong password or unknown file version. Use the recovery key for a forgotten password. Do not force an unsupported import; send support only technical details without real secrets or user data.
Inspector body states
Still loading/retrieving or streaming means collection is in progress; streaming does not promise a final complete body. An incomplete preview contains only a retained prefix, not the whole response. Unavailable means Chrome could not provide the bytes or retrieval failed; waiting indefinitely will not recover them. Released means the retained body was deliberately discarded under retention limits, though metadata may remain inspectable. Empty means there is no body; binary data has separate preview/search limits.
Capture Full Response waits for the next matching request; it does not replay an old request or restore released bytes. Create fresh supported traffic when necessary and inspect the resulting availability state.
25. Practise in Playground
Open the HTTP/WebSocket Playground, start Capture before using its controls and use sample data only. Send a real HTTP request or WebSocket message, inspect the automatic Action, open View activity for its sequence, then modify, save a Test and repeat it.
The demos cover HTTP, WebSocket and a multi-step Workflow. Follow the available lessons; the page sees only its own network results and cannot confirm extension Capture, Save as Test, Ready or your manual verdict.