Node.js HTTP testing using Node test wrapper

5 min readNov 26, 2019

The problem

If you develop Node applications you might have across SuperTest, Chai HTTP or SuperAgent. SuperTest allows you to make HTTP assertions for the purpose of testing of Node applications. Chai HTTP provides the same functionality but it is tailor-made for the Chai assertion library. Both SuperTest and Chai HTTP are abstractions to SuperAgent which has more low-level HTTP capabilities.

When using SuperTest or Chai HTTP have you found yourself repeating the test client initialization logic in every test file or test? When trying to test authenticated requests, do you find yourself having to repeat authentication logic over and over? Does it feel natural? Do you reckon that refactors like changing your authentication system would lead to so many changes on your tests?

Most Node/Express HTTP tests reveal an unhealthy pattern of repetition. Below are some scenarios detailing the most common repetition patterns.

Scenario 1

Line 3 is repeated on every test file where SuperTest is used to make HTTP assertions.

Scenario 2

Lines 5, 9, … are repeated whenever an HTTP assertion needs to be made. This repetition can be avoided by following the approach in Scenario 1.

Scenario 3

Lines 9, 16, … have to be added whenever requests need to be authenticated. If you ask me this does not feel natural. Things get more complicated when session-based authentication is used. It gets even more complicated when the application in question uses role-based access control.

Code principles

The importance of DRY code even on tests cannot be overstated. What if tomorrow we want to use a different HTTP assertion library? The approach illustrated above would force us to make so many changes to our tests. Every keystroke matters as it requires more time. It also goes without saying that it increases the probability of making a mistake.

Though this is not OOP, changing the tests causes us to break the open-closed principle. This is completely avoidable if we have an abstraction for making assertions on our app. Then, we will only need to modify the abstraction. It is a well-known fact that many software problems result from modifications. We don’t want an avoidable modification to accidentally create a false positive on our tests.

Again this is not OOP but this approach breaks the single responsibility principle. The HTTP tests should know that it is possible to authenticate for instance but not how the authentication is done. Instead, they should focus on HTTP assertions and rely on an abstraction for authentication.

For a small application, this may not be a problem but as the application starts to scale, this can become cumbersome or unsustainable.

Node test wrapper

What is it?

Node test wrapper is a single object that encapsulates all the logic needed to make HTTP assertions on a Node app. This solves the problem of other desired behaviors like authentication. It essentially acts as a black box that abstracts you from details like SuperTest initialization and authentication management.

node-test-wrapper npm package is an interactive CLI that generates test wrapper boilerplate based on your Javascript version and authentication type.

How to use it

Install node-test-wrapper npm package globally

npm install node-test-wrapper -g

yarn global add node-test-wrapper

On your project folder run node-test-wrapper

node-test-wrapper

or use shorthand

test-wrapper

Select the javascript version of the wrapper to be generated

Select the type of authentication that your application uses

Specify the path for the generated wrapper

The wrapper is generated and placed on the path you chose

Customize the generated wrapper to suit the specifics of your application

The generated wrapper has several stubs that need to be updated.

Replace “../path/to/your/app” with the actual path to your app. For example “../../src/app”. As a side note, there is merit in avoiding the creation of a server in the application definition. Tools like SuperTest and Chai HTTP will do this automatically preventing problems with application port when executing tests.
login() — based on the type of authentication your application uses, specify how the authentication parameter will be generated when this function is called with a user object.
loginRandom() — similar to login() but in this case the generated authentication parameter relies on a randomly generated or selected user.
logout() — this simply specifies how the authentication parameter is reset/removed. The default logic should suffice.
preRequest() — this function is triggered every time before the wrapper makes a request. The default logic adds the authentication parameter to the request object if it exists i.e. if login() or loginRandom() were previously called and logout() was not. For example, setting the authorization header in token-based authentication. More pre-request logic can be added but it is crucial that the default logic is retained or modified in such a way that it retains its primary purpose.
HTTP methods — when making HTTP assertions these methods are the methods that should be triggered. Under the hood, they call the respective HTTP methods on the SuperAgent instance. This allows for pre-request logic (defined in preRequest()) to be triggered to add any desired behaviors. The most common HTTP methods are available out of the box but more can be added as and when the need arises.

By default, the wrapper that is generated is based on SuperTest (the most popular Node HTTP assertion library). This can always be changed to Chai HTTP, any similar library or a custom HTTP assertion tool.

Use the wrapper on your tests

Once the wrapper has been tailored to your application it can be used to drive HTTP tests by providing an abstraction that feels natural.

Import the wrapper on your test file
Make HTTP assertions via the wrapper
Where authentication is required invoke login(), loginRandom() or logout() based on the desired behavior
Add any other desired behaviors as functions on the wrapper. Invoke the functions as and when the behaviors are required as is the case with authentication.

Examples

ES5

Wrapper

Test

ES6