Testing

Deno has several test categories living in different places. Each suite has a different role and a different way to run it. This page is a map.

The test pyramid

graph TD
    subgraph Top["High-level"]
        WPT["Web Platform Tests<br/>tests/wpt/"]
        NodeCompat["Node compat<br/>tests/node_compat/"]
        Eco["Ecosystem compat<br/>tools/ecosystem_compat_*"]
    end
    subgraph Mid["Integration"]
        Spec["Spec tests<br/>tests/specs/"]
        Integ["Integration tests<br/>tests/integration/"]
    end
    subgraph Low["Unit"]
        Unit["Runtime unit tests<br/>tests/unit/"]
        UnitNode["Node API unit tests<br/>tests/unit_node/"]
        Inline["Inline #[cfg(test)] modules<br/>throughout cli/, runtime/, libs/, ext/"]
    end
    Top --> Mid
    Mid --> Low

Suites at a glance

Suite	Path	What it tests	How to run
Spec tests	tests/specs/	CLI behavior end-to-end	cargo test specs or ./x spec
Integration	tests/integration/	Long-running CLI scenarios driven from Rust	cargo test --test integration_tests
Runtime unit	tests/unit/	Deno.* namespace JS API behavior	./x test
Node API unit	tests/unit_node/	node:* modules	./x node-test
Node compat	tests/node_compat/	Node's own test suite, run against Deno	./x node-compat
WPT	tests/wpt/	Web Platform Tests for web standards	dedicated runner; see tools/upload_wptfyi.js
NAPI	tests/napi/	Native addon (Node-API) compatibility	./x napi
FFI	tests/ffi/	Deno.dlopen and FFI infrastructure	cargo test -p deno_ffi_tests
Crate-level inline	cli/, runtime/, libs/, ext/	Pure Rust units	cargo test -p <crate>

Spec tests (tests/specs/) — the workhorse

The vast majority of user-visible behavior is covered by spec tests. Each spec test is:

• A directory under tests/specs/<area>/<name>/
• A __test__.jsonc file describing one or more steps
• Optional input files (main.ts, fixtures, etc.)
• Optional .out files containing expected output

__test__.jsonc shape

The schema is published at tests/specs/schema.json. Minimal example:

{
  "tests": {
    "basic_case": {
      "args": "run main.ts",
      "output": "expected.out",
    },
    "with_flag": {
      "steps": [
        {
          "args": "run --allow-net main.ts",
          "output": "[WILDCARD]success[WILDCARD]",
        },
      ],
    },
  },
}

The args are passed to the deno binary that's being tested. output is either inline or a filename ending in .out.

The .out matching language

.out files use a small wildcard language so tests can be deterministic about important details and tolerant of incidental ones:

Token	Meaning
literal text	matches exactly
[WILDCARD]	zero or more of any character, can cross newlines
[WILDLINE]	zero or more of any character, stops at end of line
[WILDCHAR]	exactly one character
[WILDCHARS(5)]	exactly N characters
[UNORDERED_START] … [UNORDERED_END]	the lines between can match in any order
[# comment]	ignored, line comment

Use [WILDCARD] for paths, line numbers, and stack frames; [UNORDERED_START] for output that's racy by nature (concurrent test results, parallel logs).

Adding a spec test

1. mkdir tests/specs/<area>/<my_test>/
2. Write __test__.jsonc with at least one test entry
3. Add input files (main.ts, fixtures)
4. Add .out files for expected stdout (and optionally .err.out for stderr)
5. cargo test specs::<area>::<my_test> to verify

Runtime unit tests (tests/unit/)

These are JavaScript files testing Deno.* APIs from inside the runtime. Run with ./x test. They use Deno.test(...) and exercise the same code paths that user code does. New Deno.* API → new unit test.

Node API unit tests (tests/unit_node/)

Test individual node:* modules, often with parity assertions against Node's documented behavior. Run with ./x node-test. New node:* polyfill → new unit test.

Node compat tests (tests/node_compat/)

Imports Node's own test suite and runs it under Deno. Tests can be enabled, disabled, or marked as expected-to-fail in test config files. The recent commit log has many entries like test: enable parallel/test-dns-lookup-promises-options-deprecated.js (#33710) — these are toggles that mark a Node test as now-passing.

Run with ./x node-compat. The full list of currently-passing tests can be browsed at https://node-test-viewer.deno.dev/results/latest.

WPT (tests/wpt/)

The Web Platform Test suite, used to track web standards conformance. Results are uploaded to wpt.fyi via tools/upload_wptfyi.js. The WPT runner is in tools/wpt.ts (where present); see also the WPT submodule under tests/wpt/suite/.

Crate-level Rust tests

Each Rust crate has the standard #[cfg(test)] mod tests blocks inline with the source. Run them per-crate:

cargo test -p deno_core
cargo test -p deno_runtime
cargo test -p deno_fetch

Integration tests (tests/integration/)

Long-running scenarios — LSP edge cases (tests/integration/lsp_tests.rs is 19,909 lines), watcher behavior, and other things that don't fit the spec-test format. Run with cargo test --test integration_tests or filter:

cargo test --test integration_tests lsp::completions

Filtering

All cargo test filters work as substring matches:

cargo test                           # everything (slow)
cargo test specs                     # all spec tests
cargo test specs::run                # all spec tests under tests/specs/run/
cargo test deno_core::source_map     # crate-internal tests

Common pitfalls

• Forgot --recurse-submodules. Spec tests, WPT, and node_compat live in submodules. If tests/wpt/suite/ is empty, git submodule update --init --recursive.
• Snapshot drift. If a spec test fails after a JS change, check whether the expected .out needs updating. [WILDCARD] is your friend for parts that are intentionally non-deterministic.
• Flaky [UNORDERED_*] blocks. If output isn't deterministic order, wrap it in [UNORDERED_START]…[UNORDERED_END].
• Permission flakes. New tests that touch the filesystem need explicit --allow-read/--allow-write in their args line.