5. Writing API Tests & Assertions

An API endpoint that returns a status `200 OK` is not guaranteed to be working correctly. What if the database query failed behind the scenes and returned an empty array instead of user data? To guarantee API correctness, Postman includes a powerful Javascript-based **Testing Sandbox** to write automated assertion scripts under the **Tests** tab.

Understanding `pm.test` and `pm.expect`

Postman uses a testing syntax inspired by BDD (Behavior-Driven Development) frameworks like Mocha and Chai. The basic wrapper is pm.test(), which registers a test name, followed by assertions inside:

pm.test("Descriptive test name here", function () {
    // Assertions go here
    pm.expect(actual_value).to.equal(expected_value);
});

Core Assertion Recipes

Below are the most common, professional test scripts you will use in daily production pipelines:

1. Verifying HTTP Status Codes

pm.test("Status code is 200 OK", function () {
    pm.response.to.have.status(200);
});

pm.test("Status is Created or Success", function () {
    pm.expect(pm.response.code).to.be.oneOf([200, 201]);
});

2. Checking Response Latency (Performance)

Verify that your servers are answering requests quickly under high loads:

pm.test("Response time is under 400ms", function () {
    pm.expect(pm.response.responseTime).to.be.below(400);
});

3. Inspecting Response Headers

pm.test("Content-Type header is JSON", function () {
    pm.response.to.have.header("Content-Type");
    pm.expect(pm.response.headers.get("Content-Type")).to.include("application/json");
});

4. Verifying JSON Payload Values

To inspect returned database values, parse the JSON payload using pm.response.json():

pm.test("Verify user profile values", function () {
    // Parse the response body as a JSON object
    let jsonData = pm.response.json();
    
    // Assertions
    pm.expect(jsonData.username).to.equal("jane_doe");
    pm.expect(jsonData.isActive).to.be.true;
    pm.expect(jsonData.roles).to.be.an("array").that.includes("administrator");
});

5. JSON Schema Validation (Advanced)

Instead of checking every key value manually, you can validate the structure of the entire JSON payload using **Ajv (Another JSON Schema Validator)**, which is built-in:

pm.test("Response matches database schema", function () {
    // Define the expected JSON structure
    const schema = {
        "type": "object",
        "required": ["id", "email", "createdAt"],
        "properties": {
            "id": { "type": "integer" },
            "email": { "type": "string", "format": "email" },
            "createdAt": { "type": "string" }
        }
    };
    
    let responseData = pm.response.json();
    pm.expect(tv4.validate(responseData, schema)).to.be.true;
});

Reviewing Test Results

Once you click Send, look at the **Test Results** tab in the response panel:

• Green **PASS** labels mean your assertions are correct.
• Red **FAIL** labels highlight failures, detailing the discrepancy (e.g. `AssertionError: expected 'john_doe' to equal 'jane_doe'`).