A(nother ?) light E2E test framework for nodejs
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 is pretty straightforward :
$ npm install --save-dev semtest-e2e
$ node your_spec_file.js
or, since tape allows for globbing:
$ tape '**/*.spec.js'
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
Using semtest-e2e is very simple. You require the module, which gives you the main function, and just call it with the right parameters:
appStopare functions to (you've guessed it) start and stop your service. It is mandatory that they have these signatures:
PromiseObject the spun up instancePromiseAny 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 = ;const app = ;;
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 | faucetMain Suite: when GET /docs, it should return the Swagger-UI interface# tests 1# pass 1ok
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 :
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.
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...
Do whatever you want with the code, just tell me about it so that I can know at least one person read it xD
Open issues and send me PRs like there's no tomorrow, be my guest !