summaryrefslogtreecommitdiff
path: root/docs/testing
diff options
context:
space:
mode:
Diffstat (limited to 'docs/testing')
-rw-r--r--docs/testing/assertions.md263
-rw-r--r--docs/testing/coverage.md36
-rw-r--r--docs/testing/documentation.md39
-rw-r--r--docs/testing/sanitizers.md69
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");
- },
-});
-```