Testing
Unit testing is a core part of the PASS development cycle. If you're not familiar with unit testing, or you want to know more about how unit testing is used in PASS, you're in the right place.
PASS requires tests to be included with every non-trivial PR, and we aim for 95% code coverage.
If you've never done unit testing or test-driven development before, we highly recommend dipping your toes in. Unit testing can seem strange at first, but learning how to unit test will make you a better developer, and will make your code more stable. There are tons of resources online that can help you get started. A good one is this video by Fireship.
NOTE: A unit test checks a unit of behavior, not a unit of code. You want to focus on what your program does, regardless of how it does it.
PASS uses two main libraries for unit testing:
- Vitest is our testing harness
- React Testing Library is used to make testing React component behavior easier
Vitest is a newer testing framework in the javascript ecosystem. It uses ES modules natively, making it very easy to configure out of the box.
You can find Vitest's Getting Started Guide here.
Vitest is also backwards compatible with Jest, currently the most popular Javascript testing library. If you're wondering how to do something in vitest, and you're having trouble finding advice online, chances are you can look up the same question for Jest and get the right answer.
React Testing Library is our main utility library for dealing with UI behavior and the DOM. It believes that tests are stronger if they deal with DOM nodes and HTML, rather than react components, because HTML is closest to what the user actually uses.
You should write tests for any PRs more complex than a trivial UI change. Tests go in the test folder, and should match their corresponding file in the src folder. And they are suffixed with .test.js[x]. So if you create a new component called src/components/MyCoolNewComponent.jsx, you should also have a test file test/components/MyCoolNewComponent.test.jsx.
You can run tests with the command npm run test. This will launch vitest in watch mode, so it will rerun tests as you edit files, making it really easy to get into the "red-green-refactor" loop.
If you find that npm run test takes a bit too long, and you only want to run a few specific files, you can do npx vitest path/to/my/file.js to run just one. You can add wildcards to run multiple.
You can check the code coverage of your tests by running the command npm run coverage. You can read more about code coverage here. Note that 100% code coverage simply means that your tests hit every line of your code. It does not mean your code is free of bugs.
We generate our reports using v8, which is provided by vitest. The report preesents 4 columns:
- The percentage of statements in tested files that the tests hit
- The percentage of logical branches in tested files that the tests hit
- The percentage of functions
- A list of specific lines that weren't covered by tests
We are working to raise all these numbers to 100%. Our only requirement for testing coverage at this time is that your PR does not cause test coverage to go down. Top of page ⬆️