# Assertions

Assertions allow you to define expected behaviour of a test. Using assertions, you can automate validation of API response every time a test runs and get a pass/fail status for the test. This works very similar to how asserts work in unit testing. We expect the assertions to be in JS using the Chai.js expect syntax (pun intended 🙃). If you've already used Chai.js or have some experience with unit testing, this should be straightforward for you.

Let's look at a simple example.

For a bank account creation API, this is the expected response:

{
  "response": {
    "success": true,
    "api_id": "ACCT-1123",
    "account_id": "119471389591"
  },
  "headers": {
    "content-length": "81",
    "content-type": "application/json",
    "date": "Mon, 30 Sep 2024 04:28:36 GMT",
    "server": "Werkzeug/2.0.1 Python/3.9.6"
  },
  "statusCode": 200,
  "error": null,
  "elapsedTime": "290ms"
}

Assertions for this expected response will look something like this:

expect(response.response, "success key should exist").to.have.property('success');  // check if field is present
expect(response.response.success, "success key should be a boolean").to.be.a('boolean');  // check datatype
expect(response.response, "account_id key should exist").to.have.property('account_id');
expect(response.response.account_id, "account_id key should be a string").to.be.a('string');
expect(response.response.api_id.startsWith("ACCT-"), "api_id should start with ACCT-").to.equal(true);  // check if prefix is correct
expect(response, "statusCode key should exist").to.have.property('statusCode');
expect(response.statusCode, "statusCode key should be a number").to.be.a('number');
expect(response.statusCode, "statusCode shoudl be 200").to.equal(200);  // check if field value is correct

Now depending on the test, you'll add/remove some assertions. For example, for a test which check if the API handles auth token properly by entering wrong auth token, the status code assertions will look like this:

expect(response, "statusCode key should exist").to.have.property('statusCode');
expect(response.statusCode, "statusCode key should be a number").to.be.a('number');
expect(response.statusCode, "statusCode shoudl be 200").to.equal(403);  // the api should fail with 4xx for wrong auth

Note that the top-level response object is called response. This object contains the API response (under response field) along with other additional fields like headers, statusCode, elapsedTime (response time of the API), etc. that might be useful for assertions. Fields inside the response object can be accessed like response.<field-name>.

You would have noticed that the top-level object and the API response fields are both called response. This happened because of an early design oversight and will be rectified soon.

Assertions are executed after running a test. You can see them under the "Assertions" tab in Test details.

The results are shown under the "Assertion Results" tab. Here, you'll see the status for every assertion you've added.

All assertions are executed independently of each other. So even if 1 assertion fails, all assertions after it will still get executed.

We mark a test as failed even if a single assertions fails. This status is shown under the "Assertions" column of Test table. You will see a blank or "N/A" here, if you've not written assertions for a test.

The pass/fail count under Test counts is calculated using a test's pass/fail status. Note that this count changes only if your tests have assertions.