@lando/leia

v2.0.0

Published

25 days ago

Runs tests cleverly hidden in documentation

0High
0Medium
0Low

lando leia mocha testing

Leia

Leia turns fenced commands in markdown into mocha tests. Keep runnable examples beside the prose they explain, then prove the documentation still tells the truth.

Runs on Node.js 24 or newer, or Bun with explicit invocation.

[!WARNING] Leia executes real commands that can change files, install software, or alter your machine. Prefer ephemeral CI runners. Before running locally, read the scenarios and repository guidance; a temporary working directory does not isolate machine-wide changes.

Install

# add leia to your project's development dependencies.
npm install --save-dev @lando/leia

Usage

Write your first scenario

Save this as quickstart.md:

# Leia quickstart

## Testing

```sh
# should print a greeting
echo "Hello from Leia"
```

The title names the suite, the Testing heading selects the commands, and each comment names a test. Blank lines separate tests. See scenario authoring for assertions, setup, and cleanup.

Run with the CLI

# run the locally installed leia without downloading another version.
npm exec --offline -- leia quickstart.md

Leia reports one passing test. A command that exits nonzero, cannot start, or exceeds its deadline fails the scenario.

# equivalent when leia is already on path, including inside an npm script.
leia quickstart.md

# quote globs so leia expands them; retry failed commands twice.
leia "docs/**/*.md" --retry 2

For Bun, define the project script, then run bun run leia quickstart.md. See the CLI guide for all options and environment defaults.

Run programmatically

Save as test-docs.mjs and run with node test-docs.mjs:

import Leia from '@lando/leia';

const leia = new Leia();
// compile the same markdown scenario.
const files = leia.find(['quickstart.md']);
const sources = leia.parse(files, { moduleFormat: 'esm' });
const harnesses = leia.generate(sources);
const runner = await leia.runAsync(harnesses);

// return a failing exit status when any test fails.
runner.run((failures) => {
  process.exitCode = failures ? 1 : 0;
});

The API reference includes CommonJS usage, TypeScript declarations, and every supported export.

Run in GitHub Actions

Commit quickstart.md, package.json, and package-lock.json, then save this workflow as .github/workflows/leia.yml:

name: Leia
on:
  pull_request:
permissions:
  contents: read
jobs:
  scenarios:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: '24'
      - run: npm ci
      - run: npm exec --offline -- leia quickstart.md

See GitHub Actions for a platform matrix and scenario prerequisites.

Use with an agent

Install the Leia plugin for Codex or OpenClaw, then ask:

Use Leia to find a useful missing scenario in this project, implement it, and run it.

The skill can also run and diagnose existing tests or configure their GitHub Actions matrix. See plugin installation for both hosts, prerequisites, and example requests.

Development

Leia uses pinned Bun tooling and TypeScript source. CONTRIBUTING covers setup, validation, builds, and releases.

Issues, questions, and support

Leia 1.x is unsupported. Upgrade to 2.x; see the migration notes.

Join the Lando Slack community for community help. Report bugs and request features through the issue queue.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme