diff options
| -rw-r--r-- | docs/testing.md | 110 | ||||
| -rw-r--r-- | docs/testing/coverage.md | 36 | ||||
| -rw-r--r-- | docs/testing/documentation.md | 39 | ||||
| -rw-r--r-- | docs/testing/sanitizers.md | 69 | ||||
| -rw-r--r-- | docs/toc.json | 5 |
5 files changed, 150 insertions, 109 deletions
diff --git a/docs/testing.md b/docs/testing.md index d47ea356a..6f3fd555e 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -11,8 +11,8 @@ TypeScript code. ## Writing tests -To define a test you need to call `Deno.test` with a name and function to be -tested. There are two styles you can use. +To define a test you need to register it with a call to `Deno.test` with a name +and function to be tested. There are two styles you can use. ```ts import { assertEquals } from "https://deno.land/std@$STD_VERSION/testing/asserts.ts"; @@ -33,24 +33,6 @@ Deno.test({ }); ``` -## Assertions - -There are some useful assertion utilities at -https://deno.land/std@$STD_VERSION/testing#usage to make testing easier: - -```ts -import { - assertArrayIncludes, - assertEquals, -} from "https://deno.land/std@$STD_VERSION/testing/asserts.ts"; - -Deno.test("hello world", () => { - const x = 1 + 2; - assertEquals(x, 3); - assertArrayIncludes([1, 2, 3, 4, 5, 6], [3], "Expected 3 to be in the array"); -}); -``` - ### Async functions You can also test asynchronous code by passing a test function that returns a @@ -71,58 +53,6 @@ Deno.test("async hello world", async () => { }); ``` -### Resource and async op sanitizers - -Certain actions in Deno create resources in the resource table -([learn more here](./contributing/architecture.md)). These resources should be -closed after you are done using them. - -For each test definition, the test runner checks that all resources created in -this test have been closed. This is to prevent resource 'leaks'. This is enabled -by default for all tests, but can be disabled by setting the `sanitizeResources` -boolean to false in the test definition. - -The same is true for async operation like interacting with the filesystem. The -test runner checks that each operation you start in the test is completed before -the end of the test. This is enabled by default for all tests, but can be -disabled by setting the `sanitizeOps` boolean to false in the test definition. - -```ts -Deno.test({ - name: "leaky test", - fn() { - Deno.open("hello.txt"); - }, - sanitizeResources: false, - sanitizeOps: false, -}); -``` - -### Exit sanitizer - -There's also the exit sanitizer which ensures that tested code doesn't call -Deno.exit() signaling a false test success. - -This is enabled by default for all tests, but can be disabled by setting the -`sanitizeExit` boolean to false in thetest definition. - -```ts -Deno.test({ - name: "false success", - fn() { - Deno.exit(0); - }, - sanitizeExit: false, -}); - -Deno.test({ - name: "failing test", - fn() { - throw new Error("this test fails"); - }, -}); -``` - ## Running tests To run the test, call `deno test` with the file that contains your test @@ -237,39 +167,3 @@ failure, you can specify the `--fail-fast` flag when running the suite. ```shell deno test --fail-fast ``` - -## Test coverage - -Deno will collect test coverage into a directory for your code if you specify -the `--coverage` flag when starting `deno test`. - -This coverage information is acquired directly from the JavaScript engine (V8) -which is very accurate. - -This can then be further processed from the internal format into well known -formats by the `deno coverage` tool. - -``` -# Go into your project's working directory -git clone https://github.com/oakserver/oak && cd oak - -# Collect your coverage profile with deno test --coverage=<output_directory> -deno test --coverage=cov_profile - -# From this you can get a pretty printed diff of uncovered lines -deno coverage cov_profile - -# Or generate an lcov report -deno coverage cov_profile --lcov > cov_profile.lcov - -# Which can then be further processed by tools like genhtml -genhtml -o cov_profile/html cov_profile.lcov -``` - -By default, `deno coverage` will exclude any files matching the regular -expression `test\.(js|mjs|ts|jsx|tsx)` and only consider including files -matching the regular expression `^file:`. - -These filters can be overridden using the `--exclude` and `--include` flags. A -source file's url must match both regular expressions for it to be a part of the -report. diff --git a/docs/testing/coverage.md b/docs/testing/coverage.md new file mode 100644 index 000000000..0899c7cbd --- /dev/null +++ b/docs/testing/coverage.md @@ -0,0 +1,36 @@ +# Test coverage + +Deno will collect test coverage into a directory for your code if you specify +the `--coverage` flag when starting `deno test`. + +This coverage information is acquired directly from the JavaScript engine (V8) +which is very accurate. + +This can then be further processed from the internal format into well known +formats by the `deno coverage` tool. + +```bash +# Go into your project's working directory +git clone https://github.com/oakserver/oak && cd oak + +# Collect your coverage profile with deno test --coverage=<output_directory> +deno test --coverage=cov_profile + +# From this you can get a pretty printed diff of uncovered lines +deno coverage cov_profile + +# Or generate an lcov report +deno coverage cov_profile --lcov > cov_profile.lcov + +# Which can then be further processed by tools like genhtml +genhtml -o cov_profile/html cov_profile.lcov +``` + +By default, `deno coverage` will exclude any files matching the regular +expression `test\.(js|mjs|ts|jsx|tsx)` and only consider including specifiers +matching the regular expression `^file:` - ie. remote files will be excluded +from coverage report. + +These filters can be overridden using the `--exclude` and `--include` flags. A +module specifier must _match_ the include_regular expression and _not match_ the +exclude_ expression for it to be a part of the report. diff --git a/docs/testing/documentation.md b/docs/testing/documentation.md new file mode 100644 index 000000000..f0a2061db --- /dev/null +++ b/docs/testing/documentation.md @@ -0,0 +1,39 @@ +# Documentation tests + +Deno supports type-checking your documentation examples. + +This makes sure that examples within your documentation are up to date and +working. + +The basic idea is this: + +````ts +/** + * # Examples + * + * ```ts + * const x = 42; + * ``` + */ +```` + +The triple backticks mark the start and end of code blocks. + +If this example was in a file named foo.ts, running `deno test --doc foo.ts` +will extract this example, and then type-check it as a standalone module living +in the same directory as the module being documented. + +To document your exports, import the module using a relative path specifier: + +````ts +/** + * # Examples + * + * ```ts + * import { foo } from "./foo.ts"; + * ``` + */ +export function foo(): string { + return "foo"; +} +```` diff --git a/docs/testing/sanitizers.md b/docs/testing/sanitizers.md new file mode 100644 index 000000000..c078e5234 --- /dev/null +++ b/docs/testing/sanitizers.md @@ -0,0 +1,69 @@ +# Test Sanitizers + +The test runner offers several sanitizers to ensure that the test behaves in a +reasonable and expected way. + +### Resource sanitizer + +Certain actions in Deno create resources in the resource table +([learn more here](./contributing/architecture.md)). + +These resources should be closed after you are done using them. + +For each test definition, the test runner checks that all resources created in +this test have been closed. This is to prevent resource 'leaks'. This is enabled +by default for all tests, but can be disabled by setting the `sanitizeResources` +boolean to false in the test definition. + +```ts +Deno.test({ + name: "leaky resource test", + async fn() { + await Deno.open("hello.txt"); + }, + sanitizeResources: false, +}); +``` + +### Op sanitizer + +The same is true for async operation like interacting with the filesystem. The +test runner checks that each operation you start in the test is completed before +the end of the test. This is enabled by default for all tests, but can be +disabled by setting the `sanitizeOps` boolean to false in the test definition. + +```ts +Deno.test({ + name: "leaky operation test", + fn() { + setTimeout(function () {}, 1000); + }, + sanitizeOps: false, +}); +``` + +### Exit sanitizer + +There's also the exit sanitizer which ensures that tested code doesn't call +`Deno.exit()` signaling a false test success. + +This is enabled by default for all tests, but can be disabled by setting the +`sanitizeExit` boolean to false in the test definition. + +```ts +Deno.test({ + name: "false success", + fn() { + Deno.exit(0); + }, + sanitizeExit: false, +}); + +// This test never runs, because the process exits during "false success" test +Deno.test({ + name: "failing test", + fn() { + throw new Error("this test fails"); + }, +}); +``` diff --git a/docs/toc.json b/docs/toc.json index d1f93a642..e6af26745 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -72,7 +72,10 @@ "testing": { "name": "Testing", "children": { - "assertions": "Assertions" + "assertions": "Assertions", + "coverage": "Coverage", + "documentation": "Documentation", + "sanitizers": "Sanitizers" } }, "tools": { |