Build a reusable API test scenario with variables and checks

Keep the test, not a pile of edited commands

A manual API check often starts with a single request. Then you need to inspect a list, copy an item ID, request its details, and verify an error case. Repeating that sequence by hand makes it easy to reuse yesterday’s ID or overlook a response that changed shape. A small request collection keeps the sequence and its expectations together.

The API test scenarios workbench is built for that session-sized job. It runs up to six requests in order, against one public origin, and produces a report for each step. There is one iteration and no arbitrary scripting. You can inspect the request before sending it, change a check, and run the same collection again when the implementation changes.

Start with an origin and meaningful request names

Set the base origin to the service you are testing, such as https://api.example.com. Keep it to the scheme and host, with an optional supported port. Each step uses a relative path such as /items or /items/42. This keeps the destination visible and prevents a later request from silently sending credentials to a different host.

Name steps for the behavior you expect: List items, Read the first item, and Reject an unknown item are easier to scan than Request 1, Request 2 and Request 3. Select a step to edit its method, headers and body. Move up and Move down change the order; they do not send a request. The page also does not send anything simply because it has loaded an example.

• Set the origin of an authorized test service.
• Add a request with a relative path and the expected HTTP status.
• Add a second request only when it checks another behavior.
• Review the full sequence before pressing Run scenario.

Make the result say whether the behavior is right

A successful network connection is not enough to establish that an integration works. The runner always compares the actual status with the expected status. A 500 response fails a normal 200 check, while a deliberate missing-record test can expect 404 and pass. Optional checks look for text in the body or compare a JSON field with an exact string, number, boolean or null value.

Choose a value type deliberately. The JSON string "42" differs from the number 42, and a missing property differs from null. Use dotted field paths such as data.id or items.0.name. These paths traverse existing own properties; they do not execute expressions. Keep large numeric identifiers as strings in your API rather than relying on floating-point number equality.

Stop after failure is useful when one request depends on another. The remaining steps appear as Skipped, which is different from failing a request that was actually sent. Turn that option off for independent checks when you want a full report even if the first endpoint fails.

Pass an ID to the next request

Ordinary environment variables are named strings. Add a variable called label, then use {{label}} in a path, header or body. If the body is JSON, put the placeholder inside a quoted string: {"label":"{{label}}"}. The renderer escapes quotes and backslashes in the inserted value, keeping the JSON string intact. It does not create a typed object from a placeholder.

To use a response value, open Capture value on the first request. Give the new variable a name such as itemId and select its JSON field, for example items.0.id. The next request can use /items/{{itemId}}. Capture accepts short scalar values, not whole documents or credentials. Define a variable before referencing it; a missing capture makes a dependent request fail visibly instead of sending an unresolved placeholder.

Separate credentials from the portable scenario

A useful test should be reusable without copying its password into every export. Add a declared secret, enter its value in the masked field and reference it in a header, such as Authorization: Bearer {{token}} or X-Access-Token: {{accessToken}}. Secret placeholders are restricted to headers. Credentials in the base URL or query string are rejected.

The workbench excludes secret input values from saved scenarios and exported JSON. Known secret values and sensitive fields are redacted in the response report. This does not mean every unknown sensitive value can be recognized automatically: use synthetic data, review response bodies, and check ordinary variables before sharing an export. A secret sent to your test endpoint is still available to that endpoint.

Save the setup and run it from another interface

Save scenario stores the validated configuration in the current browser. It includes ordinary request bodies and variables, but excludes secret input values and reports. A saved name is replaced when you explicitly save another configuration with that name. Export scenario JSON gives you a file you can review or version with a project. Import only loads the editor and never starts execution.

The same scenario can be sent to the hosted execution API using tool ID mock-apis-api-test-scenarios. The CLI reads the scenario from standard input; the SDK accepts the serialized scenario as input. For secrets, provide a JSON object in the secret option separately from the collection. Avoid printing those values into logs or checking them into source control.

socket-help describe mock-apis-api-test-scenarios
socket-help run mock-apis-api-test-scenarios < api-scenario.json

# SDK
const result = await socket.run(
  "mock-apis-api-test-scenarios",
  JSON.stringify(scenario),
  { secret: JSON.stringify(secretValues) }
);
const report = JSON.parse(result.output);

Read failures and limits honestly

Requests run sequentially with a three-second deadline each and a twenty-second overall bound. Each response is capped at 64 KiB. A truncated response is a failed completeness check, so a partial document cannot quietly pass as a complete response. The report preserves the status, measured time and available body for inspection. Redirects are not followed and cookies are not replayed.

A completed report consumes one hosted run, including a report containing failed checks or request errors. An invalid configuration does not consume a run. Cancellation cannot roll back a POST, PATCH or DELETE that already reached the service, so inspect the destination before retrying a mutation. This tool is a bounded manual test runner; it does not provide continuous monitoring, background execution or a production availability guarantee.