On this page
- Running tests
- Filtering
- Running affected tests
- Permissions
- Watch mode
- Parallel execution
- Code coverage
- Parameterized tests
- Snapshot testing
- Reporters
- Randomize order
- Sharding
- Retrying and repeating
- Leak detection
- Testing code in documentation
- Type checking options
- Dependency management options
- Options
- Debugging options
- Testing options
- File watching options
deno test
Deno ships with a built-in test runner using the
Deno.test() API. To learn how to write tests, see the
Testing fundamentals guide. For assertions, see
@std/assert and
@std/expect.
Running tests Jump to heading
Run all tests in the current directory and subdirectories:
deno test
Run tests in specific files:
deno test src/fetch_test.ts src/signal_test.ts
Run tests matching a glob pattern:
deno test src/*.test.ts
Skip type-checking:
deno test --no-check
Filtering Jump to heading
Run only the tests whose name matches a string or a pattern with --filter:
# Run tests whose name contains "database"
deno test --filter "database"
# Run tests whose name matches a regular expression
deno test --filter "/^connect.*/"
Wrap the filter value in forward slashes (/) to treat it as a regular
expression, like JavaScript's regex literal syntax. Filtering does not affect
test steps: when a test's name matches the filter, all of its steps run.
To control which test files are collected in the first place, set test.include
and test.exclude in your config file. See
include and exclude.
Running affected tests Jump to heading
When iterating on a change, you can run only the tests touched by it instead of the whole suite. These are one-shot runs, not watch mode.
--changed runs the test modules affected by files changed in git. With no
value it uses the working tree (staged, unstaged, and untracked files); pass a
ref to also include commits since the merge-base with that ref:
# Tests affected by uncommitted changes
deno test --changed
# Tests affected since branching off main
deno test --changed=origin/main
--related runs the test modules that depend on specific source files, without
consulting git:
# Tests that import src/util.ts
deno test --related=src/util.ts
Both flags filter the collected test files down to those that reach the changed or named files through the module graph. See Running affected tests in the testing guide for the workflow and how selection works.
Permissions Jump to heading
Tests run with the same permission model as
deno run. Grant permissions for your test suite:
deno test --allow-read --allow-net
Watch mode Jump to heading
Re-run tests automatically when files change:
deno test --watch
Parallel execution Jump to heading
Run test files across multiple worker threads:
deno test --parallel
By default, --parallel uses the number of available CPUs. Use DENO_JOBS=<N>
to control the number of threads:
DENO_JOBS=4 deno test --parallel
Code coverage Jump to heading
Collect coverage data and generate a report:
deno test --coverage
This writes raw coverage data to a coverage/ directory. To generate a summary
from existing coverage data, use
deno coverage:
deno coverage coverage/
You can also output an lcov report for use with external tools:
deno coverage --lcov coverage/ > coverage.lcov
To fail the run when coverage drops below a target, set a threshold (for example
deno coverage --threshold=90). See
coverage thresholds for
per-metric configuration.
Parameterized tests Jump to heading
Run the same test body over a table of cases with
Deno.test.each, which registers one
independently reported test per case. See
Parameterized tests for the name templates
and case forms.
Snapshot testing Jump to heading
Capture a value and compare it against a stored reference on every run with the
built-in t.assertSnapshot, updating with --update-snapshots (-u). See
Snapshot testing.
Reporters Jump to heading
Choose an output format with --reporter. Four reporters are built in:
pretty(default): detailed, human-readable outputdot: one character per test, for a concise overviewjunit: JUnit XML format, for CI systemstap: Test Anything Protocol output
deno test --reporter=dot
deno test --reporter=tap
Write a JUnit XML report to a file while keeping the human-readable pretty
output in the terminal:
deno test --junit-path=report.xml
Randomize order Jump to heading
Shuffle the order tests run in to catch hidden dependencies between tests:
deno test --shuffle
Sharding Jump to heading
Split a test suite across several machines with --shard=<index>/<count>, where
index is 1-based. The discovered test files are sorted for a stable order and
divided into <count> balanced groups; the run executes only the files in group
<index>:
# On machine 1 of 3
deno test --shard=1/3
# On machine 2 of 3
deno test --shard=2/3
Sharding is applied before --shuffle, so a given shard runs the same files on
every machine regardless of the shuffle seed.
Retrying and repeating Jump to heading
Set a run-wide default for retries and repetitions with --retry and
--repeats:
# Re-run each failing test up to twice before reporting failure
deno test --retry=2
# Run every test three times and fail if any run fails
deno test --repeats=3
A test that sets its own retry or repeats option overrides the flag. See
retrying and repeating tests for
the per-test options.
Leak detection Jump to heading
Trace the source of leaked async operations, timers, or resources:
deno test --trace-leaks
Testing code in documentation Jump to heading
Evaluate code blocks in JSDoc and Markdown files as tests:
deno test --doc
See documentation tests for details.
deno test [OPTIONS] [files]... [-- [SCRIPT_ARG]...]Run tests using Deno's built-in test runner.
Evaluate the given modules, run all tests declared with Deno.test() and report results to standard output:
deno test src/fetch_test.ts src/signal_test.ts
Directory arguments are expanded to all contained files matching the glob {*_,*.,}test.{js,mjs,ts,mts,jsx,tsx}
or **/__tests__/**:
deno test src/
Type checking options Jump to heading
--check<CHECK_TYPE>optionalSet type-checking behavior. This subcommand type-checks local modules by default, so passing --check is redundant; pass --check=all to also type-check remote modules. Alternatively, use the 'deno check' subcommand.
--no-check<NO_CHECK_TYPE>optionalSkip type-checking. If the value of "remote" is supplied, diagnostic errors from remote modules will be ignored.
Dependency management options Jump to heading
--cached-onlyRequire that remote dependencies are already cached.
--frozen<BOOLEAN>optionalError out if lockfile is out of date.
Load import map file from local file or remote URL.
--lock<FILE>optionalCheck the specified lock file. (If value is not provided, defaults to "./deno.lock").
--no-lockDisable auto discovery of the lock file.
--no-npmDo not resolve npm modules.
--no-remoteDo not resolve remote modules.
--node-modules-dir<MODE>optionalSelects the node_modules directory mode for npm packages (not a path). One of: auto (create a local node_modules directory and install npm packages into it), manual (use the existing local node_modules directory, do not modify it), none (do not use a local node_modules directory; resolve npm packages from the global cache). Defaults to auto when the flag is passed without a value.
--node-modules-linker<MODE>Sets the linker mode for npm packages (isolated or hoisted).
--reload, -r<CACHE_BLOCKLIST>optionalReload source code cache (recompile TypeScript). With no value, reloads everything. Pass a comma-separated list of specifiers to reload only those modules; npm: reloads all npm modules; npm:chalk reloads a single npm module; jsr:@std/http/file-server,jsr:@std/assert/assert-equals reloads specific modules.
--vendor<vendor>optionalToggles local vendor folder usage for remote modules and a node_modules folder for npm packages.
Options Jump to heading
--allow-scripts<PACKAGE>optionalAllow running npm lifecycle scripts for the given packages
Note: Scripts will only be executed when using a node_modules directory (--node-modules-dir).
--cert<FILE>Load certificate authority from PEM encoded file.
--conditions<conditions>Use this argument to specify custom conditions for npm package exports. You can also use DENO_CONDITIONS env var. .
Configure different aspects of deno including TypeScript, linting, and code formatting.
Typically the configuration file will be called deno.json or deno.jsonc and
automatically detected; in that case this flag is not necessary.
--env-file<FILE>optionalLoad environment variables from local file Only the first environment variable with a given key is used. Existing process environment variables are not overwritten, so if variables with the same names already exist in the environment, their values will be preserved. Where multiple declarations for the same environment variable exist in your .env file, the first one encountered is applied. This is determined by the order of the files you pass as arguments.
--ext<ext>Set content type of the supplied file.
--hide-stacktracesHide stack traces for errors in failure test results.
--ignore<ignore>Ignore files.
--location<HREF>Value of globalThis.location used by some web APIs.
--minimum-dependency-age<minimum-dependency-age>(Unstable) The age in minutes, ISO-8601 duration or RFC3339 absolute timestamp (e.g. '120' for two hours, 'P2D' for two days, '2025-09-16' for cutoff date, '2025-09-16T12:00:00+00:00' for cutoff time, '0' to disable).
--no-configDisable automatic loading of the configuration file.
--parallelRun test modules in parallel. Parallelism defaults to the number of available CPUs or the value of the DENO_JOBS environment variable.
--preload<FILE>A list of files that will be executed before the main module.
--require<FILE>A list of CommonJS modules that will be executed before the main module.
--seed<NUMBER>Set the random number generator seed.
--v8-flags<V8_FLAGS>optionalTo see a list of all available flags use --v8-flags=--help
Flags can also be set via the DENO_V8_FLAGS environment variable.
Any flags set with this flag are appended after the DENO_V8_FLAGS environment variable.
Debugging options Jump to heading
--inspect<HOST_PORT>optionalActivate inspector on host:port [default: 127.0.0.1:9229]. Host and port are optional. Using port 0 will assign a random free port.
--inspect-brk<HOST_PORT>optionalActivate inspector on host:port, wait for debugger to connect and break at the start of user script.
--inspect-wait<HOST_PORT>optionalActivate inspector on host:port and wait for debugger to connect before running user code.
Testing options Jump to heading
--changed<REF>optionalRun only test modules affected by files changed in git.
With no value, uses uncommitted changes (staged, unstaged and untracked).
Pass a git ref to compare against, e.g. --changed=main or --changed=HEAD~1.
--cleanEmpty the temporary coverage profile data directory before running tests.
Note: running multiple deno test --clean`` calls in series or parallel for the same coverage directory may cause race conditions.
--coverage<DIR>optionalCollect coverage profile data into DIR. If DIR is not specified, it uses 'coverage/'. This option can also be set via the DENO_COVERAGE_DIR environment variable.
--coverage-raw-data-onlyOnly collect raw coverage data, without generating a report.
--coverage-threshold<PERCENT>Fail if coverage is below this percentage (0-100). Requires --coverage.
--docEvaluate code blocks in JSDoc and Markdown.
--fail-fast<N>optionalStop after N errors. Defaults to stopping after first failure.
--filter<filter>Run tests with this string or regexp pattern in the test name.
--junit-path<PATH>Write a JUnit XML test report to PATH. Use '-' to write to stdout which is the default when PATH is not provided.
--no-runCache test modules, but don't run tests.
--permit-no-filesDon't return an error code if no files were found.
--repeats<NUMBER>Run each test NUMBER additional times. Every repetition must pass. Tests that set their own repeats option take precedence.
--reporter<reporter>Select reporter to use. Default to 'pretty'.
--retry<NUMBER>Re-run failing tests up to NUMBER times. A test passes if any attempt passes. Tests that set their own retry option take precedence.
--sanitize-opsEnable the ops sanitizer, which ensures that all async ops started in a test are completed before the test ends.
--sanitize-resourcesEnable the resources sanitizer, which ensures that all resources opened in a test are closed before the test ends.
--shard<INDEX/COUNT>Run only the test files for shard INDEX of COUNT, e.g. --shard=2/3.
The discovered test files are sorted and split into COUNT consecutive groups; INDEX is 1-based. Useful for splitting a run across machines.
--shuffle<NUMBER>optionalShuffle the order in which the tests are run.
--trace-leaksEnable tracing of leaks. Useful when debugging leaking ops in test, but impacts test execution time.
--update-snapshots, -uUpdate snapshots created with t.assertSnapshot() instead of failing when they do not match.
File watching options Jump to heading
--no-clear-screenDo not clear terminal screen when under watch mode.
--watch<FILES>optionalWatch for file changes and restart process automatically. Local files from entry point module graph are watched by default. Additional paths might be watched by passing them as arguments to this flag.
--watch-exclude<FILES>optionalExclude provided files/patterns from watch mode.