Node Native Unit Testing

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• package.json
• src/utils/seo/schema.test.ts
• src/features/pages/pages.utils.test.ts
• src/features/navigation/navigation.utils.test.ts
• src/features/verse/verse.utils.test.ts
• netlify/functions/daily-rebuild/index.test.ts
• src/components/Settings/Font/load-pairing.test.ts

Node Native Unit Testing refers to the implementation of software tests using the built-in node:test runner and node:assert module. This project avoids third-party test runners for unit testing, favoring the native capabilities provided by Node.js for validating domain logic, utility functions, and feature-specific helpers.

The unit testing strategy complements the End-to-End tests suite, which uses Playwright for browser-level behavior. Unit tests are colocated with the source code they verify, following a *.test.ts naming convention.

Sources: AGENTS.md:95-108, e2e/README.md:4-5

Test Architecture and Configuration

The testing infrastructure relies on tsx to execute TypeScript files via the native Node.js test runner. Tests target specific files in the src/ and netlify/ directories.

Execution Flow

The following diagram illustrates how the project triggers and executes unit tests:

The project uses tsx as the execution wrapper to handle TypeScript modules during the testing process.
Sources: package.json:34

Core Testing Libraries

The project utilizes specific native Node.js modules for all unit test files:

• node:test: Provides the describe, test, before, after, and mock functions.
• node:assert/strict: Provides strict equality and deep validation assertions.

Sources: src/utils/seo/schema.test.ts:3-4, src/features/pages/pages.utils.test.ts:1-2

Unit Testing Conventions

The project enforces specific patterns for writing and organizing unit tests to ensure consistency and maintainability.

Structural Requirements

• Colocation: Unit tests reside next to the module they verify as *.test.ts files.
• Organization: Tests use describe blocks to group units of logic and test() for individual cases. The project explicitly avoids the it() alias.
• Hooks: before, beforeEach, after, and afterEach hooks must be wrapped inside the describe block to which they apply.
• Helper Functions: File-local helpers must be placed after imports but before describe blocks.

Sources: AGENTS.md:98-108

Comparison of Testing Suites

Feature	Unit Testing	End-to-End (E2E)
Runner	node:test	Playwright
Command	pnpm test	pnpm test:e2e
Location	src/**/*.test.ts	e2e/specs/*.spec.ts
Focus	Implementation / Pure Helpers	Browser-level Behavior / A11y

Sources: e2e/README.md:4-5, package.json:34-35

Mocking and Dependency Injection

Native Node.js mocking is used to intercept network requests, global browser objects, and environmental variables.

Mocking Strategies

1. Function Mocking: Use mock.fn() to create spy functions or substitute implementations.
2. Method Mocking: Use mock.method() to override existing methods on objects (e.g., globalThis.localStorage).
3. Cleanup: Call mock.restoreAll() in afterEach hooks to prevent state leakage between tests.

Sources: AGENTS.md:103-104, netlify/functions/daily-rebuild/index.test.ts:27-29

Example: Mocking Browser Globals

Because unit tests run in a Node.js environment, browser globals like document and localStorage are stubbed using Object.defineProperty and mock.method.

This sequence ensures that tests simulating browser environments do not pollute the global Node.js scope permanently.
Sources: src/components/Settings/Font/load-pairing.test.ts:29-45, src/components/Settings/ThemeMode/theme-mode.test.ts:8-33

Feature-Specific Testing Patterns

Unit tests are applied to various domains within the project, including SEO, Navigation, and Content features.

Content and SEO Validation

Tests for SEO utilities ensure that JSON-LD and meta tags are generated correctly based on page metadata. These tests use assert.deepEqual to validate complex object structures for search engine schemas.
Sources: src/utils/seo/schema.test.ts:50-70, src/utils/og.test.ts:36-50

Feature Utility Testing

Utility tests for features like Navigation and Verse management focus on pure function logic, such as slug generation and URL building.
Sources: src/features/navigation/navigation.utils.test.ts:81-90, src/features/verse/verse.utils.test.ts:35-41

Serverless Function Testing

Netlify functions are tested by passing mocked fetch and log dependencies into the handler, allowing for assertion of request methods and URL parameters.
Sources: netlify/functions/daily-rebuild/index.test.ts:46-65

Summary

Node Native Unit Testing in this project provides a fast, dependency-light framework for validating core business logic. By utilizing node:test and node:assert/strict, the project maintains high technical accuracy and consistency without the overhead of external testing frameworks like Jest or Vitest. Unit tests are integrated into the primary pnpm validate workflow to ensure code health before deployment.

Sources: package.json:34-39, AGENTS.md:7-10