semtest-e2e

A(nother ?) light E2E test framework for nodejs

semtest-e2e: (javascript) => TAP

So what is this about ?

Concieved during the time I was writing semverse, semtest-e2e is a simple yet efficient e2e test framework for nodejs webservices. Its main goal (besides honing my skills on developing and maintaining an npm module) is to alleviate all the boilerplate around:

• testing code with Tape (in its Blue-Tape version)
• testing the webservice on its API level, by using Supertest
• enforcing E2E test best practices, such as no state sharing between tests, endpoint focused tests, and self-documenting code

It is an essay on abstracting these three tools in a practical one, suited for my needs on semverse.

I also decided that I would apply the same standards I use on semverse:

• 100 percent unit test coverage
• JSLint compliance
• Functional programming all the way !
• Automatic semantic versioning

Installation

Installation is pretty straightforward :

$ npm install --save-dev semtest-e2e

Usage

$ node your_spec_file.js

or, since tape allows for globbing:

$ tape '**/*.spec.js'

or, since a lot of us uses build pipelines, you can pipe the sources with your favorite build tool. These specs files are autonomous javascript files so you can run them anyway you want. Hurray, separation of concerns !

Documentation

1. Using semtest-e2e to launch your E2E assertions

NOTE : What's described here is the final API semtest-e2e will use. Until then please refer the code to know how to use it (hint: there is no global semtest-e2e function for the moment. This work is done by calling its e2ETests method).

Using semtest-e2e is very simple. You require the module, which gives you the main function, and just call it with the right parameters:

• appStart and appStop are functions to (you've guessed it) start and stop your service. It is mandatory that they have these signatures:

appStat: () => (Promise.Object) (the spun up instance)

appStop: (Object) => (Promise.Any) (takes the instance as parameter)

• Your test suite name as a base for all tests description for the current script. It's always nice to namespace everything so this parameter helps you with that.

• Your assertion with a clean, predefined structure that will help you both ensure your webservice works as intended, and document your code behaviour way better than any comment or README could ever do: semtest-e2e: (appStart, appStop, suiteName, Assertions) => TAP output

2. Assertions structure

Assertions are objects with three keys:

• "when" and "should" are properties that will document your unit test
• "test" is the actual e2e test, written like a function, which takes an instance-based Supertest request as parameter, and on which you'll call Supertest request method to set the tests route case and your expectations regarding this test case.

Let's take an example :

const e2ETests = require("semtest-e2e");
const app = require("myApp/main.js");

e2ETests(
    // Starting function
    app.start,
    // Stopping function
    app.stop,
    // E2E Suite name
    "Main suite",
    // E2E Assertions
    [{
        when: "GET /docs",
        should: "return the Swagger-UI interface",
        test: (r) => r
            .get("/docs/")
            .expect("Content-Type", /json/)
            .expect(200)
    }]);

Here we just passed one assertion to semtest-e2e to check that, on any of our app instance, when we perform a GET request on its "/docs/" endpoint, we get ("get", get it ?) a response with a 200 status and Content-Type header that includes "json" (such as "application/json").

When ran from the console, and piped in a TAP reader like faucet, we get:

$ node myE2ETest.js | faucet
Main Suite: when GET /docs, it should return the Swagger-UI interface
# tests 1
# pass 1
ok

The additional bonus of such structure is that you can fold your code in spec files to only show the documentation part, enabling your to truly document your code with specs, which they are for in the first place :

e2ETests(
    // Starting function
    app.start,
    // Stopping function
    app.stop,
    // E2E Suite name
    "Main suite",
    // E2E Assertions
    [{
        when: "GET /docs",
        should: "return the Swagger-UI interface",
        test: (r) => r
                [..............................................]
    }, {
        when: "GET /api/specs",
        should: "return the Swagger specs",
        test: (r) => r
                [..............................................]
    }]);

Here, whatever the [.....] cover, we can focus on the litteral description of our code instead.

Since these files aren't meant to be delivered in production, we can make them as bloated as we want, for the sake of code literacy instead of performance.

Coverage

I have not investigate that part yet. It might be possible to establish coverage on instanciation but I don't know if it's possible to do that outside of semtest-e2e...

Licence

Do whatever you want with the code, just tell me about it so that I can know at least one person read it xD

Contributing

Open issues and send me PRs like there's no tomorrow, be my guest !