wasm-rquickjs-cli 0.4.8

Tool for wrapping JavaScript modules as WebAssembly components using the QuickJS engine
# Node Modules App Tests

This runtime suite tests unbundled npm apps with real `node_modules` attached to the component filesystem. It is intentionally separate from `tests/libraries/`, which tests Rollup-bundled package usage and records human compatibility notes in `tests/libraries/libraries.md`.

## What This Suite Covers

Use node modules app tests for:

- Node-style package resolution from a filesystem `node_modules` tree
- package `exports` / `imports`, including wildcard patterns
- CJS/ESM interop and same-process `require(esm)` behavior
- package graphs that behave differently when bundled versus installed
- small smoke tests for pure-JS packages that should run without subprocesses or live services

Do not use node modules app tests for native `.node` bindings, packages that load WASM artifacts, subprocess-heavy behavior, or live network/cloud service calls.

## Source Of Truth

`tests/node_modules_apps/config.jsonc` is the source of truth. Runtime tests in `tests/runtime/node_modules_apps.rs` are generated from this config.

Each app has this shape:

```jsonc
{
  "apps": {
    "example-app": {
      "category": "runnable",
      "reason": "Short suite description",
      "tests": {
        "test-01-basic.mjs": "Coverage summary shown in the report"
      }
    }
  }
}
```

Test entries can also be objects when a per-test category, reason, or timeout is needed:

```jsonc
"test-02-edge.cjs": {
  "category": "known-gap",
  "coverage": "Coverage summary",
  "reason": "Specific gap explanation",
  "timeout": 180
}
```

Supported categories are:

| Category | Runner behavior | Report meaning |
|---|---|---|
| `runnable` | Runs in `cargo test --test runtime` | Expected to pass |
| `known-gap` | Ignored | Public behavior is in scope but missing/incomplete |
| `deferred` | Ignored | Intentionally outside this node modules app suite's current scope |

## App Directory Layout

Each app lives under `tests/node_modules_apps/apps/<app-name>/`:

```text
tests/node_modules_apps/apps/example-app/
├── package.json
├── run-node.mjs
├── test-01-basic.mjs
└── test-02-edge.cjs
```

`package.json` should pin direct dependency versions. The harness installs dependencies with:

```sh
npm ci --install-links --ignore-scripts --no-audit --no-fund
```

`run-node.mjs` should import or require the requested test file, call its exported `run()` function, print the returned result, and fail if it does not start with `PASS:`.

## Test Format

Each test file must export `run()` and return a `PASS:` string:

```js
import assert from 'node:assert';

export async function run() {
  assert.strictEqual(1 + 1, 2);
  return 'PASS: basic behavior works';
}
```

CommonJS tests can use `.cjs` and `module.exports.run = ...`.

## How Runtime Tests Run

For every runnable config entry, the harness:

1. Copies the app directory to a process-local installation template.
2. Runs `npm ci --install-links --ignore-scripts --no-audit --no-fund` once per
   app and test process.
3. Verifies the raw app test with host Node.js: `node run-node.mjs <test-file>`.
4. Copies the installed template into a fresh temporary directory and then into
   the WASI preopen as `/app`.
5. Runs `examples/runtime/node-modules-app-runner`, which imports or requires the test from `/app` and executes it against real `/app/node_modules`.

The installation-template cache only avoids repeating `npm ci` within one test
process. Each case still receives a fresh app directory, component instance,
WASI context, and JavaScript runtime.

## Commands

Node modules app tests are baselined against Node.js 22.14.0, matching CI and
the vendored Node.js compatibility suite. Use nvm before local runs:

```sh
source ~/.nvm/nvm.sh
nvm install
nvm use
node --version
```

Local runs accept Node.js 22.14.0 or newer patch/minor releases within major
22, but print a warning when the exact baseline differs because Node-baselined
fixtures can change across minor releases. CI sets
`NODE_MODULES_APP_STRICT_NODE_BASELINE=1`, which requires exactly Node.js
22.14.0.

Run the node modules app suite after skeleton changes:

```sh
./cleanup-skeleton.sh
cargo test --test runtime --features use-golem-wasmtime -- node_modules_app --nocapture
```

Run a narrower filter:

```sh
cargo test --test runtime --features use-golem-wasmtime -- node_modules_app__module_interop --nocapture
```

Run the CI-style node modules app group:

```sh
cargo test --test runtime --features use-golem-wasmtime -- ':tag:group9'
```

Node modules app tests run as runtime `group9` in CI. Regular runtime tests use `group1` through `group8`.

## Relationship To Rollup Library Tests

| Suite | Purpose | Execution |
|---|---|---|
| `tests/libraries/` | Documents package compatibility when bundled with Rollup like the Golem CLI pipeline | Manual/agent workflow using Rollup, generated wrapper crates, and `wasmtime run` |
| `tests/node_modules_apps/` | CI-enforced regression tests for unbundled apps with real filesystem `node_modules` | Rust runtime harness generated from `config.jsonc` |

The same npm package may be covered in both suites for different reasons. Rollup tests answer whether bundled usage works; node modules app tests answer whether Node-style installed package loading works.