Postman’s pm.test() is your secret weapon for ensuring API responses are exactly what you expect, but most folks misuse it, treating it like a glorified console.log instead of a precise validation tool.
Let’s see it in action. Imagine you’re hitting an API endpoint that returns user data. You’ve made the request, and the response is sitting there. Now, you want to make sure the status is 200 OK, the Content-Type is application/json, and a specific user property, email, is present and looks like an email.
Here’s how you’d write those checks in the "Tests" tab of your Postman request:
// Check if the response status code is 200 OK
pm.test("Status code is 200", function () {
pm.response.to.have.status(200);
});
// Check if the Content-Type header is application/json
pm.test("Content-Type is application/json", function () {
pm.response.to.have.header("Content-Type", "application/json");
});
// Parse the JSON response body
const responseData = pm.response.json();
// Check if the 'email' property exists and is not empty
pm.test("Email property exists and is not empty", function () {
pm.expect(responseData).to.have.property('email');
pm.expect(responseData.email).to.be.a('string').and.not.empty;
});
// Check if the 'email' property is a valid email format
pm.test("Email is a valid email format", function () {
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
pm.expect(responseData.email).to.match(emailRegex);
});
// Check a specific nested property, e.g., user's first name
pm.test("User's first name is correct", function () {
pm.expect(responseData.name.first).to.eql("John");
});
// Check if an array has a certain length
pm.test("Should return exactly 5 items in the 'tags' array", function () {
pm.expect(responseData.tags).to.have.lengthOf(5);
});
This isn’t just about catching errors; it’s about building confidence in your API’s behavior. Each pm.test() is a micro-assertion, a tiny contract between your client and the server. When all these contracts are met, you know your API is behaving predictably.
The core problem pm.test() solves is the ambiguity of API responses. Without explicit checks, you’re relying on manual inspection or just assuming things are okay. pm.test() transforms that ambiguity into concrete, verifiable facts. It allows you to define the expected state of a response – its status, headers, and body structure and content – and then automatically verify if that state is achieved. This is crucial for automated testing, CI/CD pipelines, and even just for debugging complex integrations.
Internally, Postman’s test runner executes the JavaScript code within your "Tests" tab after each request. It uses Chai.js assertion library under the hood, providing a rich set of matchers like to.eql(), to.have.property(), to.be.a(), to.match(), and to.have.lengthOf(). Each pm.test() block is essentially a named assertion. If any assertion within a block fails, the entire block is marked as failed. The results are then displayed in the "Test Results" tab, giving you a clear pass/fail status for each test you’ve written.
The most surprising thing is how much you can achieve with simple JSON parsing and regex. Many developers think advanced schema validation is required, but for common cases, pm.response.json() and a few well-crafted pm.expect() calls cover 90% of your needs. You can check for data types, specific values, the presence of keys, and even complex patterns within strings, all without needing external schema files.
You can also chain assertions for more complex conditions. For example, checking if a user ID is a positive integer:
pm.test("User ID is a positive integer", function () {
pm.expect(responseData.id).to.be.a('number').and.be.above(0).and.to.be.integer;
});
This makes your tests more robust and your intentions clearer. It’s about expressing the intent of the test in a readable way.
Once you’ve mastered basic assertions, you’ll naturally want to start using variables within your tests to make them dynamic and reusable.