Skip to main content

API Testing with Jest and Supertest: A Step-by-Step Guide

Photo by Ferenc Almasi on Unsplash


API testing is essential to ensure your endpoints behave as expected across all scenarios. In this guide, we’ll explore how to use Jest and Supertest to test a sample API with various response types, including success, authentication errors, and validation errors. By the end, you’ll understand how to apply these tools to check for different response structures and status codes.

0. Prerequisites: Setting Up Your Environment

Before diving into API testing, it’s important to ensure that your development environment is properly set up. Here’s what you need to do:

Step 1: Install Node.js and npm

Node.js is a JavaScript runtime that allows you to run JavaScript code on the server side. It comes with npm (Node Package Manager), which helps you install and manage packages.

Installation Steps:

  • Download and install Node.js from the official website.
  • To verify the installation, open your terminal and run:
node -v
npm -v

This should display the installed versions of Node.js and npm.

Step 2: Create a New Project Directory

Open your terminal and create a new directory for your project. Navigate into that directory:

mkdir api-testing-example
cd api-testing-example

Alternatively, you can create a new directory using the file explorer and then open the terminal in that location.

Step 3: Initialize a New Node.js Project

Run the following command to create a package.json file, which will manage your project dependencies:

npm init -y

The -y flag automatically answers "yes" to all prompts, creating a default package.json file.

Step 4: Open the Project Directory in Your Code Editor

Open the project directory you just created in your code editor of choice. If you do not have one yet, I recommend using Visual Studio Code (VS Code). Additionally, you can explore the following extensions in VS Code that are tailored for testing frameworks:

Jest by Orta — Visual Studio Code Extension

1. Getting Started with Jest and Supertest

Jest is a powerful testing framework, while Supertest simplifies HTTP request testing. Together, they’re a great duo for testing RESTful APIs.

Installation

To set up Jest and Supertest, run:

npm install --save-dev jest supertest

Make sure your project includes the necessary configuration for Jest, either in package.json or jest.config.js.

2. About the PayMaya Checkout API

We’ll use the PayMaya Checkout API sandbox endpoint as our testing target. This API lets us simulate a checkout process with different response codes:

  • 200 — Successful checkout
  • 400 — Invalid request (e.g., missing parameters)
  • 401 — Unauthorized (e.g., invalid credentials)

API Details

Sample Request

Here’s the structure we’ll use for our test:

{
"totalAmount": {
"value": 100,
"currency": "PHP"
},
"requestReferenceNumber": "TEST123"
}

Sample Responses

Here’s the structure we’ll expect for our test:

HTTP Status 200 Response

{
"checkoutId": "fa4da2ff-dcda-4367-a97d-0c9445147b73",
"redirectUrl": "https://payments-web-sandbox.paymaya.com/v2/checkout?id=fa4da2ff-dcda-4367-a97d-0c9445147b73"
}

HTTP Status 401 Response

{
"error": "Invalid authentication credentials. Kindly verify if the key you are using is correct.",
"code": "K003",
"reference": "8626ce33-3689-42f8-8ac4-4584631feb93"
}

HTTP Status 400 Response

{
"code": "2553",
"message": "Missing/invalid parameters.",
"parameters": [
{
"description": "value must be a number",
"field": "totalAmount.value"
}
]
}

3. Setting Up Jest and Supertest

We’ll create a test file named checkout.test.js and write tests for each response case.

Step 1: Require Supertest and Setup Base URL

const request = require('supertest'); 
const baseUrl = 'https://pg-sandbox.paymaya.com';

Step 2: Setting up Common Data

Define the headers and request payload at the top of the file for reusability.

const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Basic cGstWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo='
};

const validPayload = {
totalAmount: {
value: 100,
currency: 'PHP'
},
requestReferenceNumber: 'TEST123'
};

4. Writing Tests with Jest and Supertest

Testing a Successful Checkout (200 Response)

In this test, we’ll check that the status code is 200, and the response body includes checkoutId and redirectUrl.

describe('POST /checkout - Successful Checkout', () => {
it('should return 200 with checkoutId and redirectUrl', async () => {
const response = await request(baseUrl)
.post('/checkout/v1/checkouts')
.set(headers)
.send(validPayload);

expect(response.status).toBe(200);
expect(response.body).toHaveProperty('checkoutId');
expect(response.body).toHaveProperty('redirectUrl');
});
});

Testing Unauthorized Access (401 Response)

This test will simulate a 401 response by using an incorrect Authorization header.

describe('POST /checkout - Unauthorized Access', () => {
it('should return 401 for invalid credentials', async () => {
const invalidHeaders = { ...headers, Authorization: 'Basic invalidToken' };

const response = await request(baseUrl)
.post('/checkout/v1/checkouts')
.set(invalidHeaders)
.send(validPayload);

expect(response.status).toBe(401);
expect(response.body).toHaveProperty('error', 'Invalid authentication credentials. Kindly verify if the key you are using is correct.');
expect(response.body).toHaveProperty('code', 'K003');
});
});

Testing Missing/Invalid Parameters (400 Response)

To simulate a 400 response, we’ll send an invalid totalAmount.value parameter (a string instead of a number).

describe('POST /checkout - Invalid Parameters', () => {
it('should return 400 for invalid parameters', async () => {
const invalidPayload = { ...validPayload, totalAmount: { value: 'invalid', currency: 'PHP' } };

const response = await request(baseUrl)
.post('/checkout/v1/checkouts')
.set(headers)
.send(invalidPayload);

expect(response.status).toBe(400);
expect(response.body).toHaveProperty('code', '2553');
expect(response.body).toHaveProperty('message', 'Missing/invalid parameters.');
expect(response.body.parameters).toEqual(
expect.arrayContaining([
expect.objectContaining({
description: 'value must be a number',
field: 'totalAmount.value'
})
])
);
});
});

5. Best Practices for API Testing with Jest and Supertest

  1. Use describe to Group Tests
    Organize tests by scenario (e.g., successful checkout, unauthorized access) using describe. This structure makes tests easy to read and debug.
  2. Reuse Headers and Payloads
    Define commonly used headers and request payloads outside individual tests to avoid redundancy and ensure consistency.
  3. Chain .expect Statements
    Chain multiple assertions within one test for a clean and concise test structure. For instance, verify both the status and body properties in a single test.
  4. Check for Array Elements
    If the response contains an array, use expect.arrayContaining and expect.objectContaining to validate specific fields within the array.
  5. Mock External APIs When Needed
    If your API integrates with external services, mock them to prevent real requests and isolate your API’s behavior during testing.
  6. Use hasAssertions When Required
    Ensure tests always make assertions. Using expect.hasAssertions() can help catch cases where a test may not actually perform checks.
  7. Separate Positive and Negative Cases
    Test both valid and invalid requests to confirm the API handles errors properly.

6. Complete Example of All Tests Together

Here’s the full example to provide a clear and cohesive test file:

const request = require('supertest');
const baseUrl = 'https://pg-sandbox.paymaya.com';

const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Basic cGktWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo='
};

const validPayload = {
totalAmount: {
value: 100,
currency: 'PHP'
},
requestReferenceNumber: 'TEST123'
};

describe('POST /checkout API Tests', () => {

it('should return 200 with checkoutId and redirectUrl', async () => {
const response = await request(baseUrl)
.post('/checkout/v1/checkouts')
.set(headers)
.send(validPayload);

expect(response.status).toBe(200);
expect(response.body).toHaveProperty('checkoutId');
expect(response.body).toHaveProperty('redirectUrl');
});

it('should return 401 for invalid credentials', async () => {
const invalidHeaders = { ...headers, Authorization: 'Basic invalidToken' };

const response = await request(baseUrl)
.post('/checkout/v1/checkouts')
.set(invalidHeaders)
.send(validPayload);

expect(response.status).toBe(401);
expect(response.body).toHaveProperty('error', 'Invalid authentication credentials. Kindly verify if the key you are using is correct.');
expect(response.body).toHaveProperty('code', 'K003');
});

it('should return 400 for invalid parameters', async () => {
const invalidPayload = { ...validPayload, totalAmount: { value: 'invalid', currency: 'PHP' } };

const response = await request(baseUrl)
.post('/checkout/v1/checkouts')
.set(headers)
.send(invalidPayload);

expect(response.status).toBe(400);
expect(response.body).toHaveProperty('code', '2553');
expect(response.body).toHaveProperty('message', 'Missing/invalid parameters.');
expect(response.body.parameters).toEqual(
expect.arrayContaining([
expect.objectContaining({
description: 'value must be a number',
field: 'totalAmount.value'
})
])
);
});

});

7. Update the Code with softAssert Function

Step 1: Define softAssert and errorCollector

Add softAssert at the top of the test file. This function will collect errors without stopping the test, allowing all assertions to be checked.

function softAssert(assertFn, errorCollector) {
try {
assertFn(); // Run the passed-in assertion function
} catch (error) {
errorCollector.push(error.message); // Store error message if it fails
}
}

Step 2: Implementing softAssert in Tests

Here’s how to use softAssert in our tests to check multiple assertions without immediately stopping the test on failure.

const request = require('supertest');
const baseUrl = 'https://pg-sandbox.paymaya.com';

const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Basic cGktWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo='
};

const validPayload = {
totalAmount: {
value: 100,
currency: 'PHP'
},
requestReferenceNumber: 'TEST123'
};

describe('POST /checkout API Tests', () => {
it('should return 200 with checkoutId and redirectUrl', async () => {
const errorCollector = []; // Initialize error collector array

const response = await request(baseUrl)
.post('/checkout/v1/checkouts')
.set(headers)
.send(validPayload);

softAssert(() => expect(response.status).toBe(200), errorCollector);
softAssert(() => expect(response.body).toHaveProperty('checkoutId'), errorCollector);
softAssert(() => expect(response.body).toHaveProperty('redirectUrl'), errorCollector);

// Throw error if there were any assertion failures
if (errorCollector.length > 0) {
throw new Error("Test failed with the following errors:\n" + errorCollector.join("\n"));
}
});

it('should return 401 for invalid credentials', async () => {
const errorCollector = [];

const invalidHeaders = { ...headers, Authorization: 'Basic invalidToken' };

const response = await request(baseUrl)
.post('/checkout/v1/checkouts')
.set(invalidHeaders)
.send(validPayload);

softAssert(() => expect(response.status).toBe(401), errorCollector);
softAssert(() => expect(response.body).toHaveProperty('error', 'Invalid authentication credentials. Kindly verify if the key you are using is correct.'), errorCollector);
softAssert(() => expect(response.body).toHaveProperty('code', 'K003'), errorCollector);

if (errorCollector.length > 0) {
throw new Error("Test failed with the following errors:\n" + errorCollector.join("\n"));
}
});

it('should return 400 for invalid parameters', async () => {
const errorCollector = [];

const invalidPayload = { ...validPayload, totalAmount: { value: 'invalid', currency: 'PHP' } };

const response = await request(baseUrl)
.post('/checkout/v1/checkouts')
.set(headers)
.send(invalidPayload);

softAssert(() => expect(response.status).toBe(400), errorCollector);
softAssert(() => expect(response.body).toHaveProperty('code', '2553'), errorCollector);
softAssert(() => expect(response.body).toHaveProperty('message', 'Missing/invalid parameters.'), errorCollector);
softAssert(() => expect(response.body.parameters).toEqual(
expect.arrayContaining([
expect.objectContaining({
description: 'value must be a number',
field: 'totalAmount.value'
})
])
), errorCollector);

if (errorCollector.length > 0) {
throw new Error("Test failed with the following errors:\n" + errorCollector.join("\n"));
}
});
});

Complete Full Code Example Using softAssert in Tests

Here’s the full example with softAssert to provide a clear and cohesive test file:

const request = require('supertest');
const baseUrl = 'https://pg-sandbox.paymaya.com';

const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Basic cGktWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo='
};

const validPayload = {
totalAmount: {
value: 100,
currency: 'PHP'
},
requestReferenceNumber: 'TEST123'
};

function softAssert(assertFn, errorCollector) {
try {
assertFn(); // Run the passed-in assertion function
} catch (error) {
errorCollector.push(error.message); // Store error message if it fails
}
}

describe('POST /checkout API Tests', () => {
it('should return 200 with checkoutId and redirectUrl', async () => {
const errorCollector = []; // Initialize error collector array

const response = await request(baseUrl)
.post('/checkout/v1/checkouts')
.set(headers)
.send(validPayload);

softAssert(() => expect(response.status).toBe(200), errorCollector);
softAssert(() => expect(response.body).toHaveProperty('checkoutId'), errorCollector);
softAssert(() => expect(response.body).toHaveProperty('redirectUrl'), errorCollector);

// Throw error if there were any assertion failures
if (errorCollector.length > 0) {
throw new Error("Test failed with the following errors:\n" + errorCollector.join("\n"));
}
});

it('should return 401 for invalid credentials', async () => {
const errorCollector = [];

const invalidHeaders = { ...headers, Authorization: 'Basic invalidToken' };

const response = await request(baseUrl)
.post('/checkout/v1/checkouts')
.set(invalidHeaders)
.send(validPayload);

softAssert(() => expect(response.status).toBe(401), errorCollector);
softAssert(() => expect(response.body).toHaveProperty('error', 'Invalid authentication credentials. Kindly verify if the key you are using is correct.'), errorCollector);
softAssert(() => expect(response.body).toHaveProperty('code', 'K003'), errorCollector);

if (errorCollector.length > 0) {
throw new Error("Test failed with the following errors:\n" + errorCollector.join("\n"));
}
});

it('should return 400 for invalid parameters', async () => {
const errorCollector = [];

const invalidPayload = { ...validPayload, totalAmount: { value: 'invalid', currency: 'PHP' } };

const response = await request(baseUrl)
.post('/checkout/v1/checkouts')
.set(headers)
.send(invalidPayload);

softAssert(() => expect(response.status).toBe(400), errorCollector);
softAssert(() => expect(response.body).toHaveProperty('code', '2553'), errorCollector);
softAssert(() => expect(response.body).toHaveProperty('message', 'Missing/invalid parameters.'), errorCollector);
softAssert(() => expect(response.body.parameters).toEqual(
expect.arrayContaining([
expect.objectContaining({
description: 'value must be a number',
field: 'totalAmount.value'
})
])
), errorCollector);

if (errorCollector.length > 0) {
throw new Error("Test failed with the following errors:\n" + errorCollector.join("\n"));
}
});
});

Explanation

  1. Initialize errorCollector
    Each test initializes its own errorCollector array to store errors.
  2. Run Assertions with softAssert
    Instead of using expect directly, we wrap each expect in a softAssert call, passing in the assertion and the errorCollector.
  3. Check and Throw Collected Errors
    At the end of each test, if any errors were collected, they are thrown together. This allows all assertions in the test to be evaluated without halting on the first failure.

Benefits

  • Comprehensive Testing: Each test validates all required properties in the response before failing.
  • Readable Errors: When the test fails, it provides a consolidated error message listing all failed assertions.

This approach will make your tests more robust by allowing multiple assertions to be tested at once, providing complete feedback on each test case.

Conclusion

With Jest and Supertest, API testing becomes manageable and precise. This setup lets you verify response codes, headers, and response body content effectively. As you gain confidence, consider adding more tests for additional endpoints and experimenting with mocking and setup/teardown options.

Next Steps

Explore advanced Jest features like mocking, snapshots, and test coverage to take your API testing to the next level!

Comments

Popular posts from this blog

Understanding Number Systems: Decimal, Binary, and Hexadecimal

In everyday life, we use numbers all the time, whether for counting, telling time, or handling money. The number system we’re most familiar with is the   decimal system , but computers use other systems, such as   binary   and   hexadecimal . Let’s break down these number systems to understand how they work. What is a Number System? A number system is a way of representing numbers using a set of symbols and rules. The most common number systems are: Decimal (Base 10) Binary (Base 2) Hexadecimal (Base 16) Each system has a different “base” that tells us how many unique digits (symbols) are used to represent numbers. Decimal Number System (Base 10) This is the system we use daily. It has  10 digits , ranging from  0 to 9 . Example: The number  529  in decimal means: 5 × 1⁰² + 2 × 1⁰¹ + 9 × 1⁰⁰ =  500 + 20 + 9 = 529 Each position represents a power of 10, starting from the rightmost digit. Why Base 10? Decimal is base 10 because it has 10 digits...

How to Monetize Your API as an Individual Developer While Hosting on Your Own Server?

In the API economy, cloud services like AWS, Google Cloud, and Azure offer many conveniences, such as scaling and infrastructure management. However, some developers prefer more control and autonomy, opting to host their APIs on personal servers. Whether for cost efficiency, data privacy, or customization, hosting your own API comes with both advantages and challenges. But, even without cloud platforms, there are effective ways to monetize your API. This guide will explore how individual developers can successfully monetize their APIs while hosting them on their own servers. Why Host Your API on Your Own Server? Hosting your own API gives you full control over the infrastructure and potentially lower long-term costs. Here’s why some developers choose this approach: Cost Control : Instead of paying ongoing cloud fees, you may opt for a one-time or lower-cost hosting solution that fits your budget and resource needs. Data Ownership : You have full control over data, which is critical if ...

The Weight of Responsibility: A Developer’s Journey to Balance Passion and Reality

For the past several years, Eddie has been on a steady climb in his career as a developer, but recently, he found himself at a crossroads — caught between the weight of his responsibilities and the desire to pursue his true passions. His journey began with a three-month internship as a web developer, which led to nearly four years in an application developer role. After that, he spent almost a year as a systems associate, managing tasks across systems analysis, quality assurance, and business analysis. Eventually, he returned to full-time software development for another two years before transitioning into more complex roles. For over a year, he worked as a multi-role software developer and database administrator before stepping into his current position as a senior software developer, database administrator, and cloud administrator — occasionally handling security tasks as well. Now, with over 8 years of professional experience, he also leads a small team of developers, which has been...

The Hidden Costs of Overdesign and Bad Practices in API Systems

In software development, simplicity and clarity are often sacrificed in favor of overly complex solutions. While it can be tempting to add more features and intricate designs to ensure robustness, overdesign and poor practices can have significant consequences. They frustrate developers, lead to inefficiencies, increase costs, and put unnecessary strain on system resources.  A recent example involving a team that has faced challenges with complexity highlights the pitfalls of such an approach. Overdesign: The Problem of Too Much Complexity Overdesign occurs when systems are built with more complexity than necessary. This might manifest in bloated APIs, convoluted data flows, or excessive checks and processes that don’t add substantial value. The goal is often to anticipate future problems, but this approach typically results in cumbersome systems that are difficult to maintain and scale. In one case, a company found itself paying a hefty price just to host two API services and a po...

Selenium for Beginners: What, Where, When, and Why to Use It in Automated Testing

In today’s software development landscape, automated testing has become essential for delivering robust applications efficiently. Among various automated testing tools,   Selenium   stands out as one of the most widely used and beginner-friendly options. As you embark on your journey into automated testing, it’s crucial to understand the   what, where, when, and why   of using Selenium. In this guide we will run through these essentials and help you decide if Selenium is the right tool for you. What is Selenium? Selenium  is an open-source framework used primarily for automating web browsers. It enables developers and testers to write scripts that interact with websites, simulating actions like clicking buttons, filling out forms, and navigating pages, which allows for comprehensive automated testing. Selenium supports multiple programming languages, including Python, Java, C#, and JavaScript, making it flexible for teams with different coding preferences. Key C...