DHIVA LABS · LEARN

Appearance

Workflow testing ​

Users do not call one endpoint. They sign in, look something up, create something, change it, and check it. A workflow test follows such a journey from start to finish, with each request using what the one before returned. It finds the bugs that live between endpoints.

Why single-request tests are not enough ​

Each of these can pass alone and still fail as a sequence:

  • The create returns an id that the read endpoint does not accept.
  • The token from sign-in lacks the permission the next step needs.
  • An update succeeds, but a read afterwards shows the old value.
  • A delete answers 204, and the item is still there.

The building block: a capture ​

A capture takes a value out of a response and stores it in a variable for later requests.

text
token   = body.token
orderId = body.data.id
etag    = header.ETag
code    = status

The left side is the variable's name. The right side says where to read: body. followed by a JSON path, header. followed by a header name, or status. Later requests use the value as {{orderId}} in a URL, a header, a body or the auth settings. See Captures.

Build a workflow ​

The checkout journey from the Shop API sample:

StepRequestCapturesUses
1POST /auth/logintoken = body.token{{email}}, {{password}}
2GET /products
3POST /ordersorderId = body.id{{token}}
4GET /orders/{{orderId}}{{token}}, {{orderId}}
5DELETE /orders/{{orderId}}{{token}}, {{orderId}}

  1. Save the requests into one collection, in the order they must run. A run goes from top to bottom.

  2. Add the captures to steps 1 and 3 in their Captures tabs.

  3. Give every step its own tests: at least the status, and one value that proves the step did its job.

  4. Open the collection's ⋯ menu, choose Run collection, and select Run. In an imported collection that has folders, Run folder runs one folder the same way.

The runner sends the requests in order and passes captured values along. In its results, steps 4 and 5 show the real order id in their URLs.

Design rules ​

Create your own data. A workflow that depends on "order 57 exists" breaks the day someone deletes it. Create what you need at the start.

Clean up at the end. Finish by deleting what you created, so the next run starts clean and the test environment does not fill up.

Test every step. A step with no tests can fail silently and make the next step fail with a confusing message. When step 4 gets a 404, you want step 3 to have already told you the create went wrong.

Keep journeys short. Five to eight steps. A twenty-step workflow fails often and says little. Split it by goal: one for checkout, one for returns.

One journey, one collection or folder. Then each can be run alone, and a failure points at a feature. Folders come with imported collections; ApiWorkbench 1.4.0 has no command to create one, so for a suite built by hand, use a collection per journey.

When a step should decide what happens next ​

Sometimes the path depends on a response: poll until a job finishes, or skip a step when a feature is off. No-code captures cannot branch, but a short script can:

  • postman.setNextRequest('Check the order') jumps to a named request in a run.
  • pm.execution.skipRequest() in a pre-request script skips the current one.

Both are in the script cookbook. Use them sparingly; a straight-line workflow is easier to trust.

Verifying state, not only answers ​

The strongest step in any workflow is the read-after-write:

AfterSendExpect
A createGET the new id200, with the values you sent
An updateGET it againThe new values
A deleteGET it again404

Mocks do not remember

A Mock Studio endpoint answers each request by itself, so a read-after-delete still returns 200. Build and debug the workflow against the mock, then run it against a real test environment to prove state. To imitate a change of state in a mock, a Sequence response can answer pending and then completed on successive calls: see Response strategies.

Workflows under load ​

A journey that works for one user may not for fifty. Both apps can run a workflow with many users at once, each carrying its own captured values:

  • ApiWorkbench: the collection's or folder's ⋯ menu, then Load test. See Load testing.
  • Mock Studio: a flow, with values extracted from one step into {{vars.name}} for the next. See Flows.

Debugging a broken workflow ​

  1. Find the first failing step. Later failures are usually consequences.
  2. Open the Console and read the request that was actually sent. A URL ending in /orders/{{orderId}} means the capture never ran or the path was wrong.
  3. Send the capturing request alone and look at its body. Is the value where the capture's path says it is?
  4. Check the order of the requests.

Next steps ​