Registry / testing / prosemirror-test-builder

prosemirror-test-builder

library1.1.1jsnpmunverified

`prosemirror-test-builder` is a specialized utility package designed to simplify the programmatic construction of ProseMirror documents for testing purposes. It provides a comprehensive set of helper functions, often named after common HTML tags like `p`, `h1`, `ul`, and `li`, allowing developers to intuitively build nodes and marks within a default, feature-rich ProseMirror schema. The package also includes a `builders` utility for generating these helpers based on a custom schema. A key differentiating feature is its integrated tag system, which enables developers to embed named markers within document content strings (e.g., `<a>`) to precisely track and retrieve cursor positions within the generated document, significantly streamlining assertion logic in tests. This current stable version is 1.1.1, and its release cadence is generally aligned with the broader ProseMirror ecosystem, ensuring compatibility for test setups.

testing

npm install prosemirror-test-builder

github ↗package ↗

INSTALL

IMPORT

SIG · PROSEMIRROR-TEST-B

prosemirror-test-builder

testingjavascriptv1.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

doc

✓ import { doc, p } from 'prosemirror-test-builder'

✗ const { doc, p } = require('prosemirror-test-builder')

Named exports are standard. CommonJS `require` syntax might lead to issues in ESM-first environments or bundlers if not correctly configured for interoperability. The `doc` builder creates the root ProseMirror document.

schema

✓ import { schema } from 'prosemirror-test-builder'

Imports the default test schema used by the top-level builders (e.g., `p`, `h1`). Useful for inspecting or extending.

builders

✓ import { builders } from 'prosemirror-test-builder/dist/build'

✗ import { builders } from 'prosemirror-test-builder'

The `builders` factory function, used to create builders for a *custom* ProseMirror schema, resides in a specific subpath (`dist/build`) rather than the main entry point. Importing it from the root package might result in `undefined` or a module not found error.

This quickstart demonstrates building a ProseMirror document using both the default builders and the custom `builders` factory function, along with accessing the embedded tag positions.

import { doc, p, strong, ul, li, schema } from 'prosemirror-test-builder'; import { Schema } from 'prosemirror-model'; // 1. Using the default builders and tag system const defaultTestDoc = doc( p('Hello, ', strong('world<a>! Here is some text.')), ul( li('Item one<b>'), li('Item two'), li('Item three<c> and more') ) ); console.log('--- Default Schema Document ---'); console.log('Document JSON:', defaultTestDoc.toJSON()); console.log('Tag "a" position:', defaultTestDoc.tag.a); // Cursor position after 'world' console.log('Tag "b" position:', defaultTestDoc.tag.b); // Cursor position after 'Item one' console.log('Tag "c" position:', defaultTestDoc.tag.c); // Cursor position after 'Item three' // 2. Creating builders for a custom schema const myCustomSchema = new Schema({ nodes: { doc: { content: "custom_paragraph+" }, custom_paragraph: { content: "text*", group: "block" }, text: { inline: true } }, marks: {} }); import { builders } from 'prosemirror-test-builder/dist/build'; const { doc: customDoc, custom_paragraph: customParagraph } = builders(myCustomSchema); const customTestDoc = customDoc( customParagraph('This is custom content with a <d>tag.') ); console.log('\n--- Custom Schema Document ---'); console.log('Custom Document JSON:', customTestDoc.toJSON()); console.log('Custom Tag "d" position:', customTestDoc.tag.d); // 3. Accessing the default schema directly console.log('\n--- Default Test Schema Info ---'); console.log('Default schema node types:', Object.keys(schema.nodes));

Debug

Known issues

breakingAs a testing utility tightly coupled with `prosemirror-model`, breaking changes in `prosemirror-model` (especially to schema definitions or node/mark APIs) will likely necessitate updating `prosemirror-test-builder` or adapting test code. Always align major versions with your `prosemirror-model` dependency.

fix

Ensure `prosemirror-test-builder`'s major version is compatible with your `prosemirror-model` version. Consult the release notes for both packages.

affects: >=1.0.0

gotchaThe `builders` function for custom schemas is located at a subpath (`prosemirror-test-builder/dist/build`). Importing it from the root package (`prosemirror-test-builder`) will fail.

fix

Correct the import path to `import { builders } from 'prosemirror-test-builder/dist/build';`

affects: >=1.0.0

gotchaThe tag system (`<a>`, `<b>`) only places markers in the `.tag` property of the resulting `Node` object and does not insert visible text or special nodes into the ProseMirror document content itself. Misinterpreting this can lead to incorrect document structure assumptions.

fix

Remember that `doc(p('Text<a>'))` results in a paragraph with 'Text', and `doc.tag.a` will hold the position *after* 'Text', not 'Text<a>'.

affects: >=1.0.0

gotchaWhen using `require()` in CommonJS modules or older Node.js environments, directly destructuring named exports like `const { p } = require('prosemirror-test-builder');` might result in `undefined` if the package primarily uses ESM exports without proper transpilation or CommonJS fallback support.

fix

Prefer `import { p } from 'prosemirror-test-builder';` for ESM. For CommonJS, if issues arise, try `const prosemirrorTestBuilder = require('prosemirror-test-builder'); const p = prosemirrorTestBuilder.p;` or ensure your build setup correctly handles ESM-CJS interop.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: (0 , _prosemirrorTestBuilder.p) is not a function

Attempting to use ES module named exports (`p`) via CommonJS `require()` syntax in an environment where direct destructuring isn't supported, or the bundler/runtime is misinterpreting the module type.

fix

Use ES module `import { p } from 'prosemirror-test-builder';` if in an ESM context, or ensure correct CommonJS interop. If forced to use `require`, try `const pkg = require('prosemirror-test-builder'); const p = pkg.p;`

TypeError: Cannot read properties of undefined (reading 'a')

Accessing a tag property (e.g., `doc.tag.a`) when no tag named 'a' was placed in the document or when `doc` itself is not a valid ProseMirror `Node` instance (e.g., if the builder call failed).

fix

Verify that the tag (`<a>`) is correctly placed within the string arguments of your builders and that the builder functions themselves are returning valid `Node` objects. Tags are stored on the root node or any node that directly contains them.

Error: Unknown node type: custom_paragraph (or similar for marks/nodes)

Attempting to use builders (e.g., `customParagraph`) that were created for a custom schema without passing that schema to the `builders` factory, or using the default builders (e.g., `p`) with a document that expects a different schema.

fix

If using a custom schema, ensure you use `import { builders } from 'prosemirror-test-builder/dist/build';` and then create your schema-specific builders: `const { custom_paragraph } = builders(myCustomSchema);`. Do not mix builders from different schemas without explicit schema conversion or mapping.

Upgrade

Version history

1.1.1latest on npm

Audit

Dependencies

prosemirror-modelrequiredProvides core ProseMirror `Schema`, `Node`, and `Mark` types and functionalities essential for building and manipulating documents. This package builds on top of these primitives.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/prosemirror/prosemirror-test-builder ↗

packagehttps://www.npmjs.com/package/prosemirror-test-builder ↗