Unit Tests - Enterprise-CMCS/macpro-mako GitHub Wiki

Our Unit Testing Philosophy

We believe that unit tests are the foundation of a healthy codebase. Our philosophy is to write focused, fast, and reliable tests that verify the behavior of individual units of code in isolation.

We follow these core principles:

  • Clarity and Readability: A test should be easy to understand. It should clearly communicate what it is testing and what the expected outcome is. We use descriptive describe and it blocks to structure our tests.
  • Isolation: Unit tests should not depend on external services or other parts of the application. We use mocking to isolate the code under test.
  • Completeness: We aim to test all the important behaviors of a unit, including success cases, edge cases, and error conditions.
  • Speed: Unit tests should be fast. A fast test suite encourages developers to run it often, which helps to catch bugs early.

Tools We Use

Tool Purpose
Vitest Our primary framework for writing and running fast Unit and Integration tests.
Mock Service Worker (MSW) Intercepts network requests and provides mocked data, acting as a fake backend for development and testing. To read more about our mock service worker strategy, please follow the wiki.

How to Run All Unit Tests

To execute all unit and integration tests, run the following command from the project's root directory:

bun test

This command finds and runs all files in the codebase that end with .test.ts or .test.tsx.

Running Specific Tests

When you are working on a specific feature, you can save time by running only the tests related to that feature. To do this, you can pass the path to the test file to the bun test command.

For example, to run only the tests for the date-helper, you would use the following command:

bun test lib/packages/shared-utils/date-helper.test.ts

Snapshot Testing

We use snapshot tests to verify that the UI of our components does not change unexpectedly. This is particularly useful for our email templates and React components.

How it Works

A snapshot test renders a UI component, takes a "snapshot" of it, and then compares it to a reference snapshot file stored alongside the test. The test will fail if the two snapshots do not match.

Updating Snapshots

If you make an intentional change to a component's UI, you will need to update the corresponding snapshot. You can do this by running the following command:

bun test -u

This will tell Vitest to update the snapshot files with the new changes.

Important: Always review the changes to the snapshots before committing them. Make sure that the changes are intentional and do not introduce any regressions.

Writing Good Unit Tests

When writing new unit tests, please keep the following in mind:

  • Structure your tests with describe to group related tests and it to describe the specific behavior being tested.
  • Use mock data from the /mocks directory to simulate different scenarios.
  • Test for both success and failure. What happens when the component gets unexpected data? What about when a network request fails?
  • Keep tests small and focused. Each test should ideally verify a single behavior.

By following these guidelines, we can maintain a high-quality and reliable codebase.