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.
createBuilder, createTempDir
✓ import { createBuilder, createTempDir } from 'broccoli-test-helper';
✗ import createBuilder from 'broccoli-test-helper/createBuilder';
Primary named exports for ESM and TypeScript usage. Avoid deep imports unless explicitly documented.
helper object
✓ const helper = require('broccoli-test-helper');
const createBuilder = helper.createBuilder;
✗ const { createBuilder } = require('broccoli-test-helper');
While CommonJS destructuring `const { createBuilder } = require('broccoli-test-helper');` often works, the official examples show assigning the module to a variable and then accessing properties, which might be safer across module export configurations.
Types
✓ import type { Builder, TempDir } from 'broccoli-test-helper';
TypeScript types are shipped with the package for all primary exports.
This quickstart demonstrates how to use `broccoli-test-helper` to test a Broccoli plugin, covering initial builds, updates, removals, and verifying file changes and output using `async/await` and QUnit-style assertions. The `Herp2Derp` class serves as a placeholder for your actual Broccoli plugin under test.
import { createBuilder, createTempDir } from "broccoli-test-helper";
// This is a placeholder for your actual Broccoli plugin.
// In a real test, you would import and instantiate your plugin here.
class Herp2Derp {
private inputPath: string;
constructor(inputPath: string) { this.inputPath = inputPath; }
async build() { /* Your plugin's build logic would go here */ }
}
// Assuming QUnit is set up in your test environment.
// For demonstration, a minimal QUnit-like structure is implied.
// QUnit.module and QUnit.test are from the QUnit test framework.
// Replace with your preferred test framework (e.g., Mocha, Jest) setup.
const QUnit = {
module: (name: string, cb: Function) => { console.log(`Module: ${name}`); cb(); },
test: (name: string, cb: Function) => {
console.log(`Test: ${name}`);
const assert = { deepEqual: (actual: any, expected: any) => console.assert(JSON.stringify(actual) === JSON.stringify(expected), 'Assertion Failed') };
cb(assert);
}
};
QUnit.module("Herp2Derp Plugin Test", () => {
QUnit.test("should build and track changes correctly", async assert => {
const input = await createTempDir();
try {
const subject = new Herp2Derp(input.path()); // Instantiate your plugin with the temp input path
const output = createBuilder(subject);
try {
// INITIAL BUILD
input.write({
"a.herp": "A",
lib: {
"b.herp": "B",
"c.herp": "C"
}
});
await output.build();
assert.deepEqual(output.read(), {
"a.derp": "derp A!", // Assuming Herp2Derp transforms .herp to .derp
lib: {
"b.derp": "derp B!",
"c.derp": "derp C!"
}
});
assert.deepEqual(output.changes(), {
"a.derp": "create",
"lib/": "mkdir",
"lib/b.derp": "create",
"lib/c.derp": "create"
});
// UPDATE AND REMOVE
input.write({
"a.herp": "AA", // Change a file
lib: null // Remove a directory
});
await output.build();
assert.deepEqual(output.read(), {
"a.derp": "derp AA!"
});
assert.deepEqual(output.changes(), {
"lib/c.derp": "unlink",
"lib/b.derp": "unlink",
"lib/": "rmdir",
"a.derp": "change"
});
// NOOP BUILD
await output.build();
assert.deepEqual(output.changes(), {}); // No changes expected
} finally {
await output.dispose(); // Clean up output directory
}
} finally {
await input.dispose(); // Clean up input directory
}
});
});
Errors
Common errors & fixes
TypeError: helper.createBuilder is not a function
Attempting to access `createBuilder` from a CommonJS `require` call where `helper` might be `undefined` or the export structure is not as expected for direct property access, or trying to destructure incorrectly.
fixEnsure `require('broccoli-test-helper')` successfully returns an object. The recommended CommonJS usage shown in examples is `const helper = require('broccoli-test-helper'); const createBuilder = helper.createBuilder;`. SyntaxError: await is only valid in async function
The `await` keyword is used outside of an `async` function. This typically happens when test callbacks are not marked as `async` or when `async/await` is used in an environment without proper transpilation or native support.
fixMark your test callback function as `async`, e.g., `QUnit.test('my test', async assert => { /* ... */ });` or `it('should build', async function() { /* ... */ });`. If on older Node.js, ensure transpilation is in place. Audit
Dependencies
No dependency data recorded yet.