Skip to main content

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

Image
By mvryo

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!

Labels:

Comments

Post a Comment

Popular posts from this blog

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

By mvryo
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 Components of Selenium: S
Post a Comment
Read More »

ORM vs Non-ORM: Choosing the Right Approach for Your Database Queries

By mvryo
As developers, we often face decisions that affect how we interact with databases in our applications. One critical choice is whether to use an ORM (Object-Relational Mapping) tool or stick with traditional non-ORM methods like writing raw SQL queries or using query builders. Each approach has its advantages and disadvantages, and the decision depends on several factors, such as the complexity of the queries, project requirements, and the design of the database itself. In this guide, we’ll explore the key differences between ORM and non-ORM approaches, discuss when to use each, and highlight the pros and cons to help you make the right decision for your next project. What is an ORM? An ORM is a tool or library that allows developers to interact with a relational database using an object-oriented paradigm. It maps database tables to classes, rows to objects, and columns to attributes, allowing developers to work with data using their programming language’s syntax rather than writing SQL
Post a Comment
Read More »

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

By mvryo
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
Post a Comment
Read More »

Avoiding Confusion in API Design: The Importance of Clear Responses

By mvryo
In today’s fast-paced software development landscape, APIs play a crucial role in connecting services and enabling functionality. However, poor design choices can lead to confusion and inefficiency for both developers and users. One such choice is the omission of a response body for successful requests, a practice I recently encountered in an enterprise API designed for bill payments. The Case of the No-Response API The API in question serves two main endpoints: one for inquiring about account validity and another for confirming payment. When successful, the API returned a  200 OK  status but no response body. This design choice led to significant confusion during our integration process. Even the internal team who developed the said API struggled to justify this approach, revealing a lack of clarity around the rationale behind it. Pros of This Design Choice While the intention behind this design may have been to streamline responses, several potential benefits can be identified: Reduc
Post a Comment
Read More »

The Hidden Costs of Overdesign and Bad Practices in API Systems

By mvryo
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 portal
Post a Comment
Read More »