Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
bedrockTest
✓ import * as bedrockTest from 'bedrock-test';
✗ const bedrockTest = require('bedrock-test');
While the README examples primarily use CommonJS `require`, modern Bedrock applications increasingly utilize ES Modules. Import as a namespace for direct utility access. The package also often works by augmenting the global `bedrock` object on `require`.
bedrock.events
✓ import * as bedrock from '@bedrock/core';
bedrock.events.on('bedrock.test.configure', configureTest);
✗ const bedrock = require('bedrock');
bedrock.events.on('bedrock.test.configure', configureTest);
bedrock-test integrates deeply with the main `bedrock` framework's event system. Direct imports from `@bedrock/core` are common for core framework interactions. The `bedrock.test.configure` event is emitted by `bedrock-test`.
config.mocha.tests
✓ // In test.config.js
import path from 'path';
import { fileURLToPath } from 'url';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
config.mocha.tests.push(path.join(__dirname, 'mocha'));
✗ config.mocha.tests.push(path.join(__dirname, 'mocha'));
Configuration for Mocha test files is often managed via `config.mocha.tests` within `test.config.js`. When using ESM, `__dirname` needs to be polyfilled. In older CJS setups, `__dirname` is globally available.
This quickstart demonstrates how to set up a `bedrock-test` environment, configure it to load Mocha test files, handle mock data, and execute a basic Mocha test suite within the Bedrock framework. It also illustrates the configuration override pattern.
import path from 'path';
import { fileURLToPath } from 'url';
import * as bedrock from '@bedrock/core';
import chai from 'chai';
import { describe, it, before, after } from 'mocha';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const expect = chai.expect;
// Minimal Bedrock setup (typically done in a main test.js file)
bedrock.events.on('bedrock.test.configure', configureTest);
bedrock.events.on('bedrock.test.run', () => console.log('Tests starting...'));
bedrock.start().catch(err => {
console.error('Bedrock failed to start:', err);
process.exit(1);
});
function configureTest(config) {
// Load module-specific test configuration
config.mocha = config.mocha || {};
config.mocha.tests = config.mocha.tests || [];
// Example: push a directory containing Mocha test files
config.mocha.tests.push(path.join(__dirname, 'mocha'));
// Example: configuration override (gotcha #1)
config.someFeature = { enabled: false };
config.test = { someFeature: { enabled: true } }; // This will override config.someFeature
console.log('Bedrock test configuration applied.');
}
// Example mock data (mock.data.js)
const mockData = {
user: { id: 'user123', name: 'Test User' },
product: { id: 'prod456', name: 'Test Product' }
};
// Example Mocha test file (e.g., test/mocha/00-user-api.js)
describe('User API', () => {
let db = [];
before(async () => {
// Simulate loading mock data into a 'database'
db.push(mockData.user);
console.log('Setup: User added to mock DB.');
});
after(() => {
// Clean up between tests or after all tests
db = [];
console.log('Cleanup: Mock DB cleared.');
});
it('should retrieve the test user', () => {
const user = db.find(item => item.id === 'user123');
expect(user).to.exist;
expect(user.name).to.equal('Test User');
console.log('Test: User retrieved successfully.');
});
it('should not find a non-existent user', () => {
const user = db.find(item => item.id === 'nonexistent');
expect(user).to.not.exist;
console.log('Test: Non-existent user not found (as expected).');
});
});
bedrock-test --version
Debug
Known issues
breakingThe Bedrock framework (and by extension `bedrock-test`) updated its Node.js requirement to v10.12.0 in `bedrock@3.0.0`, and later to `>=8` in `bedrock@1.18.0` due to async/await usage. Ensure your environment meets these minimums, as older Node.js versions will cause failures.fixUpgrade Node.js to at least v10.12.0 or newer for `bedrock@3.x` and later. Ensure your `package.json` engines field reflects this.
affects: <3.0.0
breakingAs of `bedrock@3.0.0`, `bedrock.start()` now returns a Promise instead of using a callback. Code relying on the callback pattern for `bedrock.start()` must be updated to use `async/await` or `.then/.catch` for proper asynchronous handling.fixRefactor `bedrock.start()` calls from `bedrock.start(callback)` to `await bedrock.start()` or `bedrock.start().then(...)`.
affects: >=3.0.0
breakingThe core `bedrock` framework removed its internal Mocha unit test framework in `bedrock@2.0.0`, relocating all testing functionality entirely to the `bedrock-test` module at version `bedrock-test@4`. Direct usage of internal `bedrock` testing utilities is no longer supported.fixMigrate all testing logic to use the `bedrock-test` module (version 4 and above) and its exposed APIs. Ensure `bedrock-test` is installed and configured correctly.
affects: >=2.0.0 of bedrock
gotchaWhen configuring tests, `config.test.js` files are loaded after `config.js` files. This means that any settings defined in `config.test.js` will override identical settings in `config.js`. This is by design for test environments but can lead to unexpected behavior if not understood.fixBe explicit about configuration overrides in `config.test.js`. Review the Bedrock configuration loading order to understand which settings take precedence during test runs.
affects: >=1.0.0
gotchaThe `README` excerpts show `require()` syntax (CommonJS). While `bedrock-test` itself might still support CJS, modern Node.js and Bedrock applications increasingly use ES Modules (`import`/`export`). Mixing CJS `require` with ESM `import` can lead to module resolution issues or unexpected behavior without proper configuration (e.g., `"type": "module"` in `package.json` and correct file extensions).fixFor new projects, adopt ESM `import` statements and configure Node.js for ESM. For existing CJS projects, ensure consistency. If migrating, consider tools like `esm` or updating your build process.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Cannot find module 'bedrock-test'
The `bedrock-test` package or its dependencies were not properly installed or are not resolvable in the current environment.
fixEnsure `bedrock-test` is listed in your `package.json` and run `npm install` (or `yarn add bedrock-test`). Verify that the module resolution path is correct if using custom configurations.
ReferenceError: bedrock is not defined
The core `bedrock` framework has not been loaded or initialized before `bedrock-test` attempts to interact with it, specifically its event system or global configuration object.
fixEnsure `require('@bedrock/core')` or `import '@bedrock/core';` is executed early in your test setup process, typically in the main `test.js` file, before `bedrock-test` is loaded. `bedrock.start()` should also be called. Mocha tests are not running or only a subset of tests are executing.
The `config.mocha.tests` array in `test.config.js` or equivalent configuration is incorrectly populated, or the specified test file paths are invalid.
fixVerify that `config.mocha.tests` correctly pushes the directories or specific file paths where your Mocha test files (`.js`) are located. Ensure the paths are absolute and correct, especially when using `path.join` and `__dirname`.
TypeError: Cannot read properties of undefined (reading 'on') for bedrock.events
The `bedrock` core module might not be fully initialized or `bedrock.events` is not available at the time of subscription. This often happens if the `bedrock` module is not correctly imported or if its initialization is deferred.
fixEnsure that `import * as bedrock from '@bedrock/core';` is at the top of your main test file and that any event subscriptions for `bedrock.events` occur after `bedrock` has been fully loaded. Consider `await bedrock.start()` to ensure the framework is ready.
Audit
Dependencies
bedrockrequiredPeer dependency for the core Bedrock framework, essential for its functionality and event system.