diff options
Diffstat (limited to 'docs/testing')
-rw-r--r-- | docs/testing/assertions.md | 263 | ||||
-rw-r--r-- | docs/testing/coverage.md | 36 | ||||
-rw-r--r-- | docs/testing/documentation.md | 39 | ||||
-rw-r--r-- | docs/testing/sanitizers.md | 69 |
4 files changed, 0 insertions, 407 deletions
diff --git a/docs/testing/assertions.md b/docs/testing/assertions.md deleted file mode 100644 index 5fca77832..000000000 --- a/docs/testing/assertions.md +++ /dev/null @@ -1,263 +0,0 @@ -## Assertions - -To help developers write tests the Deno standard library comes with a built in -[assertions module](https://deno.land/std@$STD_VERSION/testing/asserts.ts) which -can be imported from `https://deno.land/std@$STD_VERSION/testing/asserts.ts`. - -```js -import { assert } from "https://deno.land/std@$STD_VERSION/testing/asserts.ts"; - -Deno.test("Hello Test", () => { - assert("Hello"); -}); -``` - -The assertions module provides 10 assertions: - -- `assert(expr: unknown, msg = ""): asserts expr` -- `assertEquals(actual: unknown, expected: unknown, msg?: string): void` -- `assertExists(actual: unknown,msg?: string): void` -- `assertNotEquals(actual: unknown, expected: unknown, msg?: string): void` -- `assertStrictEquals(actual: unknown, expected: unknown, msg?: string): void` -- `assertStringIncludes(actual: string, expected: string, msg?: string): void` -- `assertArrayIncludes(actual: unknown[], expected: unknown[], msg?: string): void` -- `assertMatch(actual: string, expected: RegExp, msg?: string): void` -- `assertNotMatch(actual: string, expected: RegExp, msg?: string): void` -- `assertObjectMatch( actual: Record<PropertyKey, unknown>, expected: Record<PropertyKey, unknown>): void` -- `assertThrows(fn: () => void, ErrorClass?: Constructor, msgIncludes = "", msg?: string): Error` -- `assertThrowsAsync(fn: () => Promise<void>, ErrorClass?: Constructor, msgIncludes = "", msg?: string): Promise<Error>` - -### Assert - -The assert method is a simple 'truthy' assertion and can be used to assert any -value which can be inferred as true. - -```js -Deno.test("Test Assert", () => { - assert(1); - assert("Hello"); - assert(true); -}); -``` - -### Exists - -The `assertExists` can be used to check if a value is not `null` or `undefined`. - -```js -assertExists("Denosaurus"); -Deno.test("Test Assert Exists", () => { - assertExists("Denosaurus"); - assertExists(false); - assertExists(0); -}); -``` - -### Equality - -There are three equality assertions available, `assertEquals()`, -`assertNotEquals()` and `assertStrictEquals()`. - -The `assertEquals()` and `assertNotEquals()` methods provide a general equality -check and are capable of asserting equality between primitive types and objects. - -```js -Deno.test("Test Assert Equals", () => { - assertEquals(1, 1); - assertEquals("Hello", "Hello"); - assertEquals(true, true); - assertEquals(undefined, undefined); - assertEquals(null, null); - assertEquals(new Date(), new Date()); - assertEquals(new RegExp("abc"), new RegExp("abc")); - - class Foo {} - const foo1 = new Foo(); - const foo2 = new Foo(); - - assertEquals(foo1, foo2); -}); - -Deno.test("Test Assert Not Equals", () => { - assertNotEquals(1, 2); - assertNotEquals("Hello", "World"); - assertNotEquals(true, false); - assertNotEquals(undefined, ""); - assertNotEquals(new Date(), Date.now()); - assertNotEquals(new RegExp("abc"), new RegExp("def")); -}); -``` - -By contrast `assertStrictEquals()` provides a simpler, stricter equality check -based on the `===` operator. As a result it will not assert two instances of -identical objects as they won't be referentially the same. - -```js -Deno.test("Test Assert Strict Equals", () => { - assertStrictEquals(1, 1); - assertStrictEquals("Hello", "Hello"); - assertStrictEquals(true, true); - assertStrictEquals(undefined, undefined); -}); -``` - -The `assertStrictEquals()` assertion is best used when you wish to make a -precise check against two primitive types. - -### Contains - -There are two methods available to assert a value contains a value, -`assertStringIncludes()` and `assertArrayIncludes()`. - -The `assertStringIncludes()` assertion does a simple includes check on a string -to see if it contains the expected string. - -```js -Deno.test("Test Assert String Contains", () => { - assertStringIncludes("Hello World", "Hello"); -}); -``` - -The `assertArrayIncludes()` assertion is slightly more advanced and can find -both a value within an array and an array of values within an array. - -```js -Deno.test("Test Assert Array Contains", () => { - assertArrayIncludes([1, 2, 3], [1]); - assertArrayIncludes([1, 2, 3], [1, 2]); - assertArrayIncludes(Array.from("Hello World"), Array.from("Hello")); -}); -``` - -### Regex - -You can assert regular expressions via `assertMatch()` and `assertNotMatch()` -assertions. - -```js -Deno.test("Test Assert Match", () => { - assertMatch("abcdefghi", new RegExp("def")); - - const basicUrl = new RegExp("^https?://[a-z.]+.com$"); - assertMatch("https://www.google.com", basicUrl); - assertMatch("http://facebook.com", basicUrl); -}); - -Deno.test("Test Assert Not Match", () => { - assertNotMatch("abcdefghi", new RegExp("jkl")); - - const basicUrl = new RegExp("^https?://[a-z.]+.com$"); - assertNotMatch("https://deno.land/", basicUrl); -}); -``` - -### Object - -Use `assertObjectMatch` to check that a JavaScript object matches a subset of -the properties of an object. - -```js -// Simple subset -assertObjectMatch( - { foo: true, bar: false }, - { - foo: true, - }, -); -``` - -### Throws - -There are two ways to assert whether something throws an error in Deno, -`assertThrows()` and `assertThrowsAsync()`. Both assertions allow you to check -an -[Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) -has been thrown, the type of error thrown and what the message was. - -The difference between the two assertions is `assertThrows()` accepts a standard -function and `assertThrowsAsync()` accepts a function which returns a -[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). - -The `assertThrows()` assertion will check an error has been thrown, and -optionally will check the thrown error is of the correct type, and assert the -error message is as expected. - -```js -Deno.test("Test Assert Throws", () => { - assertThrows( - () => { - throw new Error("Panic!"); - }, - Error, - "Panic!", - ); -}); -``` - -The `assertThrowsAsync()` assertion is a little more complicated, mainly because -it deals with Promises. But basically it will catch thrown errors or rejections -in Promises. You can also optionally check for the error type and error message. - -```js -Deno.test("Test Assert Throws Async", () => { - assertThrowsAsync( - () => { - return new Promise(() => { - throw new Error("Panic! Threw Error"); - }); - }, - Error, - "Panic! Threw Error", - ); - - assertThrowsAsync( - () => { - return Promise.reject(new Error("Panic! Reject Error")); - }, - Error, - "Panic! Reject Error", - ); -}); -``` - -### Custom Messages - -Each of Deno's built in assertions allow you to overwrite the standard CLI error -message if you wish. For instance this example will output "Values Don't Match!" -rather than the standard CLI error message. - -```js -Deno.test("Test Assert Equal Fail Custom Message", () => { - assertEquals(1, 2, "Values Don't Match!"); -}); -``` - -### Custom Tests - -While Deno comes with powerful -[assertions modules](https://deno.land/std@$STD_VERSION/testing/asserts.ts) but -there is always something specific to the project you can add. Creating -`custom assertion function` can improve readability and reduce the amount of -code. - -```js -function assertPowerOf(actual: number, expected: number, msg?: string): void { - let received = actual; - while (received % expected === 0) received = received / expected; - if (received !== 1) { - if (!msg) { - msg = `actual: "${actual}" expected to be a power of : "${expected}"`; - } - throw new AssertionError(msg); - } -} -``` - -Use this matcher in your code like this: - -```js -Deno.test("Test Assert PowerOf", () => { - assertPowerOf(8, 2); - assertPowerOf(11, 4); -}); -``` diff --git a/docs/testing/coverage.md b/docs/testing/coverage.md deleted file mode 100644 index 0899c7cbd..000000000 --- a/docs/testing/coverage.md +++ /dev/null @@ -1,36 +0,0 @@ -# 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 deleted file mode 100644 index f0a2061db..000000000 --- a/docs/testing/documentation.md +++ /dev/null @@ -1,39 +0,0 @@ -# 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 deleted file mode 100644 index c078e5234..000000000 --- a/docs/testing/sanitizers.md +++ /dev/null @@ -1,69 +0,0 @@ -# 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"); - }, -}); -``` |