acquit-require

0.1.1 verified Sat Apr 25 auth: no javascript maintenance

Utility to extract example code from Mocha test files and embed it into markdown, HTML, or other documentation formats via placeholder directives like `[require:testName]`. Version 0.1.1 is the latest stable release, last updated in 2016 with no active development. Requires peer dependency `acquit >= 0.4.0`. Differentiates from generic doc generators by providing a simple, test‑driven approach to keep documentation in sync with actual tests.

Common errors

error Cannot find module 'acquit-require' ↓

cause Package not installed or missing peer dependency 'acquit'.

fix

Run: npm install acquit-require acquit

error transform is not a function ↓

cause Importing default instead of named export.

fix

Change to: import { transform } from 'acquit-require'

error findTest is not a function ↓

cause Importing incorrectly, e.g. as default.

fix

Use named import: import { findTest } from 'acquit-require'

Warnings

gotcha Placeholder matching is case‑insensitive and only matches the first test whose full name contains the placeholder text as a substring. This can lead to unexpected replacements if test names overlap. ↓

fix Use unique placeholder names, e.g. [require:unique-test-title].

gotcha Only tests written with the standard Mocha `describe/it` pattern are supported. Tests using `context`, `specify`, or arrow functions without a `function()` keyword may not be matched. ↓

fix Write tests using `describe('...', function() { it('...', function() { ... }); });`

deprecated Package has not been updated since 2016. It may not work with newer versions of Mocha or Node.js. ↓

fix Consider forking or using an alternative like 'code-docs-examples'. Test with your specific versions.

Install

npm install acquit-require

yarn add acquit-require

pnpm add acquit-require

Imports

transform

wrong

import acquitRequire from 'acquit-require'

correct

import { transform } from 'acquit-require'

Default import not supported; use named import.

findTest

wrong

const findTest = require('acquit-require').findTest

correct

import { findTest } from 'acquit-require'

CJS require is also correct, but ESM named import is preferred.

transform

wrong

const transform = require('acquit-require')

correct

const { transform } = require('acquit-require')

CommonJS destructuring required; default export does not exist.

Quickstart

Shows how to load a markdown template and test file, then use transform() to replace placeholders with matching Mocha test code.

import { transform, findTest } from 'acquit-require';
import { readFileSync, writeFileSync } from 'fs';

const article = readFileSync('./README.md', 'utf8');
const testCode = readFileSync('./test/example.test.js', 'utf8');

// Replace [require:...] placeholders with test source code
const output = transform(article, testCode);

// Write the new markdown with embedded examples
writeFileSync('./README.generated.md', output);

// Example placeholder: [require:my test]
// The function findTest can be used to locate a single test's body
const testBody = findTest('should add numbers', testCode);
console.log('Test source:', testBody);