Testing and doctest workflow

対象実装: このドキュメントは NEPLg2.0（現行 nepl-core）のテストワークフローを記述する。
NEPLg3 では tests-g3/ を新設して並行開発し、Stage 6 で tests/ と切り替える計画。
詳細は migration/index.md を参照。

This document describes the current NEPLg2 test workflow and where each kind of
test lives.

Overview

The repository currently uses three main layers of verification:

  • Rust-side compiler tests under nepl-core/tests/
  • doctests and focused behavioral tests under tests/, tutorials/, and stdlib/
  • end-to-end sample regressions such as nodesrc/tui_regression.js

The main day-to-day workflow for stdlib reboot work is based on nodesrc/.

Where tests live

tests/compiler/*.n.md

Compiler-facing regression cases.

  • parse / name resolution / typecheck / diagnostics
  • compile_fail cases with diag_code
  • target-specific behavior such as LLVM / WASM / WASIX checks

tests/stdlib/*.n.md

User-facing stdlib behavior and reboot migration regressions.

  • facade behavior
  • end-user API expectations
  • focused reproductions for bugs found during reboot work

These are the main place to add a regression when an API contract breaks.

stdlib/tests/*.n.md

Library-adjacent requirement and support tests that are still useful as
standalone fixtures.

These are kept when they are still meaningful, but new public-facing behavior
checks should usually go to tests/stdlib/*.n.md.

stdlib/**/*.nepl

Doc comments may contain neplg2:test doctests.

Use these for:

  • small usage examples
  • contract examples that should stay close to the definition

Do not use doc comments for large regression matrices or heavy edge-case suites.
Those belong in tests/.

tutorials/**/*.n.md

Tutorials also contain doctests.

These act as executable documentation and should reflect the current stdlib
layout and API style.

Tutorial documents should also stay UTF-8 without BOM so ruby annotations and
Japanese text render consistently across the CLI, generated HTML, and the web
playground.

Runtime model used by nodesrc

nodesrc/run_test.js chooses the execution path from #target:

  • #target wasi / wasip1-style cases run through Node's WASI support
  • #target wasix cases first try wasmer run; when wasmer is not installed, or when Wasmer lacks the wasix_32v1.tty_get / tty_set imports, the runner falls back to Node's WASI support with minimal WASIX TTY host imports

This matters for features such as TUI, which require WASIX imports and cannot be
executed by the preview1-only Node WASI runtime without those fallback imports.
The runner prepares a tmp/ scratch directory inside each preopen root before
execution. File-write doctests can use tmp/... paths without depending on an
untracked repository directory being present in a clean checkout.

You can override the wasmer binary with:

WASMER_BIN=/path/to/wasmer node nodesrc/run_doctest.js -i tests/stdlib/features_tui.n.md -n 1

Output expectations

nodesrc/tests.js and run_doctest.js both understand doctest metadata such as:

  • stdin:
  • stdout:
  • stderr:
  • ret:
  • diag_code:

If a doctest includes stdout: or stderr:, nodesrc/tests.js checks those
expectations by default. --assert-io is optional and only makes the intent
explicit.

std/test

std/test is the basic assertion module used in NEPL-side tests.

Typical helpers include:

  • assert
  • assert_eq_i32
  • assert_str_eq
  • test_checked
  • test_fail

Use the smallest assertion that makes failures obvious.

Playground editor CLI tests

tests/playground_editor/ is reserved for browser-free editor verification.

  • Each case lives under its own directory.
  • The standard fixture shape is source.nepl, commands.json, and expected.json.
  • Analysis-model cases use source.nepl, analysis.json, requests.json, and expected.json.
  • commands.json may contain pure editor commands plus keyboard_event steps for shortcut coverage.
  • Cursor/navigation cases should prefer pure commands such as move_cursor, move_cursor_vertical, move_cursor_line_boundary, and move_cursor_page so they stay runnable without DOM events.
  • requests.json can verify update_payload, token_insight, hover, definition, and occurrences without starting a browser.
  • The formal entrypoint is nodesrc/cli.js --playground-editor-tests, which writes an aggregate JSON summary.
  • nodesrc/playground_editor_test_runner.js remains the lower-level runner used by the CLI path.
  • Current coverage includes shortcut/history cases, text insert/delete, left-right movement, up-down movement, Home/End, PageUp/PageDown, and analysis snapshots.
  • Terminal/process regressions are covered separately by nodesrc/playground_shell_worker_test_runner.js, which verifies that compile/run requests stay on the worker side and that compile outputs/stdout are routed back correctly.

Current guidance

  • Prefer tests/stdlib/*.n.md for new reboot regressions.
  • Prefer stdlib/**/*.nepl doctests for short examples attached to one API.
  • Use run_doctest.js for the fastest reproduction loop.
  • Use nodesrc/tui_regression.js for TUI end-to-end checks after WASIX-facing changes.
  • Keep docs, doctests, and implementation in sync in the same change.
On this page