goldbergyoni/nodejs-testing-best-practices: 50 rules on where a backend test should start
Beyond the basics of Node.js testing. Including a super-comprehensive best practices list and an example app (April 2025)
At a glance
- What is it?
- A curated best practices list and a working example Node.js backend, aimed at backend engineers who keep restarting tests at the wrong layer. The argument is a strategy: component tests first, a handful of E2E tests, unit tests only where logic is genuinely hard.
- Who is it for?
- Adopt this list if your team writes backend tests without a settled answer about which layer a new test belongs to, since the Testing Diamond answer is cheap to agree on and expensive to retrofit. Skip it if you have already settled that question and want a runner comparison instead, because nothing here changes how Jest, Vitest or the Node test runner execute a file.
- Can I use it commercially?
- Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
- Is it still maintained?
- Yes. The repository last received commits 52 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- goldbergyoni/nodejs-testing-best-practices4,409 ★ · +14
| Repository | 2026-09-30 | 2026-11-15 |
|---|---|---|
| goldbergyoni/nodejs-testing-best-practices | 4.4k | 4.4k |
14 Stars in the last 46 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The Testing Diamond puts component tests at the top, not unit tests
The first numbered rule is a position, not a technique: always start with integration and component tests. A component test runs a whole component, a microservice say, as it really is, through its API, with every layer present including the database, while anything outside it is faked. Rule 1 calls this the Testing Diamond and claims it catches 99 percent of bugs, a number the README repeats in rule 2 as the reason E2E budgets should be small.
The argument is sequencing rather than coverage. When a sprint starts, what a team knows is the behavior a caller expects, so the public interface is the cheapest thing to test and the hardest thing to guess wrong. Rule 2 then puts a ceiling on the top of the diamond: write 3 to 10 end to end tests, maybe a couple more for a larger component, and reserve them for risks component tests cannot reach, namely configuration mistakes, misunderstandings with third party services and infrastructure faults.
Unit tests survive in the list only under one condition, which rule 2 states as non-trivial logic or algorithms. Inner functions of a component whose overall output is still unclear are what rule 1 calls wasted effort.
Practice 3 ties coverage reports to features rather than line counts
Rule 3 shifts the unit of test from the function to the feature, and it ties coverage reports to requirements instead of to line counts. Coverage output becomes a map of which controllers, modules and folders the suite actually exercises, and the check is whether core routes and messages show up there, not whether a percentage threshold was crossed.
Rule 4 answers the other question teams argue about: when to write. Tests are written during coding, before or after as is convenient, rather than in a cleanup phase at the end of the sprint. That is the practical difference between a rule list and a policy document. A rule about which layer a test belongs to is enforceable in review. A rule about test authors is not.
The repository backs the argument with code rather than prose. There is an example-application directory holding the sample backend, a recipes directory with further examples across platforms, and an anti-patterns directory. A jest.config.js sits at the root, so the examples run on the same runner the guide reasons about.
package.json names the suite integration-test-a-z and mixes NestJS into a Jest guide
The root package.json is worth reading closely, because it is where the prose and the executable setup diverge. The package is named integration-test-a-z, its description field is empty, and its license field reads ISC, while GitHub reports the license as unknown. Anyone checking licence terms for reuse should go to the file rather than the metadata page.
The dependency list is wider than a Jest guide needs. It pulls in sequelize and pg for the database, amqplib and @aws-sdk/client-sqs plus @pulumi/rabbitmq for queues, jsonwebtoken and express for the service itself, and the full @nestjs trio alongside reflect-metadata and rxjs. NestJS has no section in the table of contents. It is there because one recipe under test:nestjs uses it, which means the root install carries framework packages the guide itself never discusses.
The close reading catch is in the scripts block. A project whose first rule is to start with component tests ships a root-level test script that is a plain jest call, plus a watch script capped at two workers.
The db:migrate and db:seed scripts cd into data-access before Jest runs
Clone the repository and use the scripts the package.json already defines. The Node version is pinned by a .nvmrc file, and dependencies are locked by a package-lock.json at the root.
The database layer lives in example-application/data-access and is driven by sequelize-cli, which is why both data scripts change directory before running instead of pointing at a config file path.
cd example-application/data-access && sequelize-cli db:migrate
cd example-application/data-access && sequelize-cli db:seed:allRun the migration before the suite or every database-backed test fails on a missing schema. The plain test script is a bare jest call, and the watch variant caps the worker count at two.
jest --watch --silent --maxWorkers=2 --verbose=false
node --inspect=9229 node_modules/.bin/jest --watch --runInBandThe second command opens a Node inspector on port 9229 and forces --runInBand, which attaches a debugger to one test process instead of to a worker pool. It is the practical entry point when a component test fails inside the example app and you need the real database in the stack.
The example claims 40 tests in 5 seconds including the database
The performance claim is stated once, in the header, and it is specific enough to be checked: 40 tests in 5 seconds including database. No breakdown is given for how much of that is the database, no hardware is named, and no run configuration is attached to the number. Treat it as a design target for the sample app rather than a benchmark for your own suite.
What the claim does imply is architectural. Five seconds means the suite cannot be spending its budget on container startup or on per-test database provisioning. That is consistent with rule 6, the first item under Database And Infrastructure Setup, whose section is titled around optimizing your DB, MQ and other infra for testing. Six practices live there, and a separate section, Web Server Setup, holds three more on starting and stopping the backend API cleanly.
So the speed is not a Jest setting. It is what you get when the infrastructure is shaped for tests before the suite is written.
Mocking gets its own file while the table of contents sends you to another repository
Mocking.md and the anti-patterns directory are where the list goes past advice into diagnosis. An anti-pattern entry is easier to argue about than a rule, because someone in the room has just done it.
A navigational detail worth knowing before you follow the table of contents: every anchor in it points at github.com/testjavascript/nodejs-integration-tests-best-practices, not at the repository holding this README. The section titles themselves, Strategy and Workflow, Database And Infrastructure Setup, Web Server Setup, The Test Anatomy, Integration, Dealing With Data, Message Queue and Mocking, are correct and match what the page describes. The links underneath them are not. Eight numbered sections are promised, five practices in the first and eight in the fifth and seventh, and the eight-practice integrations section is where the third party contract coverage sits.
For a reader arriving through those links, expect to land on a different repository than the one named in this project.
Vitest and Node:test change the runner, not the Testing Diamond
The obvious alternative to this project is not another best practices list. It is a different runner, such as Vitest or the Node test runner. The root package.json resolves the question for the examples by picking Jest and keeping --maxWorkers=2 in the watch script.
The difference in approach between the runner and the list matters more than the runner. Vitest and Node:test change what executes the assertions, and with it the config surface and the worker model. The Testing Diamond does not move. Whether a test hits a real database through sequelize, whether a queue message is read back from a real broker, whether the API is started and stopped for the suite: none of that is decided by the test framework. Sections 2, 6 and 7 of the list, covering infrastructure, data and queues, are written against that boundary rather than against Jest.
Adopting the list with a different runner is the move for a team that has already chosen one. It is not a migration the project offers tooling for. The single test:nestjs script, which pins its own config file, shows how narrowly scoped that kind of runner-specific path actually is.
Editorial conclusion
Adopt this list if your team writes backend tests without a settled answer about which layer a new test belongs to, since the Testing Diamond answer is cheap to agree on and expensive to retrofit. Skip it if you have already settled that question and want a runner comparison instead, because nothing here changes how Jest, Vitest or the Node test runner execute a file. Before adopting anything from it, run the example-application suite on your own hardware and check the header claim of 40 tests in 5 seconds against your own database and disk, since that number comes with no hardware or run configuration attached to it.
Frequently asked questions
Does nodejs-testing-best-practices need Jest, or can I apply it with Vitest or the Node test runner?
The practices are written against what a test touches, database, queue, live API, rather than against a runner. Only the example application is tied to Jest, through the root jest.config.js and the test script that calls jest.
How many end to end tests does nodejs-testing-best-practices say to write?
Practice 2 sets a budget of 3 to 10 end to end tests, maybe a couple more for a larger component. Those tests are reserved for configuration issues, third party misunderstandings and infrastructure problems, since component tests already catch 99 percent of bugs.
When does nodejs-testing-best-practices say unit tests are worth writing?
Only for non-trivial logic or algorithms, where isolating the module from its surroundings makes the test easier to write. Practice 1 treats unit tests written before the component's overall outcome is clear as wasted effort.
What does nodejs-testing-best-practices require before running the example application?
The database has to exist first. The db:migrate and db:seed scripts run sequelize-cli inside example-application/data-access, and the suite depends on that schema being in place.
What licence does nodejs-testing-best-practices use?
The root package.json declares ISC in its license field. The repository metadata reports the licence as unknown, so the file is the only source to check before reusing anything.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/goldbergyoni-nodejs-testing-best-practices)Star history chart for your README
[](https://hysenlabs.com/projects/goldbergyoni-nodejs-testing-best-practices)Was this useful?