Assertion Results and Custom Checks

Overview

When a test runs, each of its assertions produces a row in the results: what was expected, what was found, and whether it passed. Shift-Left Studio makes those rows easier to read and act on:

• Every result row is numbered to match the assertion in the editor, and custom checks show their name, so you can tell nine custom checks apart.
• A custom check's Expected and Actual cells say what the check was looking for and what it found, instead of "custom logic to pass / passed".
• A custom check can write log lines that appear under its result row.
• You can copy what any results tab shows as plain text.
• You can state a check in words to the Project Assistant and it builds it for you.
• An assertion's expected value can be a dynamic token, for example a value from a data row.

Key concepts

Before you begin

• Open a test in the Test Workbench (edit, run and see results on one screen).
• To ask the assistant to build a check, the Project Assistant must be available in your workspace and an AI provider configured under Settings → AI Settings.

Step 1 — Find the row for a specific assertion

1. Run the test.
2. In the results pane, open the Assertions tab.
3. Each row carries a #N badge. Hover it to see Assertion N in the editor. That is the card with the same number on the editor's Assertions tab.
4. A custom check's row reads Custom Assertion — <name>, where the name is the check's own name, for example the pm.test name from an imported Postman collection. A field check shows its path, for example Field Contains — data.message.

Note: For runs recorded before numbering existed, Studio matches rows to assertions by position only when the assertion type at that position agrees. A row it can't match safely shows no number rather than a wrong one.

Step 2 — Read Expected and Actual for a custom check

For built-in assertions, Expected and Actual are the values compared, for example Expected 201, Actual 200. For a custom check, Studio fills the two cells from what the run actually produced, in this order:

When a check passes and nothing more specific is known, Actual repeats Expected, the same way Expected 200 / Actual 200 reads for a status check. Studio never guesses Expected and Actual by reading your script's text, because a confident guess that is sometimes wrong is worse than a plain placeholder.

If the script throws an error, Actual reads error: <message>, so you can tell a broken script apart from a failed check.

Step 3 — Write a custom check that explains itself

1. On the editor's Assertions tab, add an assertion and choose Custom Assertion.
2. Write the logic. Your script can use these names: response, request, responseTime, assertion, utils and log. The response body is response.data and the status code is response.status.
3. Return either true/false, or an object with passed and, optionally, reason, expected and actual.
4. Call log(...) for anything that helps you read a failure later.

Example:

const items = response.data.items || [];
log('items returned:', items.length);
return {
  passed: response.status === 200 && items.length === 3,
  expected: 'status 200 and 3 items',
  actual: `status ${response.status} and ${items.length} items`,
};

Log lines appear in a Script log block under the result row, and in the Logs tab prefixed [SCRIPT]. Studio keeps up to 50 lines per check, each up to 300 characters.

Tip: Returning expected and actual is the most useful thing a custom check can do. It turns a wall of identical "passed" rows into rows that say what each one checked.

Step 4 — Copy a results tab

1. In the results pane, open the tab you want: Assertions, Response, Request, Variables or Logs.
2. Click Copy. The button changes to Copied (or Copy failed if your browser blocked the clipboard).

Studio copies what the tab shows, as readable text, not the raw run record. On the Assertions tab, for example, each row is copied as its number, name, verdict, expected and actual value. This is handy for pasting into a bug report or a chat message.

Step 5 — Ask the assistant to build a check you describe

You can describe a check in plain words and let the Project Assistant build it.

1. Open the Project Assistant from the test, or from the floating launcher.
2. Say what the check should do, for example "Change assertion 6 so it checks the body is an object" or "Add a check that data.total equals the number of items."
3. The assistant offers a change card showing exactly which assertion it adds or replaces.
4. Review the card and accept it. Nothing is changed until you accept.

How the assistant builds it:

• It uses a built-in assertion type when one fits. A check on the body's shape, for example, becomes Response Is Object, with no AI-written code.
• Only when no built-in type fits does it write a custom script, and that script must compile and must call log(...) so its result can be read.
• It refers to assertions by the numbers you see in the editor and in the results.
• If the test's last run was analyzed, the card shows that verdict as a note. When you state the check you want, the assistant builds it rather than refusing because of an earlier verdict.

Note: Like every change the assistant offers, the new assertion goes through the same checks as any other repair. For example, it won't weaken a negative test into one that can never fail.

Step 6 — Use dynamic tokens in expected values

An assertion's expected value can contain a token that is filled in at run time. In the value field, type {{ to pick one.

• In a data-driven test, {{row.COLUMN}} uses the value from the current data row, for example {{row.EXPECTED_STATUS}} for the status each row should get back.
• A value saved by an earlier test's data extraction can be used by name, for example {{orderId}}.

Tokens are resolved only in the expected value. The field path or header name a check reads from is never treated as a template.

Status-code and other number-type assertions still accept tokens: the value field is a text box so you can type {{row.EXPECTED_STATUS}}.

Generating checks from test-data sheets. When you upload a test-data sheet, columns named EXPECTED_STATUS (or EXPECTED_STATUSCODE, EXPECTED_HTTPSTATUS, EXPECTED_CODE, EXPECTED_RESPONSECODE) and EXPECTED_<path>, such as EXPECTED_data.id, are read as expectations, not inputs. Data-driven tests generated from the sheet check each row's own expected status and fields. That's how one sheet of invalid inputs can mix rows that expect 400 and rows that expect 422.

Understanding the results

Troubleshooting

Best practices

• Give each custom check a clear name, and return expected and actual.
• Prefer built-in assertion types. They explain themselves and run faster than scripts.
• Log the values a check depends on, not the whole response.
• When you report a failing assertion, copy the Assertions tab so the number and values travel with it.

Related articles

• Test cases: open, edit and save
• Postman collection import
• File uploads and form bodies
• Project Assistant actions