diff --git a/runtime/manual/tools/test.md b/runtime/manual/tools/test.md new file mode 100644 index 000000000..632fc9606 --- /dev/null +++ b/runtime/manual/tools/test.md @@ -0,0 +1,329 @@ +# deno test + +Run tests using Deno's built-in test runner. + +## Command + +`deno test [OPTIONS] [files]... [-- [SCRIPT_ARG]...]` + +## Synopsis + +```bash +deno test [--no-check[=]] [--import-map ] [-q|--quiet] +[--no-remote] [--no-npm] [--node-modules-dir[=]] +[--vendor[=]][-c|--config ] [--no-config] +[-r|--reload[=...]] [--lock []] [--lock-write] +[--no-lock] [--cert ] [--allow-read[=...]] [--deny-read[=...]] +[--allow-write[=...]] [--deny-write[=...]] +[--allow-net[=...]] [--deny-net[=...]] +[--allow-env[=...]] [--deny-env[=...]] +[--allow-run[=...]] [--deny-run[=...]] +[--allow-ffi[=...]] [--deny-ffi[=...]] [--allow-hrtime] [--deny-hrtime] [--allow-all] [--no-prompt] [--inspect[=]] +[--inspect-brk[=]] [--inspect-wait[=]] +[--cached-only] [--location ] [--v8-flags[=...]] +[--seed ] [--check[=]] [--ignore=...] +[--no-run] [--trace-leaks] [--doc] [--fail-fast[=]] [--allow-none] +[--filter ] [--shuffle[=]] [--coverage[=] [--parallel] +[--watch] [--watch-exclude[=...]] [--no-clear-screen] [--junit-path ] [--reporter ] [--env[=]] ... [-- [SCRIPT_ARG]...] + +deno test -h|--help +``` + +## Description + +Evaluate the given modules, run all tests declared with 'Deno.test()' and report +results to standard output: + +```bash +deno test +``` + +Directory arguments are expanded to all contained files matching the glob +`{__,_.,}test.{js,mjs,ts,mts,jsx,tsx}` + +The test runner is rich in functionality and supports a number of options. + +It can be executed in watch mode (`--watch`), supports parallel execution (`--parallel`), and can be configured to run tests in a random order with (`--shuffle`). Additionally, there is built in support for code coverage (`--coverage`) and leak detection (`--trace-leaks`). + +## Arguments + +`FILES` + +List of file names to run + +`SCRIPT_ARG` + +Arguments passed to script files + +## Options + +- `--no-check[=]`\ + Skip type-checking. If the value of '--no-check=remote' is supplied, diagnostic errors from remote modules will be ignored. + +- `--import-map `\ + Load [import map](https://docs.deno.com/runtime/manual/basics/import_maps) file from local file or remote URL. + +- `-q, --quiet` + Suppress diagnostic output + +- `--no-remote`\ + Do not resolve remote modules + +- `--no-npm`\ + Do not resolve npm modules + +- `--node-modules-dir[=]`\ + Enables or disables the use of a local node_modules folder for npm packages. + [possible values: true, false] + +- `--vendor[=]`\ + UNSTABLE: Enables or disables the use of a local vendor folder for remote modules and node_modules folder for npm packages. + [possible values: true, false] + +- `-c, --config ` + The [configuration file](https://deno.land/manual/getting_started/configuration_file) can be used to 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. + +- `--no-config`\ + Disable automatic loading of the configuration file. + +- `-r, --reload[=...]` + Reload source code cache (recompile TypeScript) + + `--reload` + Reload everything + `--reload=jsr:@std/http/file-server` + Reload only standard modules + `--reload=jsr:@std/http/file-server,jsr:@std/assert/assert-equals` + Reloads specific modules + `--reload=npm:` + Reload all npm modules + `--reload=npm:chalk` + Reload specific npm module + +- `--lock []`\ + Check the specified lock file. If value is not provided, defaults to "deno.lock" in the current working directory. + +- `--lock-write`\ + Force overwriting the lock file. + +- `--no-lock`\ + Disable auto discovery of the lock file. + +- `--cert `\ + Load certificate authority from PEM encoded file + +- `--no-prompt`\ + Always throw if required permission wasn't passed + +- `--inspect[=]`\ + Activate inspector on host:port (default: 127.0.0.1:9229) + +- `--inspect-brk[=]`\ + Activate inspector on host:port, wait for debugger to connect and break at the start of user script + +- `--inspect-wait[=]`\ + Activate inspector on host:port and wait for debugger to connect before running user code + +- `--cached-only`\ + Require that remote dependencies are already cached + +- `--location `\ + Value of `globalThis.location` used by some web APIs + +- `--v8-flags[=...]`\ + To see a list of all available flags use `--v8-flags=--help`. Any flags set with this flag are appended after the `DENO_V8_FLAGS` environmental variable + +- `--seed `\ + Set the random number generator seed + +- `--check[=]`\ + Set type-checking behavior. This subcommand type-checks local modules by default, so adding `--check` is redundant. If the value of '--check=all' is supplied, diagnostic errors from remote modules will be included. Alternatively, the 'deno check' subcommand can be used. + +- `--ignore=...`\ + Ignore files + +- `--no-run`\ + Cache test modules, but don't run tests + +- `--trace-leaks`\ + Enable tracing of leaks. Useful when debugging leaking ops in test, but impacts test execution time. + +- `--doc`\ + Type-check code blocks in JSDoc and Markdown + +- `--fail-fast[=]`\ + Stop after N errors. Defaults to stopping after first failure. + +- `--allow-none`\ + Don't return error code if no test files are found + +- `--filter `\ + Run tests with this string or pattern in the test name + +- `--shuffle[=]`\ + Shuffle the order in which the tests are run + +- `--coverage[=]`\ + Collect coverage profile data into DIR. If DIR is not specified, it uses `coverage/`. + +- `--parallel`\ + Run test modules in parallel. Parallelism defaults to the number of available CPUs or the value in the DENO_JOBS environment variable. + +- `--watch`\ + Watch for file changes and restart process automatically. Only local files from entry point module graph are watched. + +- `--watch-exclude[=...]`\ + Exclude provided files/patterns from watch mode + +- `--no-clear-screen`\ + Do not clear terminal screen when under watch mode + +- `--junit-path `\ + Write a JUnit XML test report to PATH. Use `-` to write to stdout which is the default when PATH is not provided. + +- `--reporter `\ + Select reporter to use. Default to 'pretty'. + [possible values: pretty, dot, junit, tap] + +- `--env[=]`\ + UNSTABLE: Load environment variables from local file. Only the first environment variable with a given key is used. Existing process environment variables are not overwritten. + +- `-h, --help`\ + Prints help information + +
+ Permissions Options + - `--allow-read[=...]`\ + Allow [file system read access](https://deno.land/manual/basics/permissions). Optionally specify allowed paths. + Examples: `--allow-read`, `--allow-read="/etc,/var/log.txt"` + + - `--deny-read[=...]`\ + Deny [file system read access](https://deno.land/manual/basics/permissions). Optionally specify denied paths. + Examples: `--deny-read`, `--deny-read="/etc,/var/log.txt"` + + - `--allow-write[=...]`\ + Allow [file system write access](https://deno.land/manual/basics/permissions). Optionally specify allowed paths. + Examples: `--allow-write`, `--allow-write="/etc,/var/log.txt"` + + - `--deny-write[=...]`\ + Deny [file system write access](https://deno.land/manual/basics/permissions). Optionally specify denied paths. + Examples: `--deny-write`, `--deny-write="/etc,/var/log.txt"` + + - `--allow-net[=...]` \ + Allow [network access](https://deno.land/manual/basics/permissions). Optionally specify allowed IP addresses and host names, with ports as necessary. + Examples: `--allow-net`, `--allow-net="localhost:8080,deno.land"` + + - `--deny-net[=...]`\ + Deny [network access](https://deno.land/manual/basics/permissions). Optionally specify denied IP addresses and host names, with ports as necessary. + Examples: `--deny-net`, `--deny-net="localhost:8080,deno.land"` + + - `--unsafely-ignore-certificate-errors[=...]`\ + DANGER: Disables verification of TLS certificates + + - `--allow-env[=...]`\ + Allow [access to system environment information](https://deno.land/manual/basics/permissions). Optionally specify accessible environment variables. + Examples: `--allow-env`, `--allow-env="PORT,HOME,PATH"` + + - `--deny-env[=...]`\ + Deny [access to system environment information](https://deno.land/manual/basics/permissions). Optionally specify accessible environment variables. + Examples: `--deny-env`, `--deny-env="PORT,HOME,PATH"` + + - `--allow-sys[=...]`\ + Allow [access to OS information](https://deno.land/manual/basics/permissions). Optionally allow + specific APIs by function name. + Examples: `--allow-sys`, `--allow-sys="systemMemoryInfo,osRelease"` + + - `--deny-sys[=...]`\ + Deny [access to OS information](https://deno.land/manual/basics/permissions). Optionally deny + specific APIs by function name. + Examples: `--deny-sys`, `--deny-sys="systemMemoryInfo,osRelease"` + + - `--allow-run[=...]`\ + Allow [running subprocesses](https://deno.land/manual/basics/permissions). Optionally + specify allowed runnable program names. + Examples: `--allow-run`, `--allow-run="whoami,ps"` + + - `--deny-run[=...]`\ + Deny [running subprocesses](https://deno.land/manual/basics/permissions). Optionally specify denied runnable program names. + Examples: `--deny-run`, `--deny-run="whoami,ps"` + + - `--allow-ffi[=...]`\ + (Unstable) Allow loading dynamic libraries. Optionally specify [allowed directories or files](https://deno.land/manual/basics/permissions). + Examples: `--allow-ffi`, `--allow-ffi="./libfoo.so"` + + - `--deny-ffi[=...]`\ + (Unstable) Deny [loading dynamic libraries](https://deno.land/manual/basics/permissions). Optionally specify denied directories or files. + Examples: `--deny-ffi`, `--deny-ffi="./libfoo.so"` + + - `--allow-hrtime`\ + Allow [high-resolution time measurement](https://deno.land/manual/basics/permissions). Note: this can enable timing attacks and fingerprinting. + + - `--deny-hrtime`\ + Deny [high-resolution time measurement](https://deno.land/manual/basics/permissions). Note: this can prevent + timing attacks and fingerprinting. + + - `-A, --allow-all`\ + Allow [all permissions](https://deno.land/manual/basics/permissions). +
+ +## Examples + +- Run tests + +```bash +deno test +``` + +- Run tests in specific files + +```bash +deno test src/fetch_test.ts src/signal_test.ts +``` + +- Run tests where glob matches + +```bash +deno test src/*.test.ts +``` + +- Run tests and skip type-checking + +```bash +deno test --no-check +``` + +- Run tests, re-running on file change + +```bash +deno test --watch +``` + +- Reload everything + +```bash +--reload +``` + +- Reload only standard modules + +```bash +--reload=jsr:@std/http/file-server +``` + +- Reloads specific modules + +```bash +--reload=jsr:@std/http/file-server,jsr:@std/assert/assert-equals +``` + +- Reload all npm modules + +```bash +--reload=npm: +``` + +- Reload specific npm module + +```bash +--reload=npm:chalk +``` diff --git a/sidebars/runtime.js b/sidebars/runtime.js index e8982131c..b8984416a 100644 --- a/sidebars/runtime.js +++ b/sidebars/runtime.js @@ -215,6 +215,11 @@ const sidebars = { label: "deno task", id: "manual/tools/task_runner", }, + { + type: "doc", + label: "deno test", + id: "manual/tools/test", + }, { type: "doc", label: "deno types",