A comprehensive, extensible testing framework for NodeBoot applications that provides a plugin-based architecture for dependency injection testing, service mocking, and lifecycle management.
- Quick Start
- Architecture Overview
- Hook Types: Setup vs Return Hooks
- Available Hooks
- Best Practices
- Troubleshooting
- Migration Guide
- Hook Reference
- Extending
npm install @nodeboot/node-test
# or
pnpm add @nodeboot/node-testimport{describe,test}from"node:test";importassertfrom"node:assert/strict";import{useNodeBoot}from"@nodeboot/node-test";import{MyApp}from"./MyApp";describe("My App Integration Tests",()=>{const{useHttp, useService, useConfig}=useNodeBoot(MyApp,({useConfig, useMock, useEnv, usePactum})=>{// Test configurationuseConfig({app: {port: 3001},database: {url: "sqlite::memory:"},});// Environment variablesuseEnv({NODE_ENV: "test"});// Enable Pactum for HTTP testingusePactum();// Mock a serviceuseMock(EmailService,{sendEmail: ()=>Promise.resolve(),});});test("should handle API requests",async()=>{const{get}=useHttp();constresponse=awaitget("/api/users");assert.equal(response.status,200);});test("should access services",()=>{constuserService=useService(UserService);assert.ok(userService,"UserService should be defined");});});For comprehensive integration test examples using the NodeBoot Test Framework with Node.js test runner, refer to the Node.js Test Demo project.
Feel free to explore it, run it, and modify it to get a hands-on understanding of how to leverage the NodeBoot Test Framework effectively.
You can also check the demo projects:
- Node.js Test Demo - Integration tests using Node.js built-in test runner.
The NodeBoot Test Framework follows a layered, plugin-based architecture designed for maximum extensibility and composability:
┌─────────────────────────────────────────────────────────┐
│ Test Runner Integration │
│ (node:test, Mocha, Vitest, etc.) │
├─────────────────────────────────────────────────────────┤
│ Custom Hook Libraries │
│ (MochaHooksLibrary, etc.) │
├─────────────────────────────────────────────────────────┤
│ Core Framework │
│ (NodeBootTestFramework, HookManager, HooksLibrary) │
├─────────────────────────────────────────────────────────┤
│ Hook System │
│ (Hook base class, lifecycle phases) │
├─────────────────────────────────────────────────────────┤
│ NodeBoot Application │
│ (IoC Container, Services, Config) │
└─────────────────────────────────────────────────────────┘
- Plugin Architecture: Everything is a hook that can be added, removed, or customized
- Lifecycle-Driven: Clear, predictable execution phases
- Priority-Based: Hooks execute in controlled order based on priority
- State Management: Hooks can store and share state across lifecycle phases
- Test Runner Agnostic: Core framework works with any test runner
- Composable: Hook libraries can extend and combine functionality
The framework uses a priority-based hook system that executes in phases:
- beforeStart: Setup before application starts
- afterStart: Configuration after application starts
- beforeTests: Setup before test suite runs
- afterTests: Cleanup after test suite completes
- beforeEachTest: Setup before each individual test
- afterEachTest: Cleanup after each individual test
The NodeBoot Test Framework provides two distinct types of hooks that serve different purposes in your test lifecycle:
Setup hooks are called during test configuration and are used to prepare your test environment before the application starts. These hooks configure how your application will run during tests.
Key Characteristics:
- Execute during the setup callback function passed to
useNodeBoot() - Run before the application starts
- Used for configuration, mocking, and environment setup
- Cannot access running application services or HTTP endpoints
- Changes take effect when the application starts
Usage Pattern:
consthooks=useNodeBoot(MyApp,({useConfig, useMock, useEnv})=>{// These are Setup Hooks - they configure the test environmentuseConfig({database: {url: "sqlite::memory:"}});useMock(EmailService,{sendEmail: ()=>Promise.resolve()});useEnv({NODE_ENV: "test"});});Common Setup Hooks:
useConfig()- Override application configurationuseMock()- Mock service implementationsuseEnv()- Set environment variablesusePactum()- Enable HTTP testing toolsuseCleanup()- Register cleanup functionsuseAddress()- Get server address after startup
Return hooks are returned from useNodeBoot() and are used during test execution to interact with your running application. These hooks provide access to services, repositories, and HTTP clients.
Key Characteristics:
- Available after
useNodeBoot()returns - Execute during test runtime when called
- Used for interacting with the running application
- Can access services, make HTTP requests, and query data
- Provide the actual testing capabilities
Usage Pattern:
const{useService, useHttp, useRepository}=useNodeBoot(MyApp,setupCallback);it("should work with services",()=>{// These are Return Hooks - they interact with the running appconstuserService=useService(UserService);const{get, post}=useHttp();constuserRepo=useRepository(UserRepository);});Common Return Hooks:
useService()- Access IoC container servicesuseRepository()- Access data repositoriesuseHttp()- HTTP client for API testinguseSupertest()- Supertest instance for HTTP testinguseConfig()- Access current configuration (read-only)useSpy()- Create spies on service methods
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Setup Phase │ │ Application │ │ Test Execution │
│ │ │ Startup │ │ │
│ Setup Hooks │───▶│ │───▶│ Return Hooks │
│ - useConfig() │ │ - Load config │ │ - useService() │
│ - useMock() │ │ - Start server │ │ - useHttp() │
│ - useEnv() │ │ - Initialize │ │ - useRepo() │
└─────────────────┘ └──────────────────┘ └─────────────────┘
Use Setup Hooks for Configuration:
// ✅ Good - Configure before app startsuseNodeBoot(AppUnderTest,({useConfig, useMock})=>{useConfig({port: 3001});useMock(EmailService,mockImpl);});
Use Return Hooks for Testing:
// ✅ Good - Test the running applicationconst{useService, useHttp}=useNodeBoot(AppUnderTest,setup);it("should work",()=>{constservice=useService(MyService);expect(service.doSomething()).toBeTruthy();});
Don't Mix Hook Types:
// ❌ Bad - Can't use return hooks in setupuseNodeBoot(AppUnderTest,({useConfig, useService})=>{// useService not available hereuseConfig({port: 3001});constservice=useService(MyService);// This will fail!});
Understand Timing:
// ✅ Good - Right timing for each hook typeconsthooks=useNodeBoot(AppUnderTest,({useConfig})=>{useConfig({database: {url: "test.db"}});// Setup: before app starts});it("should access database",()=>{constrepo=hooks.useRepository(UserRepo);// Runtime: after app started});
These hooks are called during the setup callback passed to useNodeBoot() and configure your test environment before the application starts.
Override application configuration for tests.
useConfig({app: {port: 3001},database: {url: "test.db"},redis: {host: "localhost",port: 6380},});Set environment variables for the test session.
useEnv({NODE_ENV: "test",API_KEY: "test-key",DEBUG: "true",});Mock service methods with automatic cleanup.
// Mock with plain function implementationsuseMock(EmailService,{sendEmail: ()=>Promise.resolve(),validateEmail: ()=>true,});// Mock with more complex implementationsuseMock(PaymentService,{processPayment: ()=>({success: true,transactionId: "test-123"}),});Access the server's listening address after startup.
useAddress(address=>{console.log("Server running at:",address);// Set up external test dependencies});Access the application context for advanced setup.
useAppContext(context=>{expect(context.config).toBeDefined();expect(context.logger).toBeDefined();// Additional context validation or setup});Enable Pactum.js integration for HTTP testing.
usePactum();// Uses default server address// orusePactum("http://localhost:3001");// Custom base URL// Now you can use spec() from pactum directly in testsRegister cleanup functions that will be called automatically.
useCleanup({afterAll: ()=>{// Clean up test data, close connections, etc.},afterEach: ()=>{// Reset state between tests},});Get service instances from the IoC container.
constuserService=useService(UserService);constresult=userService.findUser("123");Get repository instances for data layer testing.
constuserRepo=useRepository(UserRepository);awaituserRepo.create({name: "Test User"});constusers=awaituserRepo.findAll();Get HTTP client for API testing.
const{get, post, put,delete: del}=useHttp();// GET requestconstusers=awaitget("/api/users");// POST request with dataconstnewUser=awaitpost("/api/users",{name: "John Doe",email: "john@example.com",});// With headersconstresponse=awaitget("/api/protected",{headers: {Authorization: "Bearer token"},});// Custom base URLconstexternalApi=useHttp("https://api.external.com");constdata=awaitexternalApi.get("/data");Get Supertest instance for HTTP testing with built-in assertions.
constrequest=useSupertest();awaitrequest.get("/api/users").expect(200).expect("Content-Type",/json/).expect(res=>{expect(res.body).toHaveLength(1);});Access the current configuration (read-only during test execution).
constconfig=useConfig();constport=config.getNumber("app.port");constdbUrl=config.getString("database.url");constisProduction=config.getBoolean("app.production",false);Some hooks can be used both during setup and test execution phases.
Can be used as both a setup hook (with callback) and return hook (direct access).
// Setup usage - configure during setup phaseuseNodeBoot(AppUnderTest,({useAppContext})=>{useAppContext(context=>{// Configure based on application contextconsole.log("AppUnderTest started with config:",context.config);});});// Return usage - access during test executionconst{useAppContext}=useNodeBoot(AppUnderTest,setup);it("should access app context",()=>{useAppContext(context=>{expect(context.logger).toBeDefined();expect(context.config).toBeDefined();});});import{describe,test}from"node:test";import{useNodeBoot}from"@nodeboot/node-test";describe("User Management",()=>{consthooks=useNodeBoot(AppUnderTest,commonSetup);describe("Authentication",()=>{// Auth-specific tests});describe("Profile Management",()=>{// Profile-specific tests});});// Mock external dependencies, keep internal services realuseMock(EmailService,{sendEmail: ()=>Promise.resolve()});// ExternaluseMock(PaymentGateway,{charge: ()=>Promise.resolve()});// External// Don't mock UserService, OrderService, etc. (internal business logic)// Use environment-specific configsuseNodeBoot(AppUnderTest,({useConfig})=>{useConfig({app: {port: 20000,},database: {url: process.env.TEST_DB_URL||"sqlite::memory:"},redis: {host: "localhost",port: 6380},// Test Redis instanceexternal: {apiKey: "test-key",baseUrl: "http://localhost:8080",// Mock server},});});const{useRepository}=useNodeBoot(AppUnderTest);// Clean slate for each testbeforeEach(async()=>{constrepository=useRepository(UserRepository);awaitrepository.find({});});import{test}from"node:test";importassertfrom"node:assert/strict";test("should handle async operations",async()=>{constservice=useService(AsyncService);// Use proper async/awaitconstresult=awaitservice.processAsync("data");assert.ok(result,"Result should be defined");// Verify async side effectsconstspy=useSpy(EmailService,"sendEmail");assert.equal(spy.callCount,1,"sendEmail should have been called");});Service Not Found Error
Error: The class MyService is not decorated with @ServiceEnsure your service classes are properly decorated with
@Service().IoC Container Not Found
Error: IOC Container is required for useService hook to workMake sure your app is properly initialized with dependency injection.
Port Conflicts Use random ports in tests:
useConfig({app: {port: 0}});// Random available port
Memory Leaks in Tests Ensure proper cleanup:
useCleanup({afterAll: ()=>{// Close connections, clear caches, etc.},});
Enable Debug Logging
useEnv({DEBUG: "nodeboot:*"});
Inspect Hook Execution The framework logs hook execution order and timing.
Verify Mock Calls
constspy=useSpy(Service,"method");console.log("Mock calls:",spy.calls);console.log("Call count:",spy.callCount);
// Before (manual setup)beforeAll(async()=>{app=newMyApp();server=awaitapp.start();});afterAll(async()=>{awaitserver.close();});// After (NodeBoot Test Framework)const{useHttp}=useNodeBoot(MyApp);| Hook | Category | Description | Docs |
|---|---|---|---|
| useAddress | Setup | Access server listening address after startup | AddressHook |
| useAppContext | Setup/Test | Access application context for advanced setup or during tests | AppContextHook |
| useConfig | Setup/Test | Override and read configuration for tests | ConfigHook |
| useEnv | Setup | Set environment variables for the test session | EnvHook |
| useMock | Setup/Test | Mock service methods with cleanup/restore | MockHook |
| useCleanup | Setup | Register cleanup functions for automatic execution | LifecycleHook |
| usePactum | Setup | Enable Pactum.js integration for HTTP testing | PactumHook |
| useHttp | Test | HTTP client for calling app endpoints | HttpClientHook |
| useService | Test | Access services from IoC container | ServiceHook |
| useRepository | Test | Access repositories for persistence tests | RepositoryHook |
| useSupertest | Test | Supertest agent for HTTP assertions | SupertestHook |
| useSpy | Test (node-test) | Create spies on service methods | SpyHook |
| useTimer | Test (node-test) | Control fake timers and track execution time | TimerHook |
| useMetrics | Test | Record metrics and timers; retrieve summaries | MetricsHook |
| usePerformanceBudget | Setup/Test | Enforce per-label performance budgets | PerformanceBudgetHook |
| useFileSystemSandbox | Setup/Test | Per-test real filesystem sandbox | FileSystemSandboxHook |
| useMemoryFileSystem | Setup/Test | In-memory filesystem replacement (memfs) | MemoryFileSystemHook |
| useLogCapture | Setup/Test | Capture logs for assertion and diagnostics | LogCaptureHook |
| useLogMatch | Setup/Test | Declarative log pattern expectations/forbids | LogMatchHook |
| useLoggerHook | Test | Access the shared Winston logger in tests | LoggerHook |
| useLifecycle | Setup | Unified lifecycle management (before/after) | LifecycleHook |
| useMongoContainer | Setup/Test | Real MongoDB via Docker | MongoContainerHook |
| useMongoMemoryServer | Setup/Test | In-memory single MongoDB instance | MongoMemoryServerHook |
| useMongoMemoryReplSet | Setup/Test | In-memory MongoDB replica set (transactions/change streams) | MongoMemoryReplSetHook |
| useGenericContainer | Setup/Test | Declarative Docker containers via Testcontainers | GenericContainerHook |
| useGenericContainerRaw | Setup/Test | Raw factory-based Testcontainers control | GenericContainerRawHook |
| useToxiproxy | Setup/Test | Network toxicity simulation | ToxiproxyHook |
| useSnapshotState | Setup/Test | Detect unintended shared state mutations | SnapshotStateHook |
| useResourceLeakDetector | Setup/Test | Detect lingering resources/handles across tests | ResourceLeakDetectorHook |
| useHttpClient | Test | HTTP client (alias where applicable) | HttpClientHook |
- Setup: Hooks called during the setup callback passed to
useNodeBoot(). These configure the test environment before the application starts. - Test: Hooks returned from
useNodeBoot()and used during test execution to interact with the running application.
// Setup hooks are used in the configuration callbackconsthooks=useNodeBoot(MyApp,({useConfig, useMock, useEnv})=>{useConfig({database: {url: "test.db"}});// Setup HookuseMock(EmailService,{sendEmail: ()=>Promise.resolve()});// Setup HookuseEnv({NODE_ENV: "test"});// Setup Hook});// Return/Test hooks are used during test executionconst{useService, useHttp, useSpy}=hooks;test("should work",()=>{constservice=useService(UserService);// Return Hookconst{get}=useHttp();// Return Hookconstspy=useSpy(EmailService,"sendEmail");// Return Hook});- To implement custom hooks or extend the framework, refer to the Creating Custom Hooks documentation.
- For a concrete example of extension, refer to the node:test extension documentation.
MIT License - see LICENSE file for details.