testing

name	testing
description	How to write and run tests in @jsenv/core. Use when adding, running, or understanding tests in any package of this monorepo.

Overview

Testing in @jsenv/core focuses on behavior verification and regression prevention rather than exhaustive coverage. Tests capture actual behavior to ensure changes don't break existing functionality.

Running Tests

Run tests from the repo root to ensure the correct Node.js version (25.8.1):

node --conditions=dev:jsenv <test-file>

The dev:jsenv export condition uses source files directly — no build step needed. For packages like @jsenv/server, this avoids rebuilding dist/ after every source change.

Snapshot Testing (Primary Method)

• Tests generate markdown files containing inputs, outputs, and debug logs
• Snapshots live in _test-name.test.js/ directories alongside test files
• Important: Snapshot tests do not "fail" in the traditional sense — they always pass and update snapshots automatically. You must manually read and verify snapshot files to ensure results haven't changed unexpectedly
• Review snapshot diffs to verify intended behavior changes

Debug Logging in Tests

• DEBUG=true output appears in snapshot markdown files, not the terminal
• Use targeted logging to trace complex behaviors during development
• Clean up debug logs once issues are resolved

Test Organization

• Co-locate tests with source code or place in dedicated tests/ directories
• Browser tests use Playwright for real browser behavior
• Node.js tests for server-side and CLI functionality
• Integration tests for cross-package interactions

Goal

Write tests that catch regressions and document expected behavior, not to achieve high coverage metrics.