DEV Community: Artem Zakharchenko

Mock Service Worker adopts a brand-new request interception algorithm for Node.js.

Artem Zakharchenko — Mon, 21 Feb 2022 11:02:06 +0000

Preface

One of the most prominent features of Mock Service Worker has always been the way it establishes the boundaries between what is mocked and what is not. Conventional API mocking solutions turn any fetch or axios call into a black hole through the substitution of the entire client with a mocked re-implementation. In contrast, MSW brings Service Workers to the table, which allows request clients to execute in their entirety, bringing more confidence to your tests and prototypes. The reason why it increases confidence is simple—your system underneath your test resembles your actual production system. Allow me to elaborate with a quick example.

Imagine you are writing an abstract test for a bank branch—one with a physical location where people come to open accounts, withdraw funds, and deposit their earnings and investments. Let's say you want to test that your bank can handle deposits. You model a situation where a customer walks in, goes to the cash stand, and hands their money to the teller. The teller then puts the deposit into the bank system, which updates the customer's account balance.

Since this is a test of an interaction, spending actual money to put into accounts isn't the best idea (what an expensive test that would be! 😉). Instead, you decide to mock certain parts of your bank during the test, so they don't actually happen.. You do remember, however, that the point of any test is still to test a system or its part, so you ought to introduce mocking carefully, understanding which parts of the "customer → bank" interactions can be replaced without sacrificing the actual functionality you wish to test—that your bank can handle deposits.

Ideally, it's only that last "cashier → bank system" procedure you should mock. The cashier would receive fake money (mocked), and interact with the bank systems that are already pre-configured (mocked) to respond with a "Okay, we've got the funds!" state. Walking into the bank, finding the cash stand, and speaking to a cashier are all crucial aspects for our customer which should remain authentic and real.

At this point, it should be clear I'm hinting at the HTTP communication with this story, where the customer is a request, and the bank is your request client that processes it. The final part—the "cashier → bank system"—is where you should employ API mocking.. So let's see what happens when you bring a common API mocking library to do the job.

Due to the implementation details of such libraries, what happens is that you end up with your entire bank being replaced. Yes, not just the cashier or a cash stand, the entire bank. Because a conventional interception of request can be roughly represented as follows:

// node_modules/api-mocking-library/index.js
const mockRequestClient = {}

global.requestClient = mockRequestClient

For many tools, the lowest level of operation becomes the request client. In other words, they replace window.fetch, axios, react-query and other clients during your tests, so your code no longer executes them. Basically, your customer no longer walks into your actual bank. Instead, they walk into a fake building, constructed to look and resemble the bank. Since the scope of the mock has grown from a single interaction to the entire building, the surface area where potential issues can happen increases drastically.

This is precisely where Mock Service Worker introduces interception of requests via the Service Worker API. This allows you to keep the bank, the cash stand, and the cashier as real as they are in production. Oh, but there's more! Even the "cashier → bank system" communication becomes real because the worker would intercept the deposit request after it's left the bank. This keeps the mocked surface to a ridiculous minimum.

This has been our algorithm to intercept requests that occur in a browser for years now. Unfortunately, this hasn't been the case for Node.js.

Request interception in Node.js

Node.js is an entirely different environment and, as one would expect, it has its own rules and limitations. It's like an alternative universe where you can still have your bank, but all its doors are now made of blue wood, and all the communication is conducted via woolen envelopes... that's just how banks work in this world.

There's simply no intermediate network layer like Service Workers in Node.js. Once requests happen, they happen, and nothing can intercept them past that point. This design choice is why request clients become the lowest point of interception available in a Node.js environment.

Due to this limitation, request interception in Node.js is implemented by stubbing request modules:

// node_modules/api-mocking-library/index.js
const https = require('https')

// My custom function replaces the "bank"
// (the "https" module) and becomes responsible
// for handling any issued requests.
https = function (...args) {
  // ...
}

Modules in Node.js share the same scope, so modifying a standard API like https in one module will affect its references in all other modules.

Module stubbing is a reasonable strategy within the circumstances, and that is also how MSW intercepts requests in Node.js.

Or rather, how it used to, until we tried something... unusual.

Brand-new interception algorithm

Starting from the latest version of Mock Service Worker (0.38.0), the library will employ a request interception algorithm that has been rewritten from the ground-up. There's no more module stubbing, no more replacing the entire bank. Instead, we are introducing a way to extend the request modules, allowing them to execute in their entirety and intercept the outgoing requests at the last possible moment (wait, we've heard this somewhere, haven't we?).

We achieve this through module extension.

Technically, both http and https modules are just wrappers around the ClientRequest class. That is actually the request that is being constructed and sent to a server. That is also a lower surface where we could move our logic in order to be even closer to the constructed requests.

Still, we do not wish to tread same water by hijacking the ClientRequest class and forcing it to do our bidding:

// Both "http" and "https" use the same "http.ClientRequest"
// configured accordingly for HTTP and HTTPS
// connections.
const { ClientRequest } = require('http')

// That is NOT what we want!
ClientRequest = class MyClientRequest {
  end(data) {
    // Now, suddenly, resolve with a mocked response!
  }
}

Unfortunately, this is no different than stubbing http/https modules directly.

What we've decided to do is to extend the ClientRequest class, effectively creating a child class that is much like its parent, albeit with a few deviations.

class NodeClientRequest extends ClientRequest {
  end(data) {
    // Respond with a mocked response.
  }
}

This may look similar at first, but, there is a fundamental difference between the choice of replacing or extending the ClientRequest class.

When you replace that class, you're removing it from existence, swapping it with a seemingly compatible class that you've written by yourself. This means you (the API mocking library in this context) become responsible for respecting and handling all the internals of that class. And those are many: establishing the socket connection, writing request/response body, handling headers, etc.

In our previous implementation, that's exactly what we were doing, handling all those moving parts by ourselves.

But what happens when you extend the class is an entirely different story.

Class extension preserves the behavior of the parent class, producing a child class that augments it. So, while we were previously forced to re-implement the response handling logic just to be able to intercept an original response, we can now hook into the ClientRequest.prototype.end method and simply use super() whenever we need to bypass a request.

class NodeRequestClient extends ClientRequest {
  end(data) {
    if (mockedResponse) {
      this.respondWith(mockedResponse)
      return
    }

    // Calling "super.end()" will perform the intercepted request
    // in the identical way it's perform without mocks.
    return super.end(data)
  }
}

The ability to execute the parent class' logic through super() is what allows us to keep the default behavior of request modules intact. We just call out to it whenever it's needed!

It's been a rather challenging implementation, as allowing ClientRequest to execute normally imposes a certain behavior difference when constructing requests.

Let's look at one of these challenges that we've faced during this rewrite.

Handling refused connections

Extending the ClientRequest class means that all requests begin to establish actual HTTP connection. This quickly becomes problematic. When you're prototyping against a non-existing endpoint in Node.js, such connections would be refused! In addition, when you're testing the code that hits actual production servers, connecting to those is not what you want your tests to do.

Presently, we've landed on the decision to always establish the connection, no matter if the request is supposed to be mocked or not.

While this sounds unconventional, the cost of establishing an actual socket connection is rather small. Note that we are still preventing any data from being sent or received through that connection. You can think of it as a HEAD request to your endpoint.

What about the scenarios when the connection fails? What about requesting non-existing endpoints?

It comes down to proper error handling in ClientRequest.

The connection itself happens right away, while first constructing the request instance. At that time, it's impossible for the library to know if there's a request handler created to intercept this particular request. However, it's not too early to handle connection errors.

So what ends up happening is:

Request instance attempts to connect to the server;
This connection is either established (the server exists) or refused (the server does not exist or couldn't otherwise establish the connection). In either case, no data is being transferred yet.
If the connection is refused, MSW catches the respective error and silences it until it knows there are no matching request handlers. Once this is known, the library replays the errors, propagating it to the process.
If the connection is established, MSW prevents any data from being written or received until it's certain there are no matching request handlers.

We are convinced that keeping the connection logic is crucial to maintain the integrity of the ClientRequest instances. This does not mean that you must request actual endpoints from now on, or even that you must be connected to the internet while testing. It only means that request instances execute more of its internal logic, including the logic that's responsible for establishing the connection.

What should I expect as MSW user?

Expect to update msw in your projects!

npm install msw@latest --save-dev
# or
yarn add msw@latest --save-dev

The new algorithm is an internal change, so there are no breaking changes to the public API or behaviors of MSW in Node.js.

That being said, this is quite a shift from our previous implementation, so we expect issues to be reported occasionally. We highly encourage you to do so whenever you encounter an unexpected behavior or a regression in your Node.js tests! Submit an issue here.

Our motivation behind this change is to reduce the mocked surface in Node.js, bringing you a similar level of confidence that you get when using MSW in a browser.

Afterword

I hope you're as excited about these changes as I am! There's a long road for us ahead, but it's a road we wish to spend on making your developer experience not just better, but unmatched. We've got a history of using unconventional approaches to API mocking in the browser, and we're thrilled to expand our vision to Node.js.

Follow MSW on Twitter to stay updated on the awesome features we're working on!

Make sure to check out the @mswjs/interceptors—the low-level interception library that powers Node.js support in MSW:

mswjs / interceptors

Low-level network interception library.

`@mswjs/interceptors`

Low-level network interception library.

This library supports intercepting the following protocols:

HTTP (via the http module, XMLHttpRequest, or globalThis.fetch);
WebSocket (the WebSocket class in Undici and in the browser).

Motivation

While there are a lot of network mocking libraries, they tend to use request interception as an implementation detail, giving you a high-level API that includes request matching, timeouts, recording, and so forth.

This library is a barebones implementation that provides as little abstraction as possible to execute arbitrary logic upon any request. It's primarily designed as an underlying component for high-level API mocking solutions such as Mock Service Worker.

How is this library different?

A traditional API mocking implementation in Node.js looks roughly like this:

import http from 'node:http'
// Store the original request function.
const originalHttpRequest = http.request

// Override the request function entirely.
http.request = function (...args

…

View on GitHub

Thank you!

One Thing That May Ruin The New God of War Game

Artem Zakharchenko — Sat, 11 Sep 2021 23:05:45 +0000

With the PlayStation Showcase 2021 behind our backs, I, just as many others, was excited to finally get the first look at the new God of War titled "Ragnarök". At the next day after watching the showcase a strange feeling settled in my heart. A feeling that the new beloved title may be disastrous.

To understand my worries, first you need to understand my biggest critique of the previous God of War game, which was widely praised and well-perceived by both critics and gamers. Looking back at it, I couldn't help but notice how a single element of the game introduces so many flaws into otherwise great action experience. That element is RPG.

Adopting parts of RPG mechanics has become widely popular in action titles in the recent years. From dressing up your assassins in the Victorian era to deciding which perk Geralt of Rivia should level up before going on his next hunt—elements of RPG gameplay has soaked into other genres in many shapes and forms. Needless to say, sometimes this conjunction is far from perfect. In some cases, it straight ruins the game, being a burden rather than an engaging and captivating elements of the gameplay.

The latest God of War game featured prominent RPG elements like character armor and weapons, and also the skill tree.

A skill tree in the God of War (Source).

I am convinced that these elements ruin the game and, moreover, don't belong in action titles in the first place. A strong statement, I know, but let's dig a little bit deeper to see what exactly these RPG elements mean for the game.

RPG in action games

RPG is an incredibly popular genre with dozens of renowned titles, gigantic fanbase and stylistic variability. Perhaps the biggest thing that makes this genre stand out is subtly placed right in its name—R (role). The ability to role-play, meaning playing your character in a role you see fit, brings an incredible sense of wonder and personalization.

The thing that makes action games unique is in the genre name as well. It's action. Intricate, thrilling fighting scenes, blood-chilling dialogues and character interactions, and just a bit of sprinkle of epic on top. Action games are known to be huge, vibrant, and flamboyant. Such degree of excitement is usually achieved by pre-defined, mostly linear storytelling, masterfully written and orchestrated like in a big blockbuster movie. While this allows game designers to balance between the unstoppable epic and the intermissions of peace, it takes away any room for variability, any room for role. Try to remember an action game where your decisions influenced something, or a game where you even had to make any decisions. Most of the times playing such games would feel like watching an interactive movie (and it's great) rather than crafting a unique novel-like story using your character as an ink pen.

Needless to say that RPG games have dominated the online world with thousands of MMORPG titles. They did and continue doing so due to the addictive gameplay and nearly infinite character progression in a definitely infinite (and often absent) story. No wonder that the action genre tends to borrow such addictive gameplay elements to create a sense of character progression in otherwise progression-less genre.

I think the main reason to add RPG elements into an action game is to compensate for a short and uninteresting gameplay loop. What can be better than taking a bunch of weapons, armor, perks, all color-graded into perfection, so that the player spends a few more hours in a game that already offered everything it could in the first hour of playing?

More often than not, RPG elements in action games simply fail and feel out of place, dragging the gameplay away rather than complimenting it. I think that happens because those RPG elements are designed to come hand-in-hand with role playing, which is absent in action games. Moreover, such incompatibility often births a ludonarrative dissonance, ruining the immersion that any game strives to create.

Let me give you an example. Imagine that during one of your world-wondering sessions, your abstract Geralt had stumbled upon an ancient chest. You opened it and found an incredible set of armor, perhaps the best in the game. You feel joy as the next shiny thing lands in your character's inventory. Time passes and you, eventually, reach the next "story" moment—a cutscene. You stare at the polygons on your monitor as they, suddenly, grab your Geralt and throw it against the wall, rendering him half-dead. Wait, what? you exclaim. Not a single living soul in the game could've beaten you while you wear that armor set. But the cutscene does beat you. Because the cutscene is destined to happen. You accept this as a game detail and head on to find yet another chest with jaw-dropping items that change your gameplay upside-down but have zero effect on the story you're trying to play.

Now, let's talk about God of War (finally).

Role in God of War

When you purchase God of War you're likely expecting to play as a god-crashing brute named Kratos. Although the latest title has opened him up from a rather unconventional (yet great) sensitive side, you'd still be right to expect an occasional ass whipping here and there, using the might of the God of War. In other words, you expect a certain gameplay based on the game setting and characters. I don't think anybody has tried playing a stealthy Kratos. Partially, because it's against the already written character. Mainly, because the game won't allow you to. Don't be deceived, there is no role in God of War, as you've taken the role of Kratos from the moment you downloaded the game.

As I've said before, taking on a pre-defined role is an inevitable pre-requisite of a good action adventure game. As I've also stated before, adding RPG elements to a role-less game is a terrible, pointless idea, which is likely there to mask the lack of gameplay than anything else. That's exactly what happens with God of War.

Source: Vortex

I challenge you: take a clip of Kratos fighting enemies at the beginning of the game and put it side-by-side with him fighting enemies at the end of the game. You'll be amazed how both fights are, well, identical. The enemy colors and skins may change, but there are still about 3 enemy types in the game. Kratos' may shove off with a few new moves but they hardly have any significant impact on the battle, adding mainly in choreography and style than making an actual gameplay difference. Turns out all those chests and items were there only to fake you feeling engaged, when in actuality Kratos was moving from point A to point B as the story foretells, regardless of your actions. RPG elements were now complimenting the game, they were saving you from feeling bored.

The strong side

For a moment, let's imagine God of War without chests, weapons, armors, skills. We will still be left with a bunch of gaming aspects:

Combat;
World exploration;
Story.

I think most of the praise that God of War received was related to its story and, specifically, to how it was told.

Source: DigitalSpy

The plot itself is a classic travelogue with close to no things to surprise you. The main strength of the story, and also the main thing that the developer team did incredibly well, was the character development during that story.

Once the item grind is gone, the combat and exploration have almost nothing else to offer. Enemy types are extremely scarce, while the world is, although vast, feels and de-facto is a classic action game world. These two aspects of the game are weak and no amount of armor or skills can make them better. That'd only mask the problem, not solve it.

How to solve it

The biggest mistake I think the developer did was betting too much on the RPG elements in the game. I understand they were supposed to engage the players and gift them the sense of progression, but they do the opposite, dissolving the gameplay with the needless search for gear (that Kratos has no use for story-wise), living in the limbo of the same chest opening animation.

Instead, they should've focused on what makes an action game stunning: progression through story, not gameplay. Instead of giving me a new armor in a box, let Kratos tear that armor off an important boss, and do so by his intentions, not mine (player's). Instead of letting me press a mindless "+" next to a skill, let an encounter with an NPC teach Kratos that skill, making me feel like a journey that the protagonist undertook to learn it as opposed to a new way to swing an axe magically appearing in the hero's memory.

And I believe the team understands that. The appearance of his twin blades in the second part of the game was phenomenal. Yes, they did extend your combat capabilities, but I'm referring to how their reveal was handled. Kratos retrieved them from his hideout because it was a logical move in the circumstances that the story dictated. Pre-defined story, pre-defined Kratos, pre-defined blades. And it still worked wonderfully because action elements will always work in action games.

Source: ScreenRant

I hope that the next God of War advances the combat and the world, leaving the RPG elements aside, if not abandoning them altogether. I don't need to feel variability from gear in a game where I don't expect variability. I honestly hope that they spend the budget they could allocate on improving weapons and skills on extending the world, crafting more cinematic moments, and, for God's sake, finally adding some nordic Gods to interact with.

Spawn an HTTP server from your Mock Service Worker request handlers.

Artem Zakharchenko — Fri, 23 Jul 2021 15:50:15 +0000

When Mock Service Worker was released, it had a clear mission to enable API mocking without the need to spawn and maintain an actual HTTP server. This purposeful restriction, among a few other core principles, has led to thousands of developers writing declarative, agnostic, and reusable mocks every day, prototyping amazing applications and delivering stunning products with confidence.

While our "you don't need a mocking server" principle still stands strong today, we listen closely and analyze all the great feedback that our users share with us in order to improve the project and increase the amount of use cases it could cover.

Today, I'm excited to tell you about a project that David Idol and I have collaborated on with a goal to bring Mock Service Worker to more challenging usage contexts. We named it "http-middleware".

mswjs / http-middleware

Spawn an HTTP server from your request handlers or apply them to an existing server using a middleware.

The Concept

The premise of http-middleware is extremely straightforward: reuse your request handlers to create an actual HTTP server.

This project is designed to cover more complex use cases when the standard Mock Service Worker approach isn't sufficient. Such use cases include:

Adding the ability to curl your mock definitions, for example, for local debugging;
Integrating API mocking in complex application architecture (i.e. with dockerized apps).
Prototyping Node.js server development.

Note that this project is not a go-to solution for API mocking, and you should always favor Mock Service Worker instead. It's created to handle complex use cases and you'd know when you need it. As a rule of thumb: when in doubt, prefer MSW.

Learn more about how to get started with MSW.

The Usage

The "http-middleware" project is so concise that I've decided to write a brief usage tutorial right here, right now. Let's get a server running in 2 minutes with your request handlers being the source of truth.

First, create a project if you don't have one already:

$ npm init -y

Then, install the necessary dependencies:

$ npm install express msw @mswjs/http-middleware --save-dev

To keep things simple, let's have a single server.js file where we will declare our server:

$ touch server.js

Finally, use the createServer function to spawn an Express server. Provide it with the request handlers you want to be responsible for producing responses:

// server.js
const { rest } = require('msw')
const { createServer } = require('@mswjs/http-middleware')

const httpServer = createServer(
  rest.get('/', (req, res, ctx) => {
    return res(ctx.text('Hello world'))
  })
)

httpServer.listen(9090)

Learn more about writing request handlers with Mock Service Worker. You can reuse the same handlers you write in tests, local development, and debugging.

Now run your server:

$ node server.js

Try making a GET http://localhost:9090 request. You'll see that the response was resolved based on the request handler you've specified:

200 OK
Content-Type: text/plain;

"Hello world"

Done 🎉

Adding to an existing server

Alternatively, you can apply request handlers via a middleware, which is handy in case you already have a server:

// existing-server.js
import { rest } from 'msw'
import { createMiddleware } from '@mswjs/http-middleware'
import { app } from './app'

app.use(
  createMiddleware(
    rest.get('/', (req, res, ctx) => {
      return res(ctx.text('Hello world'))
    })
  )
)

The Cherry on Top

With request handlers acting as the source of truth, you get the same benefits as when using MSW: shared API mocking logic across different environments and purposes.

I can't stress enough how important it is to have a clean, deterministic testing setup. There is absolutely no reason to install 3 different libraries for API mocking just because you want to mock the same API in an integration test, and then in an end-to-end test, and then to debug an irksome data-driven bug.

Mock Service Worker allows you to write your API mocks once and reuse them anywhere later: when working on the app, when testing it in Node.js, when running automated tests in Cypress, when debugging. All that using the same familiar consistent syntax. Don't miss out.

mswjs / msw

Industry standard API mocking for JavaScript.

Embrace the ecosystem

By leveraging libraries like @mswjs/data, you can have data-driven type-safe API mocking reused across the entire stack. Develop and iterate on your next product with the speed of light by the flexibility Mock Service Worker and its ecosystem gives you.

Afterword

We're excited to see what impact this small package will have in your development workflow! Make sure to follow Mock Service Worker on Twitter to get the latest news and be notified about many upcoming features.

We also highly encourage you to contribute to the http-middleware package with your ideas and feedback on GitHub:

mswjs / http-middleware

Spawn an HTTP server from your request handlers or apply them to an existing server using a middleware.

Stay awesome ❤️

Announcing "@mswjs/data"—data modeling library for testing JavaScript applications

Artem Zakharchenko — Mon, 12 Apr 2021 15:59:45 +0000

Introduction

It's been more than a year since Mock Service Worker (MSW) began to appear in people's package.json, improving the way you write tests, iterate on features, and debug API-related issues. We are incredibly thankful for everybody who supported us and gave the library a chance in their projects. That allowed us to gather a ton of feedback based on the usage scenarios you face every day. It is with that feedback that we can move the project forward to ease your testing and development workflow even more. And it is with that feedback that we are able to make this announcement.

MSW was deliberately designed with only the essentials of API mocking in mind: interception of requests and response mocking. A huge focus was made on leveraging Service Worker API to enable a one-of-a-kind experience and support the same request handlers across different environments. While some alternative libraries come with built-in assertions or data-modeling options, our team has chosen a horizontal way to scale the project: distribute complimentary, on-demand libraries instead of stuffing dozens of functions and methods into a single package.

Some of the most popular questions developers have when starting with MSW are related to data. You immediately notice how the library is agnostic to how you create and update data in your handlers. You may use a plain array or Map to manage resources. Perhaps, you may even design a custom database abstraction that manages those resources in a more standardized way.

No matter what data-related setup you end up with, it's there to answer the following questions:

How to describe data resources?
How to implement CRUD operations on data?
How to persist the changes made to the data?

Today we are proud to announce the Data library—a standalone package to model and query data in your tests and beyond. Although the project is at the early stage of development and doesn't solve every problem right away, letting you try it out and gather your feedback is crucial for us to refine and shape the future experience.

mswjs / data

Data modeling and relation library for testing JavaScript applications.

Without further a due, let's talk about what's to become the recommended way to work with data in Mock Service Worker.

Data modeling

First, let's get acquainted with the two main terms that the Data library operates with:

Model—description of the data. Think of it as a blueprint that describes what properties the data has.
Entity—an instance of a particular model. This is the exact data that implements its model description.

When working with Data, you define models and relationships between them, which, effectively, result in a virtual database being created.

Install the package into your project:

npm install @mswjs/data

Now, let's create a new "user" model:

import { factory, primaryKey } from '@mswjs/data'

const db = factory({
  user: {
    id: primaryKey(Math.random),
    firstName: () => 'John',
    age: () => 18,
  },
})

Models are defined by calling the factory function and providing it with the object where keys represent model names, and values stand for model definitions. Each property in the model definition has an initializer—a function that seeds a value and infers its type.

Notice how the id property equals primaryKey. Each model must have a primary key, which acts as a unique ID in a conventional database table. Data exposes the primaryKey function that you should use to mark a certain property as the model's primary key.

In the example above, we're using plain functions that return static data. This means that each time a user is created, it will have firstName: "John" and age: 18. While this is a good foundation to build upon, the static nature of values may limit your data scenarios. Consider using tools like Faker to define models with randomly generated realistic data.

import { factory, primaryKey } from '@mswjs/data'
import { name, random } from 'faker'

const db = factory({
  // Create a user model with a random UUID and first name.
  user: {
    id: primaryKey(random.uuid),
    firstName: name.findName,
    age: random.number,
  },
})

You can define multiple models and relationships between them within the same factory:

import { factory, primaryKey, oneOf } from '@mswjs/data'
import { random } from 'faker'

const db = factory({
  book: {
    isbn: primaryKey(random.uuid),
    // "book.publisher" is a relational property
    // that references an entity of the "publisher" model.
    publisher: oneOf('publisher')
  },
  publisher: {
    id: primaryKey(random.uuid),
    name: random.words,
  }
})

Learn more about defining model relationships.

Seeding

Once the models are defined, create an entity of a particular model by calling the .create() method on it:

db.user.create()

Creating an entity without any arguments will fill its properties using the value initializers you've specified in the model definition.

The .create() method accepts an optional argument that stands for the initial values of the entity. For example, if we wish to create a user with a fixed "firstName" value, we can provide that value in the initial values object:

db.user.create({
  // Uses an exact value for the "firstName" property,
  // while seeding the "id" based on its getter.
  firstName: 'John',
})

Querying client

Apart from the data modeling functionality, this library provides a querying client that allows you to find, modify, and delete entities on runtime. The querying client brings Data to life, as it enables dynamic scenarios against the generated data.

Each model supports the following querying methods:

.findFirst(), finds the first entity that matches a query.
.findMany(), finds multiple entities that match a query.
.count(), returns the number of entities for a model.
.update(), updates an entity that matches a query.
.updateMany(), updates multiple entities that match a query.
.delete(), deletes an entity that matches a query.
.deleteMany(), deletes multiple entities that match a query.

The most basic example of querying is finding an entity by its primary key. In our case, we can find a user by its "id" like this:

// Find a user with the given "id" (primary key).
const user = db.user.findFirst({
  where: {
    id: {
      equals: 'abc-123',
    },
  },
})

Let's focus on where part of the query above. When querying entities, where is a predicate object that describes the criteria against an entity. The structure of that predicate is the following:

{
  where: {
    [property]: {
      [operator]: expectedValue
    }
  }
}

[property], a known property of the model. In the case of our "user" model, this can be "id" or "firstName".
[operator], an operator function name that compares the actual and expected values of the referenced property.

Operators depend on the value type that's being queried. When querying a string (like we do with where.id, where "id" is of the String type), operators like equals, notEquals, contains, in, and others are available. When querying a number, you have access to the gt, lte, between, etc. operators instead.

Querying methods are strongly typed, validating the known model properties and value-based operators on build time. Experiment with your models to learn about all the different options at your disposal!

In a similar fashion, we can query multiple entities. Here's how we can get all the users that satisfy a certain age criteria:

// Returns all users whose "user.age"
// is greater or equal 18.
const users = db.user.findMany({
  where: {
    age: {
      gte: 18,
    },
  },
})

Data supports cursor and offset pagination to work with large data sets.

There is much more functionality that Data provides, so don't hesitate to explore the library API. Refer to the documentation for API definition and usage examples.

Integration with Mock Service Worker

Here's a gigantic cherry on top: you can turn any data model into request handlers (both REST and GraphQL) to encapsulate its operations, like creation and querying, under the respective API routes.

Generating REST API

Using our db and its "user" model, we can turn it into a REST API "server" in a single command:

// src/mocks/browser.js
import { setupWorker } from 'msw'
// Import the "db" object.
import { db } from './db'

const worker = setupWorker(
  // Generate REST API request handlers
  // based on the "user" model.
  ...db.user.toHandlers('rest')
)

worker.start()

Looks unfamiliar? Learn how to get started with Mock Service Worker.

Calling .toHandlers() on a model generates CRUD routes for working with that model. In the example above, the following request handlers will be created:

GET /users/, returns all users in the database.
GET /users/:id, returns a user by their primary key (id).
POST /users, creates a new user.
PUT /users/:id, updates an existing user.
DELETE /users/:id, deletes a user by their primary key.

Notice how the model name is pluralized ("user*s*") to reflect the proper semantics when working with the "user" resource.

With the handlers established, you can create and query users in your application as you would do against an actual HTTP server:

// Create a new user in the database.
fetch('/users', {
  method: 'POST',
  // The body is used as the initial entity values.
  body: JSON.stringify({
    id: 'abc-123',
    firstName: 'John',
  }),
})

// Then, query the created user.
fetch('/users/abc-123')

Explore this interactive sandbox to learn more about generating REST API handlers from your data models:

Generating GraphQL API

A model can also generate GraphQL handlers:

const worker = setupWorker(...db.user.toHandlers('graphql'))

This command generates the following GraphQL schema with its types based on your model:

type Query {
  user(where: UserQuery): User
  users(where: UserQuery, take: Int, skip: Int, cursor: ID): [User!]
}

type Mutation {
  createUser(data: UserInput!): User!
  updateUser(where: UserQueryInput!, data: UserInput!): User!
  updateUsers(where: UserQueryInput!, data: UserInput!): [User!]
  deleteUser(where: UserQueryInput!, data: UserInput!): User
  deleteUsers(where: UserQueryInput!, data: UserInput!): [User!]
}

All the generated GraphQL types and their names are based on your model name and properties.

With your model turned into request handlers, you can query its entities as you would usually do in GraphQL. Here's an example that uses Apollo to get a user entity by ID:

import { useQuery, gql } from '@apollo/client'

const GET_USER = gql`
  query GetUser {
    # Hey, it's the same query as in the ".findMany()" method!
    user(where: { id: { equals: "abc-123" } }) {
      firstName
      age
    }
  }
`

useQuery(GET_USER)

Explore the GraphQL example on Codesandbox:

Call for Contributors!

Data is a new library that has a long way to go and multiple areas to improve. For instance, these are some of the features we'd love to implement:

Client-side persistence;
Server-side rendering support;
.createMany() method to seed multiple entities at once, respecting their relations.

If you would like to learn about data modeling or find this area fascinating, join as a contributor and shape the way developers would model their fixtures.

You can also support the project financially by sponsoring it on Open Collective, allowing the team to work on bug fixes and stunning new features. Your support will not go unnoticed!

Resources & links

mswjs / data

Data modeling and relation library for testing JavaScript applications.

API Mocking Strategies for JavaScript Applications

Artem Zakharchenko — Tue, 16 Mar 2021 09:08:30 +0000

API mocking is easily the most common kind of mocking in JavaScript (apart from the mocking about how there's a new framework every day). No matter what application you're building, it is likely to make some HTTP calls.

So why do you even need mocking? A good question, perhaps you don't. However, if you wish to test the code you write, you'd also have to test the code that does HTTP requests. Making actual requests in your tests is a sure path to flaky and unreliable tests, and here's where API mocking comes in.

The Request's Journey

Before we rush into code, let's stop for a moment and think about what we're trying to achieve here.

Mocking is the action of substituting a piece of software with another, seemingly compatible piece. Since we wish to mock an API call, we will be substituting some piece of the logic responsible for making that call. To better understand which part and why we'll be mocking, we need to visualize a journey of the request first.

Here's a high-level overview of what happens when your application makes a request:

Your application calls a request client to make a request. This can be window.fetch, react-query, or Apollo.
The request client forms a proper request based on your input (resource path, query parameters, headers, body, etc.), and sends it over HTTP to the server.
The server receives a request and returns a response.
Your application receives the response.

It's important to mention that this diagram may differ based on the application architecture you have. However, there always will be these fundamental pieces: a logic that dispatches a request and a server that processes that request.

This overview gives us some visual clues towards what parts conclude a request. We will be mocking one of those parts to achieve our goal. Now to decide which one...

API mocking strategies

I've been honored to speak about various API mocking strategies at this year's TestJS Summit conference. In the video below you can get a grasp over mocking as a technique, its purpose, and the most common (and the most efficient) ways to achieve it.

Let's take a closer look at each strategy in the written form today.

Out of the request's journey components (application, request client, server) we surely don't wish to mock an application. That's the code we're trying to test, and mocking it would be, well, pointless.

This leaves us with the two remaining parts, each representing a mocking strategy:

Mocking the request client.
Mocking the server.

Both these strategies are applicable and widely used. Just as any decision in programming, choosing any of these strategies comes with benefits and drawbacks. Let's focus on those.

Mocking the request client

When you mock the request client, you're making the following change in the request's journey:

By mocking (substituting) the request client, the actual request client is taken out of the equation. A compatible client is placed in its stead, giving us the desired power to mock the responses our application receives.

The most basic example that illustrates this mocking strategy in practice is when you stub the window.fetch function:

window.fetch = (init, input) => {
  // Respond with a mocked response
  // any time our code calls "window.fetch".
  return new Response('hello')
}

Of course, most of the time you would use a third-party library that abstracts this logic for you. Some of the prominent libraries for this strategy are:

MirageJS, through Pretender
nock, through stubbing http/https modules
PollyJS, through various adapters

Benefits

This strategy gives us control over the requests/responses at the earliest stage of their flow. The cost of such control is also minimal, as the mocking logic lives entirely in the client-side code, next to our application.

Drawbacks

If you take a closer look at the diagram altered by this strategy, you'll notice that not only the "Server" part is blackened out, but also the "Request" part. That is because replacing the request client means it never actually makes a request. If a request "leaves" the client, it won't be able to control it anymore.

There's also a behavioral divergence for your application: it does a request in production, but it doesn't in the tests.

Mocking the server

Alternatively, we can replace the "server" part of the request journey to make it look like this:

Since our request client is configured to communicate with a production server, such request destination detour often happens by introducing some sort of conditional URL logic:

const IS_TEST = process.env.NODE_ENV === 'test'

fetch(
  IS_TEST
    // Communicate with a local mock server while testing.
    ? 'http://localhost:3000/api'
    : 'https://api.backend.com'
  )

Some of the most prominent libraries for this mocking strategy are:

Benefits

With the mocking server strategy, we're allowing the request client to fully execute because it's the server part that we're placing. This makes our application behavior under test almost idenctical to the one in production. Almost.

Drawbacks

For this strategy to work, our request client must know when and how to decide which server endpoint to use. Regardless of the technical details of this strategy, it means that the requests are hitting an entirely different server. Introducing any kind of deviation puts the logic you're resting at risk. Consider this:

fetch(
  IS_TEST
    ? 'http://localhost:3000/api'
    : 'hts://apibackendcom' // Ehm, is this okay?
  )

The actual production server URL is corrupted in the example above. Guess what, the tests would still pass while the application would be successfully broken for your users.

There is also a minor operational hassle, as you need to spawn and terminate the local mocking server before/after your test suites. You must ensure the mocking server's operability so that there are no unhandled exceptions that may fail your tests, resulting in false negatives.

Overall, introducing an entire server for the sake of mocking may be considered an overhaul. Even if you're using it for this specific purpose, it's still an actual server you need to write and maintain, increasing the operational cost of this setup.

Using third-party libraries often abstracts the operational aspect of the mocking server, so you're not experiencing it directly. That doesn't mean that it's magically gone.

Which strategy to choose?

The mocking strategy you choose largely depends on the environment where you wish to mock API. Certain environments, such as the browser, allow you to intercept requests on the network level via Service Worker API. That way you compromise on neither request client nor server, allowing all your logic to execute, hit the same production endpoints, and receive the mocked response you're in charge of.

Libraries like Mock Service Worker leverage this unique browser ability gracefully to provision seamless API mocking. Let me know if you would like to learn more about this unusual strategy in the comments below!

There are, however, environments that don't have a designated API to intercept outgoing requests. Running tests in Node.js, for example, would likely require your mocking setup to stub request issuing modules (such as http.request) in order to know what requests are happening, and mock their responses.

Afterword

Regardless of which API mocking strategy you end up choosing, please remember that:

The less test-specific setup you have, the better;
The less your app's behavior changes for the sake of tests, the better;
The closer to the server your request interception is, the better.

I hope you've enjoyed this analysis of different API mocking strategies you may adopt. Make sure to follow me on Twitter to stay in touch with the articles I write. Stay productive!

Type-safe API mocking with Mock Service Worker and TypeScript

Artem Zakharchenko — Sun, 28 Feb 2021 14:10:14 +0000

NOTE: This article is about MSW v1. We released MSW v2, which brings improvements to type-safety along with other features and bug fixes. Please read the Using with TypeScript page for type-safe API mocking on MSW v2. Thank you!

Mock Service Worker is a seamless API mocking library for browser and Node.js. It uses Service Worker API to intercept requests on the network level, meaning no more stubbing of "fetch", "axios", or any other request issuing client. It provides a first-class experience when mocking REST and GraphQL API, and allows you to reuse the same mocks for testing, development, and debugging.

Watch this 4 minutes tutorial on mocking a basic REST API response with Mock Service Worker to get a better understanding of how this library works and feels:

Today we're going to have a practical dive-in into adding TypeScript to your API mocking experience to bring it one step further.

Why annotate mocks?

The mocks you write are a part of your application like any other piece of logic. Having a type validation is one of the cheapest and most efficient ways to ensure your mocks satisfy the data expectations towards them.

REST API

Each REST request handler has the following type signature:

type RestHandler = <RequestBody, ResponseBody, RequestParams>(mask, resolver) => MockedResponse

This allows us to annotate three things in our REST API handlers:

Request body type.
Response body type.
Request parameters.

Let's take a look at the UPDATE /post/:postId request that utilizes all three said generics:

import { rest } from 'msw'

// Describe the shape of the "req.body".
interface UpdatePostRequestBody {
  title: "string"
  viewsCount: string
}

// Describe the shape of the mocked response body.
interface UpdatePostResponseBody {
  updatedAt: Date
}

// Describe the shape of the "req.params".
interface UpdatePostRequestParams {
  postId: string
}

rest.update
  <UpdatePostRequestBody, UpdatePostResponseBody, UpdatePostRequestParams>(
  '/post/:postId',
  (req, res, ctx) => {
    const { postId } = req.params
    const { title, viewsCount } = req.body

    return res(
      ctx.json({
        updatedAt: Date.now()
      })
    )
  })

The same generics apply to any rest request handler: rest.get(), rest.post(), rest.delete(), etc.

GraphQL API

A type signature for the GraphQL handlers is:

type GraphQLHandler = <Query, Variables>(args) => MockedResponse

This means we can annotate the Query type (what gets returned in the response) and the Variables of our query.

Let's take a look at some concrete examples.

GraphQL queries

import { graphql } from 'msw'

// Describe the payload returned via "ctx.data".
interface GetUserQuery {
  user: {
    id: string
    firstName: string
    lastName: string
  }
}

// Describe the shape of the "req.variables" object.
interface GetUserQueryVariables {
  userId: string
}

graphql.query
  <GetUserQuery, GetUserQueryVariables>(
  'GetUser',
  (req, res, ctx) => {
    const { userId } = req.variables

    return res(
      ctx.data({
        user: {
          id: userId,
          firstName: 'John',
          lastName: 'Maverick'
        }
      })
    )
  })

GraphQL mutations

Now, let's apply the same approach to a GraphQL mutation. In the case below we're having a UpdateArticle mutation that updates an article by its ID.

import { graphql } from 'msw'

interface UpdateArticleMutation {
  article: {
    title: "string"
    updatedAt: Date
  }
}

interface UpdateArticleMutationVariables {
  title: "string"
}

graphql.mutation
  <UpdateArticleMutation, UpdateArticleMutationVariables>(
  'UpdateArticle',
  (req, res, ctx) => {
    const { title } = req.variables

    return res(
      ctx.data({
        article: {
          title,
          updatedAt: Date.now()
        }
      })
    )
  })

GraphQL operations

When it comes to capturing multiple GraphQL operations regardless of their kind/name, the graphql.operation() truly shines. Although the nature of the incoming queries becomes less predictable, you can still specify its Query and Variables types using the handler's generics.

import { graphql } from 'msw'

type Query = 
  | { user: { id: string } }
  | { article: { updateAt: Date } }
  | { checkout: { item: { price: number } } }

type Variables = 
  | { userId: string }
  | { articleId: string }
  | { cartId: string }

graphql.operation<Query, Variables>((req, res, ctx) => {
  // In this example we're calling an abstract
  // "resolveOperation" function that returns
  // the right query payload based on the request.
  return res(ctx.data(resolveOperation(req)))
})

Bonus: Using with GraphQL Code Generator

My absolute favorite setup for mocking GraphQL API is when you add GraphQL Code Generator to the mix.

GraphQL Code Generator is a superb tool that allows you to generate type definitions from your GraphQL schema, but also from the exact queries/mutations your application makes.

Here's an example of how to integrate the types generated by GraphQL Codegen into your request handlers:

import { graphql } from 'msw'
// Import types generated from our GraphQL schema and queries.
import { GetUserQuery, GetUserQueryVariables } from './types'

// Annotate request handlers to match 
// the actual behavior of your application.
graphql.query<GetUserQuery, GetUserQueryVariables>('GetUser', (req, res, ctx) => {})

With your data becoming the source of truth for your request handlers, you're always confident that your mocks reflect the actual behavior of your application. You also remove the need to annotate queries manually, which is a tremendous time-saver!

Advanced usage

We've covered most of the common usage examples above, so let's talk about those cases when you abstract, restructure and customize your mocking setup.

Custom response resolvers

It's not uncommon to isolate a response resolver logic into a higher-order function to prevent repetition while remaining in control over the mocked responses.

This is how you'd annotate a custom response resolver:

// src/mocks/resolvers.ts
import type { ResponseResolver, RestRequest, RestContext } from 'msw'

interface User {
  firstName: string
  lastName: string
}

export const userResolver = (user: User | User[]): ResponseResolver<RestRequest, RestContext, User> => {
  return (req, res, ctx) => {
    return res(ctx.json(user))
  }
})

import { rest } from 'msw'
import { userResolver } from './resolvers'
import { commonUser, adminUser } from './fixtures'

rest.get('/user/:userId', userResolver(commonUser))
rest.get('/users', userResolver([commonUser, adminUser])

Custom response transformers

You can create custom context utilities on top of response transformers.

Here's an example of how to create a custom response transformer that uses the json-bigint library to support BigInt in the JSON body of your mocked responses.

// src/mocks/transformers.ts
import * as JsonBigInt from 'json-bigint'
import { ResponseTransformer, context, compose } from 'msw'

// Here we're creating a custom context utility
// that can handle a BigInt values in JSON.
export const jsonBigInt =
  (body: Record<string, any>): ResponseTransformer => {
    return compose(
      context.set('Content-Type', 'application/hal+json'),
      context.body(JsonBigInt.stringify(body))
    )
  }

Note how you can compose your custom response transformer's logic by utilizing the compose and context exported from MSW.

You can use that jsonBigInt transformer when composing mocked responses in your handlers:

import { rest } from 'msw'
import { jsonBigInt } from './transformers'

rest.get('/stats', (req, res, ctx) => {
  return res(
    // Use the custom context utility the same way
    // you'd use the default ones (i.e. "ctx.json()").
    jsonBigInt({
      username: 'john.maverick',
      balance: 1597928668063727616
    })
  )
})

Afterword

Hope you find this article useful and learn a thing or two about improving your mocks by covering them with type definitions—either manual or generated ones.

There can be other scenarios when you may find yourself in need to cover your mocks with types. Explore what type definitions MSW exports and take a look at the library's implementation for reference.

Share this article with your colleagues and give it a shoutout on Twitter, I'd highly appreciate it! Thank you.

Useful resources

When should I (not) use mocks in testing?

Artem Zakharchenko — Tue, 24 Nov 2020 15:44:06 +0000

What is "mocking"?

Mocking in programming refers to an action of substituting a part of the software with its fake counterpart.

Mocking technique is primarily used during testing, as it allows us to take out certain aspects of the tested system, thus narrowing the test's focus and decreasing the test's complexity.

Depending on the software that is being tested, there are multiple things that can be mocked:

Environment and context. To assert a list of user's purchases you can mock the user already being authenticated, instead of going through the authentication in the unrelated test suite.
API communication. When testing a checkout process you don't want to make an actual purchase and be charged for it.
External dependencies. When testing how our system reacts to various payloads from an external library or SDK you may emulate what the latter return.

Understanding when to apply and, most importantly, when not to apply mocking is a vital skill to help you ensure your tests are reproducible and credible. Today I would like to share some opinionated views and guidelines that help me decide and integrate mocking into my tests and still trust them.

The purpose of mocking

By mocking certain parts of our system we drop them from the testing equation. That way the mocked parts become a test's pre-requisites, a configurable given that should not be acted upon.

Some of the biggest benefits of mocking:

Makes a tested system, or its parts, more predictable by configuring or fixing dynamic system parts (i.e. HTTP requests).
Gives a granular control over the system's state at a given point in time.
Keeps tests more focused by treating certain internal or external system's aspects as pre-requisites.

The dangers of mocking

Deviating system

What mocking essentially does is that it replaces one part of the system with a seemingly compatible part.

Mocking creates a deviation in the system that always results in an altered system.

Although it may still look and behave similarly, the system's integrity gets compromised and with an excessive or misguided mocking one may find themselves testing an entirely different system than one should.

// Mocking or stubbing request issuing module
// as a part of a test implies that the tested system
// does not execute the actual "fetch" any longer.
global.fetch = jest.fn().mockReturnValue(
  Promise.resolve({ data: 'ok' })
)

Learn about why you should Stop mocking fetch with Kent C. Dodds.

Testing implementation details

Another dangerous drawback of a misplaced mocking is that one may fall into the trap of implementation details testing without even realizing it. Replacing any part of the internal/external system is incredibly powerful and
comes with the responsibility on your shoulders not to misuse mocking to test things on a level much deeper than it is necessary.

// context.js
export const context = {
  // Lookups the list of sessions.
  lookupSessions() { ... },

  // Returns the active user from the latest session.
  getUser() {
    const sessions = this.lookupSessions()
    const latestSession = sessions[sessions.length - 1]
    return latestSession.user
  }
}

// context.test.js
import { context } from './context'

beforeAll(() => {
  spyOn(context, 'lookupSessions').mockImplementation()
})

test('returns the active user', () => {
  const user = context.getUser()

  expect(context.lookupSessions).toBeCalled()
  expect(user).toBeDefined()
})

The issue here is that if context.getUser stopped relying on the lookupSessions method the test would fail. Even if context.getUser still returns the proper user.

The issues caused by mocking can be split into two categories:

Misplaced mocking. Mocking is not applicable in the current circumstances and should be avoided.
Inaccurate mocking. Mocking is applicable, but executed poorly: the extend of mocks is excessive, or the mocked part's behavior violates the system's integrity.

When to mock?

Let's focus on the mocking in the context of tests.

The purpose of testing is to give you confidence in the system you are developing. The more you mock, the more you deviate from the original system, the more it decreases the amount of confidence your tests give you. It is crucial to know what and when to mock during test runs.

When it comes to mocking there is a golden rule:

If you can omit mocking, omit mocking.

Despite being somewhat extreme, this rule guards you against unnecessary mocking, making each time you decide to mock something a conscious and well-weighed choice, rather than a reach-out tool for each and every situation.

There are cases, however, when mocking is beneficial and even necessary in tests. Those cases derive from the testing levels and the boundaries each level establishes.

Mocking in different testing levels

Mocking plays a crucial part in defining testing boundaries. Testing boundary, or in other words an extent of a system covered by a particular test, is predefined by the testing level (unit/integration/end-to-end).

Unit tests

It is unlikely for mocking to be applicable in unit tests, as that means there is a part of the system the unit depends on, making that unit less isolated and less subjected to unit testing.

Whenever you reach out to mock things in a unit test that is a good sign you are in fact writing an integration test. Consider breaking it down into smaller dependency-free pieces and covering them with unit tests. You may then test their integration in the respective testing level.

In certain cases, mocking has a place in unit tests when those units operate on data that is dependent on runtime, or otherwise hard to predict. For example:

/**
 * Returns a formatted timestamp string.
 */
function getTimestamp() {
  const now = new Date()
  const hours = now.getHours()
  const minutes = now.getMinutes()
  const seconds = now.getSeconds()

  return `${hours}:${minutes}:${seconds}`
}

To unit test the getTimestamp function reliably we must know the exact date it returns. However, the date has a variable nature and will depend on the date and time when the actual test will run.

A mock that emulates a specific date during the test would allow us to write an assertion with confidence:

beforeAll(() => {
  // Mock the timers in Jest to set the system time
  // to an exact date, making its value predictable.
  jest.useFakeTimers('modern');
  jest.setSystemTime(new Date('01 Jan 1970 14:32:19 GMT').getTime());
})

afterAll(() => {
  // Restore to the actual timers and date
  // once the test run is done.
  jest.useRealTimers()
})

test('returns the formatted timestamp', () => {
  expect(getTimestamp()).toEqual('14:32:19')
})

Integration tests

In the integration tests, on the other hand, mocking helps to keep the testing surface focused on the integration of the system's parts, leaving unrelated yet dependent pieces to be fake.

To illustrate this point, let's consider an integration test of a "Login" component—a form with inputs and a submit button that makes an HTTP call upon form submission.

const LoginForm = () => {
  return (
    <form onSubmit={makeHttpCall}>
      <input name="email" type="email" />
      <input name="pasword" type="password" />
      <button>Log in</button>
    </form>
  )
}

The goal of an integration test is to ensure that the inputs rendered by the "Login" component are operational (can be interacted with, validated, etc.) and that the login form can be submitted given correct values.

However, there is a part of our "Login" component's implementation that stretches far beyond the integration of its compounds: the HTTP call. Making an actual request as a part of an integration test would increase its surface to assert two integrations at the same time:

Integration of the Login form's components;
Integration of the Login form and some external HTTP server.

In order to keep the testing surface focused on the component itself, we can mock an HTTP request, effectively making it a pre-requisite of the "Login" test. Moreover, with mocks, we can model various HTTP response scenarios, such as a service timeout or failure, and assert how our login form handles them.

// Example of the "Login" component test suite
// written using an abstract testing framework.

test('submits the form with correct credentials', () => {
  // Emulate a successful 200 OK response upon form submission.
  mockApi('/service/login', () => {
    return new Response('Logged in', { status: 200 })
  })

  render(<LoginForm />)

  fillCredentials({
    email: 'john.maverick@email.com',
    password: 'secret-123'
  })

  expect(successfulLoginNotification).toBeVisible()
})

test('handles service failure gracefully', () => {
  // For this particular test mock a 500 response.
  mockApi('/service/login', () => {
    return new Response(null, { status: 500 })
  })

  fillCredentials(...)

  expect(oopsTryAgainNotification).toBeVisible()
})

End-to-end tests

End-to-end tests may utilize mocking of external dependencies, like communication with payment providers, as their operability lies beyond your system's responsibilities.

Mocking any part of the system itself in an end-to-end test contradicts the purpose of this testing level: to ensure the system's functionality as a whole.

It is also plausible to have no mocking at all during end-to-end testing, as that way your system behaves identically to its production version, giving you even more confidence in these tests.

Afterword

Thank you for reading! I hope I was able to contribute to your attitude towards mocking and the tips from the article will be useful next time you sit to write a test.

If you like the material consider Following me on Twitter and checking out my personal blog, where I write about technical and non-technical aspects of software engineering.