Bedrock Test Framework

raw JSON →
6.1.0 verified Thu Apr 23 auth: no javascript

bedrock-test is a JavaScript testing utility for the Bedrock modular web application framework. It provides a structured approach for setting up and running tests, leveraging Mocha for backend unit tests and Karma (formerly Protractor, updated in search results to Karma) for frontend testing. The package, currently at version 6.1.0, is part of the Digital Bazaar Bedrock ecosystem, indicating its release cadence is likely tied to the development of the main Bedrock framework. Key differentiators include its ability to create self-contained test environments for individual modules, manage configuration overrides (e.g., `config.test.js` overriding `config.js`), and facilitate the inclusion of helper functions and mock data for comprehensive testing scenarios. It aims to simplify complex testing setups within the Bedrock architecture by defining how test files are loaded and executed, supporting a modular and independent testing approach for Bedrock-based projects.

Common errors

error Error: Cannot find module 'bedrock-test' ↓
cause The `bedrock-test` package or its dependencies were not properly installed or are not resolvable in the current environment.
fix
Ensure 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.
error ReferenceError: bedrock is not defined ↓
cause 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.
fix
Ensure 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.
error Mocha tests are not running or only a subset of tests are executing. ↓
cause The `config.mocha.tests` array in `test.config.js` or equivalent configuration is incorrectly populated, or the specified test file paths are invalid.
fix
Verify 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.
error TypeError: Cannot read properties of undefined (reading 'on') for bedrock.events ↓
cause 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.
fix
Ensure 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.

Warnings

breaking The 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. ↓
fix Upgrade Node.js to at least v10.12.0 or newer for `bedrock@3.x` and later. Ensure your `package.json` engines field reflects this.
breaking As 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. ↓
fix Refactor `bedrock.start()` calls from `bedrock.start(callback)` to `await bedrock.start()` or `bedrock.start().then(...)`.
breaking The 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. ↓
fix Migrate 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.
gotcha When 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. ↓
fix Be explicit about configuration overrides in `config.test.js`. Review the Bedrock configuration loading order to understand which settings take precedence during test runs.
gotcha The `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). ↓
fix For 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.

Install

npm install bedrock-test
yarn add bedrock-test
pnpm add bedrock-test

Imports

Quickstart

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).');
  });
});
last verified Thu Apr 23
next check Wed Jul 22