Guided: Integration Testing in JavaScript

Welcome to the Guided: Integration Testing with JavaScript Lab

In this lab, you'll explore the fundamentals of integration testing by testing a simple RESTful API for a blogging platform. The application is built with Node.js and Express, and it focuses on writing tests that verify the interaction between different components, including endpoints, request/response handling, and external APIs.

In this lab, you’ll test an API with the following capabilities:

• View a list of users in the system.
• Add new users with name and email.
• View blog posts associated with each user.
• Retrieve blog posts combined with simulated external data.
• Handle common error cases such as missing input or failed external requests.

The core of the application is an Express server with a set of routes that respond to HTTP requests. Throughout this lab, you will write integration tests to ensure those routes work as expected, checking both success and failure scenarios.

Familiarizing with the Project Structure

The application is structured as follows:

• server.js – The main entry point for starting the Express server

• app.js – The Express app containing routes and in-memory data logic

• test.js – A test file where you’ll write integration tests using Supertest and Jest

• package.json – Lists dependencies like express, jest, and supertest, and defines scripts to run the app and tests

This is a server-side project with a simple front end component, but instead of interacting with a user interface, you’ll interact with the application using HTTP requests and assertions in your test code.

How to Get Started

Once the project loads, spend a few minutes reviewing the existing files in the editor. Here’s how you can get started:

• Open app.js to see how the Express routes are defined and how the in-memory data works.

• Open test.js to view the test file where you'll be adding and running integration tests.

• Use the Terminal tab to perform the following command:

npm start

You should see output like this:

Server is running on http://localhost:3000

Switching to the Web Browser tab, you should see the frontend of this service.

Note: Sometimes it's required to refresh the browser. Just press the Refresh icon and the frontend should be displayed.

You can play with the web app and explore its functionality. It's important to keep in mind that you're not going to focus on the service's frontend when writing your tests, but rather on its backend.

Throughout the lab, you’ll build out the integration test cases, step by step.

In the early stages, the tests may fail or be incomplete. That’s okay! You’ll implement the missing logic as you progress through each step.

If you ever get stuck, refer to the solution directory for guidance or validation.

Setting Up Your Test Environment and Writing an Integration Test

Before diving into writing tests, it’s important to understand how the test environment is set up and how each part contributes to the integration testing process.

In this step, you’ll explore the top section of the test.js file, specifically the imports, and the setup and teardown hooks using beforeAll, afterAll, and afterEach.

First, you will learn what integration testing is and why it is important.

What is Integration Testing?

Integration testing focuses on verifying how different parts of an application work together. Instead of testing a single function in isolation (as in unit testing), you test multiple components interacting, like routes, middleware, data storage, and even external services. For example, sending an HTTP POST request to an Express route and ensuring the data is saved correctly mimics how the pieces integrate in real usage.

This is different from unit testing, which tests small, isolated pieces of logic (like a single function) with no dependencies. On the other end of the spectrum is end-to-end testing, which simulates real user behavior through the full application stack—UI, backend, and database—often using tools like Cypress or Playwright. Integration testing sits in the middle: it's faster and more focused than E2E tests, but it still ensures that real-world interactions work correctly between components.

Here is a break down of what is happening at the top of the test script:

Imports

const request = require('supertest');
const { app, users } = require('./app');

• supertest: A library that allows you to simulate HTTP requests to your Express app without starting a real server.
• app: The Express instance you’re testing. Instead of hitting a running server, Supertest injects requests directly into this app.
• users: The in-memory data store that holds user objects. You’ll use it to validate the server-side data state after API calls.
• nock: An HTTP server mocking and expectations library for Node.js.

Test Hooks

beforeAll(() => {
  server = app;
});

afterEach(() => {
  nock.cleanAll();
  resetData();
});

• beforeAll: Runs once before all tests. This is used to assign the app import to the server variable for better readabilty.

• afterEach: Runs after each individual test. Here you’re clearing the mocked objects so each test starts fresh with no leftover data.

Additionally you can also use afterAll, which is performed after all of the tests inside the test file runs.

Right after the test hooks, you should see a describe code block. Here, a group of tests are definied that ideally should target a single piece of functionality. This is called a test suite.

In this case, those tests will target your server's user endpoints.

Before jumping into writing integration tests, you will get familiar with the testing tools you'll be using. Here’s a breakdown of the most common patterns and syntax:

Writing a Test with Jest

Jest provides a simple syntax for structuring your tests.

describe('Some feature or route', () => {
  it('should behave in a certain way', () => {
    // Test logic here
  });
});

• describe(): Groups related tests together.

• it(): Defines an individual test case.

• expect(): Used for assertions, verifying that the code behaved as expected.

For example:

expect(2 + 2).toBe(4);

Making HTTP Requests with Supertest

Supertest is a library that allows you to simulate HTTP requests to an Express app in a test environment.

To use it:

1. Import it and pass your Express app to it.
2. Chain methods to build and send the request.

const request = require('supertest');
const response = await request(app)
  .post('/api/some-endpoint')
  .send({ key: 'value' })
  .expect(201); // Asserts the status code is 201

Common Assertions

After you make a request, you’ll often want to inspect the response and validate certain conditions using Jest’s expect function.

Some examples:

expect(response.status).toBe(201); // Check response status
expect(response.body).toHaveProperty('id'); // Response has an ID
expect(response.body.name).toBe('Alice'); // Check value

You can also check the internal state of your application, like an in-memory array or mock database:

const item = dataStore.find(entry => entry.id === response.body.id);
expect(item).toBeDefined();
expect(item.name).toBe('Alice');

Now that you have the basics, you will start writing your first integration test with Jest and Supertest.

  it('should create a new user successfully', async () => {
    const newUser = { name: 'John Doe', email: '[email protected]' };

    const response = await request(server)
      .post('/users')
      .send(newUser)
      .expect(201);

it('should create a new user successfully', async () => {

const newUser = { name: 'John Doe', email: '[email protected]' };

const response = await request(server)
  .post('/users')
  .send(newUser)
  .expect(201);

    expect(response.body).toHaveProperty('id');
    expect(response.body.name).toBe(newUser.name);
    expect(response.body.email).toBe(newUser.email);

expect(response.body).toHaveProperty('id');
expect(response.body.name).toBe(newUser.name);
expect(response.body.email).toBe(newUser.email);

const storedUser = users.find(u => u.id === response.body.id);
expect(storedUser).toBeDefined();
expect(storedUser.name).toBe(newUser.name);

Testing Retrieval of All Users

After learning how to test user creation via POST /users, you're now going to verify that users can be retrieved through the GET /users endpoint.

In integration testing, this means making a simulated request to your server and checking that it returns the correct list of users, just like a real client would.

Making GET Requests in Tests

To test GET /users, you’ll again use Supertest, which allows you to simulate HTTP requests in your test suite. Here's how a basic GET request looks in a test:

const response = await request(server).get('/users').expect(200);

This line tells Supertest to:

• Make a GET request to /users.
• Expect an HTTP 200 OK status.
• Capture the response into a response variable for assertions.

Asserting the Response

Once you have the response, you'll typically want to:

1. Check that the data is an array.
2. Check how many users were returned.
3. Optionally, check that individual objects match expected values.

expect(response.body).toBeInstanceOf(Array);
expect(response.body.length).toBe(2);
expect(response.body[0].name).toBe('Alice');

These assertions confirm:

• The response is an array
• It has two elements
• The first user is named "Alice"

Preparing the Test Environment

Before testing the GET request, just like in the previous step, you’ll want to manually populate the in-memory users array with fake data. This mimics having users already created in your application:

users.push(
  { id: 1, name: 'Alice', email: '[email protected]' },
  { id: 2, name: 'Bob', email: '[email protected]' }
);

This is important because you’re not hitting a real database, your test needs to control the state of the app directly.

  it('should fetch all users', async () => {
    users.push(
      { id: 1, name: 'Alice', email: '[email protected]' },
      { id: 2, name: 'Bob', email: '[email protected]' }
    );

    const response = await request(server).get('/users').expect(200);

  });

it('should fetch all users', async () => {

  users.push(
    { id: 1, name: 'Alice', email: '[email protected]' },
    { id: 2, name: 'Bob', email: '[email protected]' }
  );

 const response = await request(server).get('/users').expect(200);

In this step, you'll test an endpoint that not only serves local application data, but also integrates information from an external service. This is a classic use case for integration testing: verifying how your application behaves when internal logic and external dependencies are combined.

Why This Matters

Unlike unit tests that isolate functionality, integration tests validate the collaboration between components. In this case, your Express server fetches posts from in-memory data and enriches them with details from an external API. You want to ensure this integration behaves correctly without depending on the actual external service during testing.

About the External API

Your application integrates with JSONPlaceholder, a free fake online REST API that’s often used for prototyping and testing. Specifically, the endpoint /todos/1 returns a single "to-do" item:

{
  "userId": 1,
  "id": 1,
  "title": "delectus aut autem",
  "completed": false
}

In your Express app, the /posts-with-external-data endpoint combines this to-do item with local post data and appends a new property, externalInfo, to each post like this:

{
  "id": 1,
  "title": "My First Post",
  "content": "Hello World",
  "authorId": 1,
  "externalInfo": "External task: \"delectus aut autem\""
}

Since relying on a real network request during testing would introduce flakiness (e.g., failing if offline or if the service changes), you’ll mock this API call using the nock library.

External Integration Test Breakdown

Here’s a step-by-step look at how such a test is structured:

1. In-memory Setup: Push a user and a post into the in-memory arrays (users, posts), associating the post with the user by ID.

2. Mocking External Call: Use nock to intercept the call to https://jsonplaceholder.typicode.com/todos/1 and return a predefined JSON response. Here's how you can achieve this using nock:

nock('https://jsonplaceholder.typicode.com')
      .get('/todos/1')
      .reply(200, { id: 1, title: 'delectus aut autem', completed: false });

To decouple yourselves from the actual jsonplaceholder API, nock will fake the GET request to the API and will return the response and status code specified in the reply() function.

3. Calling the Endpoint: Use supertest to make a GET request to /posts-with-external-data.

4. Assertions:

   • Confirm that the response is an array.
   • Confirm it has one post.
   • Check that the post title matches the in-memory post.
   • Verify that the mocked external info is correctly appended to the post.

This is how a complete integration test should look like for an use case where an API combines data supplied by the user with external data.

it('should fetch posts and combine them with mocked external data', async () => {
    // Setup in-memory data
    users.push({ id: 1, name: 'Jane Doe', email: '[email protected]' });
    posts.push({ id: 1, title: 'My First Post', content: 'Hello World', authorId: 1 });

    nock('https://jsonplaceholder.typicode.com')
      .get('/todos/1')
      .reply(200, { id: 1, title: 'delectus aut autem', completed: false });

    const response = await request(server)
      .get('/posts-with-external-data')
      .expect(200);

    expect(response.body).toBeInstanceOf(Array);
    expect(response.body.length).toBe(1);
    expect(response.body[0].title).toBe('My First Post');
    expect(response.body[0].externalInfo).toBe('External task: "delectus aut autem"');
  });

In real-world applications, your backend services often depend on third-party APIs. These external APIs might sometimes fail due to downtime, network issues, or rate limiting. When that happens, your server should handle the error gracefully and return a meaningful response to the client. In this step, you'll learn how to simulate such a failure and verify your application's behavior using integration tests.

Introducing nock for Mocking External API Failure

In the previous step, you used nock to simulate a successful response from an external service (jsonplaceholder.typicode.com). In this step, you’ll simulate a failure instead.

Here’s how you can mock an external API failure:

nock('https://jsonplaceholder.typicode.com')
  .get('/todos/1')
  .reply(500, { message: 'External Service Down' });

This tells nock to intercept any HTP GETrequest to /todos/1 on that domain and return a 500 status code instead, along with a failure message.

Writing the Test

You want to test that your backend responds appropriately (e.g., with a 500 status and a relevant error message) when the external service fails. Here's how you do it step-by-step:

1. Mock the external failure with nock.

2. Make a request to your local API endpoint (/posts-with-external-data) using supertest.

3. Assert that your server responds with HTTP 500 and the expected error message in the response body.

You can use: expect(response.body.message).toBe('Error fetching combined data') to confirm that the error handling logic in your backend executed as intended.

it('should handle errors when the external API call fails', async () => {
    nock('https://jsonplaceholder.typicode.com')
      .get('/todos/1')
      .reply(500, { message: 'External Service Down' });

    const response = await request(server)
      .get('/posts-with-external-data')
      .expect(500);

    expect(response.body.message).toBe('Error fetching combined data');
  });

nock('https://jsonplaceholder.typicode.com')
  .get('/todos/1')
  .reply(500, { message: 'External Service Down' });

const response = await request(server)
  .get('/posts-with-external-data')
  .expect(500);

expect(response.body.message).toBe('Error fetching combined data');

In this step, you’ll learn how to write an integration test that ensures your application correctly handles unknown routes by returning a 404 Not Found response.

This type of test is important because users (and clients) may attempt to access endpoints that do not exist. Your server should respond with a meaningful error message rather than crashing or returning a generic 500 error.

By default, Express.js will not respond with anything if a route is not defined, unless you explicitly handle it. Most applications add a "catch-all" middleware at the end of the route declarations to handle unmatched paths.

Your server, however, is actually handling non-existent routes as follows:

app.use((req, res) => {
  res.status(404).json({ message: 'Not Found' });
});

You want to test that when someone tries to access a non-existent route, the server returns a 404 status and includes the expected message in the response body.

How to Write This Test

To build this test, you’ll use the same tools as before:

• Jest for structuring the test and making assertions

• Supertest for making requests to the server inside the test

Here's how to approach it:

• Use describe() to group the test under a meaningful label, like "Error Handling".

• Use it() to define what the test should do (e.g., "should return 404 for a non-existent route").

• Make a GET request using Supertest to an undefined route such as /non-existent-path.

• Expect the server to respond with HTTP status code 404.

• Verify that the response body contains a specific error message, and in this case, "Not Found").

Here’s a working example of the test:

describe('Error Handling', () => {
  it('should return 404 for a non-existent route', async () => {
    const response = await request(server).get('/non-existent-path').expect(404);
    expect(response.body.message).toBe('Not Found');
  });
});

Here is a breakdown:

• describe('Error Handling', () => { ... }): Creates a test suite for error handling behavior

• it('should return 404 for a non-existent route', async () => { ... }): Defines what this test is verifying

• await request(server).get('/non-existent-path').expect(404): Sends a request to an undefined route and checks that the server responds with a 404 status

• expect(response.body.message).toBe('Not Found'): Asserts that the response contains the correct error message, ensuring the error handling logic is functioning

Congratulations on completing the Guided: Integration Testing with JavaScript lab!

Throughout this hands-on lab, you’ve built a deeper understanding of how integration testing helps ensure that different parts of your application work together correctly. Here's what you've accomplished:

• Learned how to write integration tests using Jest and Supertest

• Created tests to verify core API endpoints like creating and fetching users

• Practiced mocking external services with nock to simulate API dependencies

• Handled edge cases such as failing external calls and invalid routes, ensuring robust error handling in your application

Why Integration Testing is Important

Integration testing sits between unit and end-to-end testing. It checks how multiple parts of your system interact, such as your route handlers, business logic, and data layers, without spinning up a full browser or relying on complex environments. This level of testing is fast, reliable, and crucial for spotting issues early in development.

What’s Next?

You can build on this foundation by:

• Create PUT and DELETE endpoints and add tests for them.

• Exploring tools like MSW (Mock Service Worker) for frontend API mocking.

• Integrating coverage tools to measure test effectiveness.

• Combining unit, integration, and end-to-end tests into a complete test suite.

You've taken a major step toward writing reliable, maintainable JavaScript applications. Keep practicing and expanding your test coverage!