Merge pull request #15 from udibo/dev

Rewrite describe and it to use test steps

.github/workflows/ci.yml

@@ -24,9 +24,9 @@ jobs:
         if: matrix.os == 'ubuntu-latest'
         run: deno lint
       - name: Run tests
-        run: deno test --allow-read --coverage=cov
+        run: deno test --coverage=cov
       - name: Run tests unstable
-        run: deno test --allow-read --unstable
+        run: deno test --unstable
       - name: Generate lcov
         if: |
           matrix.os == 'ubuntu-latest' &&

.vscode/launch.json

@@ -7,7 +7,7 @@
       "request": "launch",
       "cwd": "${workspaceFolder}",
       "runtimeExecutable": "deno",
-      "runtimeArgs": ["run", "--inspect", "${file}"],
+      "runtimeArgs": ["run", "--inspect-brk", "${file}"],
       "attachSimplePort": 9229
     },
     {
@@ -16,7 +16,7 @@
       "request": "launch",
       "cwd": "${workspaceFolder}",
       "runtimeExecutable": "deno",
-      "runtimeArgs": ["test", "--inspect", "${file}"],
+      "runtimeArgs": ["test", "--inspect-brk", "${file}"],
       "attachSimplePort": 9229
     }
   ]

README.md

@@ -1,22 +1,22 @@
 # Test Suite
 
-[![version](https://img.shields.io/badge/release-0.9.5-success)](https://deno.land/x/test_suite@0.9.5)
-[![deno doc](https://doc.deno.land/badge.svg)](https://doc.deno.land/https/deno.land/x/test_suite@0.9.5/mod.ts)
+[![version](https://img.shields.io/badge/release-0.10.0-success)](https://deno.land/x/test_suite@0.10.0)
+[![deno doc](https://doc.deno.land/badge.svg)](https://doc.deno.land/https/deno.land/x/test_suite@0.10.0/mod.ts)
 [![CI](https://github.com/udibo/test_suite/workflows/CI/badge.svg)](https://github.com/udibo/test_suite/actions?query=workflow%3ACI)
 [![codecov](https://codecov.io/gh/udibo/test_suite/branch/master/graph/badge.svg?token=EFKGY72AAV)](https://codecov.io/gh/udibo/test_suite)
 [![license](https://img.shields.io/github/license/udibo/test_suite)](https://github.com/udibo/test_suite/blob/master/LICENSE)
 
-An extension of Deno's built-in test runner to add setup/teardown hooks and the
-ability to organize tests. Includes describe/it functions for creating nested
-tests in a format similar to Jasmine, Jest, and Mocha.
+An extension of Deno's built-in test runner to add setup/teardown hooks and make
+it easier to organize tests in a format similar to Jasmine, Jest, and Mocha.
 
 ## Features
 
 - Ability to group tests together into test suites
-- Setup/teardown hooks for test suites(beforeAll, afterAll, beforeEach,
+- Setup/teardown hooks for test suites (beforeAll, afterAll, beforeEach,
   afterEach)
 - Tests within a test suite inherit configuration options
 - describe/it functions similar to Jasmine, Jest, and Mocha
+- shorthand for focusing and ignoring tests
 
 ## Installation
 
@@ -26,20 +26,13 @@ also be imported directly from GitHub using raw content URLs.
 
 ```ts
 // Import from Deno's third party module registry
-import { TestSuite, test } from "https://deno.land/x/test_suite@0.9.5/mod.ts";
+import { describe, it } from "https://deno.land/x/test_suite@0.10.0/mod.ts";
 // Import from GitHub
-import { TestSuite, test } "https://raw.githubusercontent.com/udibo/test_suite/0.9.5/mod.ts";
+import { describe, it } "https://raw.githubusercontent.com/udibo/test_suite/0.10.0/mod.ts";
 ```
 
 ## Usage
 
-Below are some examples of how to use TestSuite and test in tests.
-
-See [deno docs](https://doc.deno.land/https/deno.land/x/[email protected]/mod.ts)
-for more information.
-
-### TestSuite
-
 When you have a set of tests that are related, you can group them together by
 creating a test suite. A test suite can contain other test suites and tests. All
 tests within a suite will inherit their options from the suite unless they
@@ -53,99 +46,29 @@ values available to the tests that are defined in the beforeAll function.
 The beforeEach and afterEach hook options are similar to beforeAll and afterAll
 except they are called before and after each individual test.
 
-The example test below can be found in the example directory.
-
-```ts
-import { test, TestSuite } from "https://deno.land/x/[email protected]/mod.ts";
-import { assertEquals } from "https://deno.land/[email protected]/testing/asserts.ts";
-import {
-  getUser,
-  resetUsers,
-  User,
-} from "https://deno.land/x/[email protected]/example/user.ts";
-
-interface UserSuiteContext {
-  user: User;
-}
-const userSuite: TestSuite<UserSuiteContext> = new TestSuite({
-  name: "user",
-  beforeEach(context: UserSuiteContext) {
-    context.user = new User("Kyle June");
-  },
-  afterEach() {
-    resetUsers();
-  },
-});
-
-test(userSuite, "create", () => {
-  const user = new User("John Doe");
-  assertEquals(user.name, "John Doe");
-});
-
-const getUserSuite: TestSuite<UserSuiteContext> = new TestSuite({
-  name: "getUser",
-  suite: userSuite,
-});
+Below are some examples of how to use `describe` and `it` in tests.
 
-test(getUserSuite, "user does not exist", () => {
-  assertEquals(getUser("John Doe"), undefined);
-});
-
-test(getUserSuite, "user exists", (context: UserSuiteContext) => {
-  assertEquals(getUser("Kyle June"), context.user);
-});
-
-test(userSuite, "resetUsers", (context: UserSuiteContext) => {
-  assertEquals(getUser("Kyle June"), context.user);
-  resetUsers();
-  assertEquals(getUser("Kyle June"), undefined);
-});
-```
-
-If you run the above tests using `deno test`, you will get the following output.
-Each test name is prefixed with the suite name.
-
-```sh
-$ deno test
-running 4 tests
-test user create ... ok (4ms)
-test user getUser user does not exist ... ok (1ms)
-test user getUser user exists ... ok (2ms)
-test user resetUsers ... ok (2ms)
-
-test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out (11ms)
-```
-
-### describe/it
-
-When you have a set of tests that are related, you can group them together by
-creating a test suite with describe. A test suite can contain other test suites
-and tests. All tests within a suite will inherit their options from the suite
-unless they specifically set them.
-
-The beforeAll and afterAll hook options can be used to do something before and
-after all the tests in the suite run. If you would like to set values for all
-tests within the suite, you can create a context interface that defines all the
-values available to the tests that are defined in the beforeAll function.
+See
+[deno docs](https://doc.deno.land/https/deno.land/x/[email protected]/mod.ts)
+for more information.
 
-The beforeEach and afterEach hook options are similar to beforeAll and afterAll
-except they are called before and after each individual test.
+### Nested test grouping
 
-The example test below can be found in the example directory.
+The example below can be found [here](examples/user_nested_test.ts).
 
 ```ts
 import {
   afterEach,
   beforeEach,
   describe,
   it,
-} from "https://deno.land/x/test_suite@0.9.5/mod.ts";
-import { assertEquals } from "https://deno.land/std@0.120.0/testing/asserts.ts";
+} from "https://deno.land/x/test_suite@0.10.0/mod.ts";
+import { assertEquals } from "https://deno.land/std@0.126.0/testing/asserts.ts";
 import {
   getUser,
   resetUsers,
   User,
-} from "https://deno.land/x/test_suite@0.9.5/examples/user.ts";
+} from "https://deno.land/x/test_suite@0.10.0/examples/user.ts";
 
 describe("user describe", () => {
   let user: User;
@@ -182,19 +105,119 @@ describe("user describe", () => {
 ```
 
 If you run the above tests using `deno test`, you will get the following output.
-Each test name is prefixed with the suite name.
 
 ```sh
 $ deno test
-running 4 tests
-test user describe create ... ok (4ms)
-test user describe getUser user does not exist ... ok (1ms)
-test user describe getUser user exists ... ok (2ms)
-test user describe resetUsers ... ok (2ms)
+running 1 test from file:///examples/user_nested_test.ts
+test user describe ...
+  test create ... ok (4ms)
+  test getUser ...
+    test user does not exist ... ok (4ms)
+    test user exists ... ok (3ms)
+  ok (11ms)
+  test resetUsers ... ok (3ms)
+ok (24ms)
+
+test result: ok. 1 passed (5 steps); 0 failed; 0 ignored; 0 measured; 0 filtered out (43ms)
+```
+
+### Flat test grouping
+
+The example below can be found [here](examples/user_flat_test.ts).
+
+```ts
+import { test, TestSuite } from "https://deno.land/x/[email protected]/mod.ts";
+import { assertEquals } from "https://deno.land/[email protected]/testing/asserts.ts";
+import {
+  getUser,
+  resetUsers,
+  User,
+} from "https://deno.land/x/[email protected]/example/user.ts";
+
+interface UserContext {
+  user: User;
+}
+
+const userSuite = describe({
+  name: "user",
+  beforeEach(context: UserContext) {
+    context.user = new User("Kyle June");
+  },
+  afterEach() {
+    resetUsers();
+  },
+});
+
+it(userSuite, "create", () => {
+  const user = new User("John Doe");
+  assertEquals(user.name, "John Doe");
+});
+
+interface GetUserContext extends UserContext {
+  value?: number;
+}
 
-test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out (11ms)
+const getUserSuite = describe<GetUserContext>({
+  name: "getUser",
+  suite: userSuite,
+});
+
+it(getUserSuite, "user does not exist", () => {
+  assertEquals(getUser("John Doe"), undefined);
+});
+
+it(getUserSuite, "user exists", (context: UserContext) => {
+  assertEquals(getUser("Kyle June"), context.user);
+});
+
+it(userSuite, "resetUsers", (context: UserContext) => {
+  assertEquals(getUser("Kyle June"), context.user);
+  resetUsers();
+  assertEquals(getUser("Kyle June"), undefined);
+});
 ```
 
+If you run the above tests using `deno test`, you will get the following output.
+
+```sh
+$ deno test
+running 1 test from file:///examples/user_flat_test.ts
+test user ...
+  test create ... ok (3ms)
+  test getUser ...
+    test user does not exist ... ok (2ms)
+    test user exists ... ok (4ms)
+  ok (11ms)
+  test resetUsers ... ok (3ms)
+ok (22ms)
+
+test result: ok. 1 passed (5 steps); 0 failed; 0 ignored; 0 measured; 0 filtered out (44ms)
+```
+
+### Shorthand for focusing and ignoring tests
+
+To avoid having to change your test function arguments to be able to focus or
+ignore tests temporarily, a shorthand has been implemented. This makes it as
+easy as typing `.only` and `.ignore` to focus and ignore tests.
+
+- To focus a test case, replace `it` with `it.only`.
+- To ignore a test case, replace `it` with `it.ignore`.
+- To focus a test suite, replace `describe` with `describe.only`.
+- To ignore a test suite, replace `describe` with `describe.ignore`.
+
+### Migrating from earlier versions
+
+The `TestSuite` class has been turned into an internal only class. To create a
+test suite, use the `describe` function instead of creating a new instance of
+`TestSuite` directly.
+
+The `test` function has been removed. Replace `test` calls with calls to `it`.
+
+The `each` function that was previously available has been temporarily removed
+to allow me to switch over to the test step api quicker. I plan on implementing
+this later. If you make use of the `each` function for generating test cases, do
+not upgrade beyond version 0.9.5.
+
 ## License
 
 [MIT](LICENSE)

deps.ts

@@ -1,11 +1,12 @@
-export { delay } from "https://deno.land/std@0.120.0/async/delay.ts";
+export { delay } from "https://deno.land/std@0.126.0/async/delay.ts";
 export {
   assert,
   assertEquals,
   AssertionError,
   assertObjectMatch,
   assertRejects,
+  assertStrictEquals,
   assertThrows,
-} from "https://deno.land/std@0.120.0/testing/asserts.ts";
+} from "https://deno.land/std@0.126.0/testing/asserts.ts";
 
 export { Vector } from "https://deno.land/x/[email protected]/vector.ts";