API Test Cases Format: The Test Workbench and Assertions

This is lesson 9.6 of Shift-Left API in Depth. In lesson 9.5 you generated tests from the spec; now you open one and write its checks yourself. For the demo, use the free edition of Shift-Left API and the public sandbox store API.

What's the right API test cases format?

A spreadsheet row, a Postman script, a block of code? Whatever API test cases format you use, every test case needs the same parts. This lesson names them, then shows them in the Shift-Left API test workbench: you add assertions without writing code, run the test, read a failing check, and fix it.

The parts of an API test case

How to write test cases for API testing comes down to three parts:

• The request: a method, a URL, parameters and a body.
• The expected result: the checks the response must pass, on the status code, the fields, the headers and the time it took.
• What the test needs to run: its data and its authentication.

Take API test cases for a GET request: get one order by its ID, expect a 200, and check the order's fields.

From Chai lines to assertion cards

If you've written API automation test cases in code, you've probably used Chai: expect the status to equal 200. Expect the order's status to equal pending, to be one of a list, to be a number. Expect the time to be below a second.

In Shift-Left API, each of those lines is an assertion card: a type, a field, an operator and a value. Same checks, no code. When you import a Postman collection, as in lesson 9.4, its Chai checks become these cards.

When no built-in type fits, a custom assertion runs your own JavaScript and reports what it expected and what it found. With an AI provider set up, you can also describe a check in plain words and the project assistant builds the card for you. Every result reads the same way: expected, and actual.

Open a test in the test workbench

1. In a project built from the sandbox store's spec, click Orders in the Features table.
2. Click Get a single order by ID, then click the test's name to open it in the test workbench.

The test is on the left and its results will be on the right. The editor's tabs run left to right: Request, Assertions, Response, Data and Auth. Read the Request tab from the top: the test's name, the method (GET) and its severity, then Parameters. The ID in the path is the sandbox's pending order, and the endpoint takes one more parameter, expand, which this test doesn't send yet.

Click Run at the top right. The test runs on the Shift-Left Engine against the live sandbox and passes, with one check: status code equals 200. Click Response in the results: the order's status is pending and it has a product ID, but no product details.

Add assertions without code

1. Click the Assertions tab. Each assertion is a card; assertion 1 checks that the status code equals 200. Above the cards are the endpoint's expected responses and Suggest Assertions, which adds a starting set from them.
2. Click Add Assertion and open the Type list. The types are grouped by what they check: the status code, the response body and its type, fields, headers, performance and more. In Fields, choose Quick JSON assertion.
3. Fill the card from the top. Click Field: the list comes from the endpoint's response schema. Pick a field or type the path, data.status.
4. Choose the operator. If you've written Chai assertions, these look familiar: equals, contains, is one of, is of type. Keep equals and type the expected value, pending. The card reads as a sentence: data.status equals pending.
5. Click Add Assertion under the last card and choose Quick JSON assertion again. This field isn't in the schema's list, so type the path yourself, data.product.name, with the expected value Standing Desk.

Read a failing check, and fix it

Click Run. Run saves the test first, then runs it. This time it fails. The failed check is at the top, already open: number 3, data.product.name. Expected: Standing Desk. Actual: nothing; the field is absent. Below it are the two checks that passed. Click View in response: the order came back without a product.

The fix is in the request. The sandbox only includes the product when you ask for it with expand.

1. Click the Request tab.
2. Under Available Parameters, click Add to test next to expand. It's added as a query parameter. Type its value: product.
3. Click Run at the top right.

This time the request asks for the product, and all three checks pass. Click number 3: it found Standing Desk.

Try it yourself

On the sandbox store, open a test for Get a single order by ID on the pending order (ID ffffffff-ffff-ffff-ffff-ffffffffffff). Add a Quick JSON assertion, data.status equals pending. Add data.product.name equals Standing Desk and run it: what does Actual say? Then add the expand parameter, set to product, and run it again.

Recap

• Whatever the API test cases format, a test case is a request and the checks its response must pass.
• In the Shift-Left API test workbench, each check is an assertion card (a type, a field, an operator and a value): the same checks you'd write in Chai, without the code.
• Run shows every check's expected and actual value, and a failing one takes you straight to the response.

The test workbench and assertions are in every edition, including the free one. Next, in lesson 9.7, you run one test against many rows of data from CSV, Excel, JSON and database sources. For more API test cases examples and templates, read how to write API test cases.