Testomatio Editor Blocks

Custom BlockNote blocks, schema, and Markdown conversion helpers for Testomatio-style test cases and steps. The repository bundles two things:

• A Vite playground (npm run dev) for trying the blocks in isolation.
• A publishable package (npm run build:package) that writes the distributable files to package/.

Prerequisites

• Node.js 20+
• npm 9+

Install once after cloning:

npm install

Running The UI

Start the Vite dev server:

npm run dev

The app defaults to http://localhost:5173. Paste Markdown (including tables or step blocks) directly into the editor to see it converted into structured blocks, while the right-hand panels display the Markdown and block JSON previews.

Building the Package

Create the publishable bundle (JavaScript, type declarations, and stylesheet) by running:

npm run build:package

The compiled files land in package/:

• package/index.js and package/index.d.ts export the schema plus converters.
• package/editor/... contains the underlying source hierarchy for easier debugging.
• package/styles.css ships all required styles for the blocks.

Running npm run build will also invoke Vite and place the playground site in dist/, which you can upload to Cloudflare Pages if you want a hosted demo.

Using Inside Any BlockNote Editor

1. Install

   Add testomatio-editor-blocks alongside the BlockNote packages you already use:

   npm install testomatio-editor-blocks @blocknote/react @blocknote/core

   (If you are working locally before publishing, use npm install ../path/to/testomatio-editor-blocks --save.)

2. Load the schema and helpers

import { BlockNoteView } from "@blocknote/mantine";
import { useCreateBlockNote, useEditorChange } from "@blocknote/react";
import {
  customSchema,
  markdownToBlocks,
  blocksToMarkdown,
  testomatioEditorClassName,
} from "testomatio-editor-blocks";
import "testomatio-editor-blocks/styles.css";

const editor = useCreateBlockNote({
  schema: customSchema,
  pasteHandler: ({ event, editor, defaultPasteHandler }) => {
    const text = event.clipboardData?.getData("text/plain") ?? "";
    if (!text.trim()) {
      return defaultPasteHandler();
    }
    try {
      const blocks = markdownToBlocks(text);
      editor.insertBlocks(blocks);
      return true;
    } catch {
      return defaultPasteHandler();
    }
  },
});

useEditorChange((instance) => {
  const markdown = blocksToMarkdown(instance.document);
  // Persist markdown to your backend or trigger app logic.
  console.log(markdown);
}, editor);

return (
  <BlockNoteView
    editor={editor}
    className={testomatioEditorClassName}
    slashMenu={false}
  />
);

3. Work with Markdown

• markdownToBlocks(markdown: string) converts Testomatio Markdown into BlockNote block definitions ready for insertion.
• blocksToMarkdown(blocks) serialises editor content back into Markdown for storing or syncing.
• testomatioEditorClassName gives you the markdown wrapper class so the editor inherits the same Tailwind typography styles as your read-only view.

4. Blocks Available

   • testStep: inline WYSIWYG inputs for Step Title, Data, and Expected Result with bold/italic/underline formatting/images.
   • snippet: dropdown to pick a reusable snippet and editable body (no formatting buttons).

5. Spellcheck

   Step and snippet fields inherit the browser's spellcheck setting from the editor container, so it is enabled by default. To turn it off for the whole editor (paragraphs and steps), set spellcheck="false" on any wrapper around BlockNoteView.

Test and Suite Header

<!-- test --> and <!-- suite --> comments render as a card that folds open into their fields. Shut, it shows the id, the first filled field and how many more. The + button adds a field from getMetaFieldSuggestions. The card is read-only when the editor is not editable.

The same card is exported for read-only views outside the editor:

import { TestMetaCard } from "testomatio-editor-blocks";

<TestMetaCard kind="test" fields={[{ key: "id", value: "@T1234abcd" }]} onChange={() => {}} readOnly />

Theming

Every color, font and size comes from a --tme-* token. Defaults are the Testomat.io look. Set the tokens on any ancestor of the editor (or :root) to restyle it. Dark values switch on html.dark.

Token	Default (light)	Used for
--tme-font-sans / --tme-font-mono	Inter / system mono	Text / ids
--tme-text-size / --tme-leading	14px / 20px	Step fields
--tme-h1 … --tme-h6	22 / 20 / 18 / 16 / 14 / 14px	Headings
--tme-fg	#262626	Text
--tme-fg-strong / --tme-fg-soft	#0a0a0a / #404040	Icons / step buttons
--tme-muted-fg / --tme-placeholder	#737373 / #a1a1a1	Labels / placeholders
--tme-border / --tme-border-strong	#e5e5e5 / #d4d4d4	Borders
--tme-surface / --tme-surface-hover	#fff / #fafafa	Popovers, menus
--tme-muted	slate 5%	Soft fills
--tme-primary / --tme-ring	#4f46e5 / its 25%	Focus, open card
--tme-link / --tme-code / --tme-danger	indigo / amber / red	Links / code / remove
--tme-tooltip-bg / --tme-tooltip-fg	#0a0a0a / #fafafa	Tooltips
--tme-shadow / --tme-radius	12% black / 8px	Popovers / corners
--tme-meta-bg / --tme-meta-border / --tme-meta-border-open	muted / border / primary 50%	Test and suite header
--tme-meta-gap	2rem	Space above each test

Step and snippet blocks also keep their older --step-* and --snippet-* variables.

.my-editor {
  --tme-font-sans: var(--font-sans);
  --tme-fg: var(--foreground);
  --tme-primary: var(--primary);
}

Headless Parser

testomatio-editor-blocks/markdown holds the Markdown parser and serializer without React, BlockNote or a DOM, so a server can read test files with the same rules as the editor.

import { parseTestDocument, metaFieldValue, splitTags } from "testomatio-editor-blocks/markdown";

for (const section of parseTestDocument(markdown)) {
  // section.meta: { kind: "test" | "suite", fields, inline } | null
  // section.start / bodyStart / end: 0-based lines, end exclusive
  // section.heading: the first # or ## heading; section.steps: { title, data, expected }
  const id = metaFieldValue(section.meta, "id");
  const { title, tags } = splitTags(section.heading?.text ?? "");
}

It also exports markdownToBlocks, blocksToMarkdown, scanMarkdownBlocks (blocks with their source lines), isStepsHeading and getMetaFieldSuggestions.

Step Autocomplete & Image Upload Hooks

Configure everything via JS—no React providers required:

import {
  customSchema,
  setStepsFetcher,
} from "testomatio-editor-blocks";
import { setSnippetFetcher } from "testomatio-editor-blocks/snippets";

// Step suggestions (fetch or return an array of { id, title, ... })
setStepsFetcher(async () => {
  const res = await fetch("https://api.testomatio.com/v1/steps");
  return res.json();
});

setSnippetFetcher(async () => {
  const res = await fetch("https://api.testomatio.com/v1/snippets");
  return res.json();
});

// Image upload uses BlockNote's `uploadFile` handler you pass to `useCreateBlockNote`.
// No extra setup is required for step/snippet fields.

For snippets, provide a suggestions fetcher that returns { id, title, body, ... } or a JSON:API document and map it with setSnippetFetcher. Selecting a snippet fills its body; Markdown is wrapped with <!-- begin snippet #id --> ... <!-- end snippet #id -->.

Step suggestions accept either an array of { id, title, ... } or the JSON:API shape:

{
  "data": [
    {
      "id": "145",
      "type": "step",
      "attributes": {
        "title": "Donec placerat, dui vitae",
        "description": null,
        "kind": "manual",
        "labels": [],
        "keywords": [],
        "usage-count": 23,
        "comments-count": 0,
        "is-snippet": null
      }
    }
  ]
}

When a user types in Step Title, autocomplete filters these titles; Tab/Enter/Ctrl/Cmd+Space or the ⌄ button will insert the selection.

To stop suggestions from popping up while typing, set data-step-autocomplete="false" on any ancestor of the editor (for example the element the editor is mounted into). The "Show suggestions" button and Ctrl/Cmd+Space still open the list. The attribute is read on every edit, so toggling it takes effect immediately; isStepAutocompleteOnTypeEnabled(element) exposes the same check.

Running Tests

Vitest covers the Markdown/block converter. Run the suite with:

npm run test:run

Use npm run test if you prefer the interactive watcher.