Node.js recently shipped an experimental test runner. This talk will explore the test runner's architecture and API, and show how to use it with other core modules to create a testing experience with no external dependencies. This talk will also look at potential future additions to the test runner.
Zero Dependency Testing With Node.js
TestJS Summit 2022
Hi everyone, thanks for coming to my talk. Today I'm going to be talking about zero dependency testing with Node.js, which essentially means that you can start writing your unit tests, integration tests, without having to install anything from npm. So before getting into the nature of Node's new test runner, I wanted to talk a little bit about why a test runner was desired in the first place. So almost all projects need a test runner. So you know, if you're, whether you're building an application or a module that you're planning to publish on npm or whatever, if you're planning to have other people use your code, you almost certainly need tests for it. And then Node.js actually for years now has shipped with a really good assertion library that's just import assert. This is the assertion library that I've been using for years now. I like it. So yeah, that's one less dependency. And then most test runners overlap a lot in terms of functionality anyway. So you know, every test runner runs some tests. They generally have features like timeouts, you know, reporting which tests passed and failed, skipping tests, things like that. So you know, there are differences. So some test runners are more suited towards front-end development. Some do things like injecting globals into your code without your knowledge. Some execute their tests inside of different contexts. So you might have surprising results whenever you, you know, check for equality and things like that. But you know, so there are these rough edges, but in general, you know, a lot of test runners have a lot of overlap. And then on top of that, NPM is just really a dangerous place. There's, you know, over the years, there've been a number of incidents, things like left pad, the colors.js thing, even more recently, the minimist package, which I think has like 50 million downloads or something like that. Nothing happened to it on NPM, but the GitHub repository went away. So like, all of these third-party dependencies that you're taking on come with a lot of issues. Third-party dependencies that you're taking on come with some risk and some cost. And so that's just, you know, one reason why having a test runner built in, I feel is useful. And also, there's just a general trend to have more of these batteries included in the runtimes. So, you know, now Node has a built-in test runner. I'm pretty sure Bun has one. I know Dino has one. So this is becoming more and more common. And then, you know, here's my tweet from over a year ago. I believe that Node should ship a test runner and, you know, I feel pretty strongly about that. So some of the features in the new test runner, you can run the test runner through the CLI interface that has the Node chips now with the dash dash test flag, or you can actually just execute a standalone file containing tests. So say you have your file foo.js, you can just say Node foo.js, and if you're using the test runner in there, it'll still just work. When it comes to actually writing tests themselves, there's, you know, we support synchronous code, promises, or async await-based code. And even, you know, because Node still does have a lot of callback-based APIs, we support callback-based tests as well. If you're coming from a test runner like tap or tape, then we do support test style tests using the test function. If you're coming from a test runner like Mocha or Jest, we have describe and it functions. So under the hood, everything uses test, describe and it are just kind of implemented on top of test. But, you know, if you're looking for that familiar API, it is there. We support nesting tests. So you can have, you know, a test with arbitrarily nested tests inside of it. Same, if you have describe, you can have suites containing more suites and more tests and things like that. Skip and to do tests. So, you know, if you just want to skip over a test, there's a few different ways that you can do that. To do is kind of, it's similar to skip in the fact that it won't cause your test suite to fail, but it will still execute the test and kind of don't care about the result. We also have only tests. So if you start the CLI runner with dash dash test only, then any tests that you have annotated as being only tests are the only ones that will be executed. And then you can also filter tests by the name of the test. So if you use the dash dash test name pattern, you can actually pass in a regular expression and Node will only execute the test whose names match that pattern. So if you wanted to actually write a test, what would it look like? Here's a very simple example using nothing but Node's assert module and Node's test module. Here we have two tests. One is a synchronous test that passes. And the other is an asynchronous test, which fails. The asynchronous test, even though it looks like synchronous code, it's an async function, so it returns a promise. That promise rejects whenever the assertion fails. So two things worth noting here is, you'll see here, we're using Node colon test. The Node colon prefix can be used to import any Node core module. But starting with the test module, and likely with all modules added to Node core moving forward, you have to use the Node colon prefix. If you just try to use the word test here, it would actually fall back to trying to load from user land. And speaking of user land, the test runner itself is actually published on NPM. So right now, the test runner exists in Node 18 and 16. Node 14 is still supported, though. So a few people took the code from Node core, kind of ported it to work in an NPM module, and published it. So you can just NPM install test if you're on Node 14, and you'll still have access to all this functionality. So after you execute your test, this is what the output will look like. So this output is called TAP, which stands for Test Anything Protocol. And it's not the most easy for humans to parse, but you can do interesting things like, you know, pipe it into a different reporters and things like that and have it formatted differently. But you can see here that we have OK1. That's the first test. That was the synchronous passing test. It passed in 1.87 milliseconds. And then the second test was not OK. Not OK is how TAP indicates a failure. You can see that there was a test code failure. We expected the assertion, we asserted that the value 1 would be equal to 2, and clearly it's not. So the test failed. And then at the bottom, we have a little test summary. So there were two tests that were executed. One passed, one failed. Zero were canceled, zero skipped, no to-do tests, and then the entire process took about 11 milliseconds. So just some of the future work for the test runner. We have a pull request that's open right now for a TAP parser. So that will allow us to do better reporting inside of the CLI runner. The CLI, for every file that it's going to execute, it spawns a child process that generates its own TAP. The way it works now is if there's a failure, then we just take all of the standard output and standard error for that file and display it. If no tests fail, then we kind of just say it passed and don't show any output. The TAP parser will actually allow us to intelligently parse that output and display things a little more nicely. We also want to use the TAP parser to build out reporters. So as I said earlier, TAP is not the prettiest thing to look at. So we want to implement some reporters that can actually transform that into something a little easier for humans to read. And then we'd like to build in code coverage and mocking, just because these are two pretty significant features that really make a test runner feel mature, in my opinion. So the test runner is still listed as experimental, but I don't expect there to be a lot, if many at all, breaking changes in it. I have a link here to the documentation for it and encourage everyone to go out and at least give it a try. That's everything I had. Thanks for coming. Bye.