Testing & Harnesses¶

What each test covers, how to run them, and how to add your own.

Test suites¶

Void has three verification layers that run in CI and locally:

All three must pass before opening a PR.

JS smoke tests (npm test)¶

File: tests/void.test.js (1412 lines)

The test stubs a minimal DOM/browser environment and loads the theme's void.js IIFE to verify the boot sequence runs without throwing. It then exercises specific features.

What each check covers¶

How to run¶

npm test

Output ends with All JS smoke checks passed (55 checks). or reports failures with line numbers.

How to add a test¶

1. Find the right insertion point (tests are numbered sequentially).
2. Use bootIIFE() to boot void.js with your config fixture:

const myBoot = bootIIFE({
  location: { origin: "https://x", pathname: "/page/", search: "", href: "https://x/page/", hash: "" },
  config: {
    base: "/",
    components: { /* your component config */ },
    content: {},
    void_search: { enabled: false },
    translations: {},
  },
  searchDom: null,
  stored: {},   // pre-populate localStorage keys here
})

1. Assert with check("description", booleanCondition).

Fixture helpers:

Pre-populating localStorage:

const myBoot = bootIIFE({
  stored: { "void-notes": JSON.stringify([{ id: "x", url: "/", ts: Date.now() }]) },
  // ...
})

Accessing the search Worker shim:

The Worker shim in the test harness fires results when msg.query is sent. The results are rendered into _searchDom.list._children as row nodes.

Doc lint (tools/check_docs.py)¶

File: tools/check_docs.py

How to run¶

python tools/check_docs.py

All 8 checks print [ ok ]. Failures print [FAIL] with the file and reason.

How to add a check¶

1. Open tools/check_docs.py.
2. Add a new function following the pattern of existing checks.
3. Register it in the checks list at the bottom.
4. The check runs against all files in docs/ and mkdocs.yml.

Strict build¶

mkdocs build --strict --clean

Zero warnings means the build is clean. Any warning is treated as an error.

CI workflows¶

Recipes¶

Adding a new init function to void.js¶

1. Write the function in void.js.
2. Call it from the boot sequence (the IIFE at the bottom).
3. Add a smoke test that boots with the relevant config and asserts the function ran.
4. Run npm test to confirm.

Adding a new config key¶

1. Add the key to _VOID_DEFAULT_* in void/plugins/void_plugin.py.
2. Add it to _VOID_TOKEN_MAP for the doc lint check.
3. Run python tools/emit_config_reference.py to regenerate the reference page.
4. Document the key in the relevant docs page.
5. Run python tools/check_docs.py to confirm the key is recognized.

Back to README