Merge pull request #1 from RobDWaller/0.1.0

0.1.0

Author: RobDWaller

README.md

@@ -1,3 +1,113 @@
+[![Actions Status](https://github.com/robdwaller/explicitly/workflows/ci/badge.svg)](https://github.com/robdwaller/explicitly/actions)
+
 # Explicitly
 
-Extends the code Deno assertion library with additional assertions so developers can write more explicit Unit Tests if they choose to.
+This library extends the [Deno assertions module](https://github.com/denoland/deno/blob/master/std/testing/asserts.ts) with additional assertions so developers can write more explicit unit tests if they choose to. It works with [Deno Test Tools](https://deno.land/manual/testing) in the same way the built in assertions do.
+
+The principle behind this library is unit tests should focus small units of business logic. Assertions should therefore focus on the assertion of basic types in an explicit manner. This library provides assertions which fulfill this requirement and all the assertions are simple and specific which makes the intent of a unit test clearer.
+
+For more generalised equality checks, better suited to integration or functional tests, please use the built in [Deno assertions module](https://github.com/denoland/deno/blob/master/std/testing/asserts.ts).
+
+## Installation
+
+Before you use this library make sure you have read and understood how to set up [Deno Tests](https://deno.land/manual/testing).
+
+To install this library and make use of the assertions in your test suite simply add the following import to the test modules which require it.
+
+```js
+import {
+  assertTrue,
+  assertFalse,
+  assertSame,
+  assertGreater,
+  assertGreaterOrEqual,
+  assertLess,
+  assertLessOrEqual,
+  assertInstanceOf,
+  assertTypeOf,
+} from "https://raw.githubusercontent.com/RobDWaller/explicitly/0.1.0/mod.ts";
+```
+
+## Basic Usage
+
+This assertion library comes with nine basic assertions methods:
+
+- `assertTrue(actual: unknown): void`
+- `assertFalse(actual: unknown): void`
+- `assertSame(actual: unknown, expected: unknown): void`
+- `assertGreater(actual: unknown, expected: unknown): void`
+- `assertGreaterOrEqual(actual: unknown, expected: unknown): void`
+- `assertLess(actual: unknown, expected: unknown): void`
+- `assertLessOrEqual(actual: unknown, expected: unknown): void`
+- `assertInstanceOf(actual: unknown, expected: any): void`
+- `assertTypeOf(actual: unknown, expected: string): void`
+
+Each of these assertions aims to test a single thing. This means unit tests are explicit and clearer to read.
+
+### Assert True Example
+
+A basic example of when you may wish to assert true.
+
+```js
+Deno.test("Assert True Example", () => {
+  function isOlderThanFive(age: number): boolean {
+    return age >= 5;
+  }
+
+  const childAge: number = 6;
+
+  const result: boolean = isOlderThanFive(childAge);
+
+  assertTrue(result);
+});
+```
+
+### Assert Instance Of Example
+
+A more advanced example of when you may wish to assert an instance of. Usually when there is a polymorphic relationship between objects.
+
+```js
+Deno.test("Assert Instance Of Example", () => {
+  interface Person {
+    name: string;
+    age: number;
+    location: string;
+  }
+
+  class Adult implements Person {
+    name: string;
+    age: number;
+    location: string;
+
+    constructor(name: string, age: number, location: string) {
+      this.name = name;
+      this.age = age;
+      this.location = location;
+    }
+  }
+
+  class Child implements Person {
+    name: string;
+    age: number;
+    location: string;
+
+    constructor(name: string, age: number, location: string) {
+      this.name = name;
+      this.age = age;
+      this.location = location;
+    }
+  }
+
+  function createPerson(name: string, age: number, location: string): Person {
+    if (age < 18) {
+      return new Child(name, age, location);
+    }
+
+    return new Adult(name, age, location);
+  }
+
+  const jenny = createPerson("Jenny Brown", 12, "US");
+
+  assertInstanceOf(jenny, Child);
+});
+```

mod.ts

@@ -4,6 +4,8 @@ import {
   greaterOrEqual,
   less,
   lessOrEqual,
+  instanceOf,
+  typeOf,
 } from "./src/equality.ts";
 import {
   AssertionError,
@@ -43,3 +45,11 @@ export function assertLess(actual: unknown, expected: unknown): void {
 export function assertLessOrEqual(actual: unknown, expected: unknown): void {
   handleError(lessOrEqual(actual, expected));
 }
+
+export function assertInstanceOf(actual: unknown, expected: any): void {
+  handleError(instanceOf(actual, expected));
+}
+
+export function assertTypeOf(actual: unknown, expected: string): void {
+  handleError(typeOf(actual, expected));
+}

src/equality.ts

@@ -1,5 +1,5 @@
 import { Result, ok, err } from "https://deno.land/x/resulty/mod.ts";
-import { error } from "./message.ts";
+import { error, errorSimple } from "./message.ts";
 
 export function equals(actual: unknown, expected: unknown): Result<string> {
   if (actual === expected) {
@@ -44,3 +44,25 @@ export function lessOrEqual(actual: any, expected: any): Result<string> {
     error(actual, expected, "is not less than or equal to expected value"),
   );
 }
+
+export function instanceOf(
+  actual: unknown,
+  expected: any,
+): Result<string> {
+  if (actual instanceof expected) {
+    return ok(`${actual} is instance of ${expected}`);
+  }
+
+  return err(errorSimple(actual, expected, "is not an instance of"));
+}
+
+export function typeOf(
+  actual: unknown,
+  expected: string,
+): Result<string> {
+  if (typeof actual === expected) {
+    return ok(`${actual} is type of ${expected}`);
+  }
+
+  return err(errorSimple(actual, expected, "is not a type of"));
+}

src/message.ts

@@ -28,3 +28,17 @@ export function error(
     green(`"${getValueOrName(expected)}" type of ${typeof expected}.`),
   );
 }
+
+export function errorSimple(
+  actual: unknown,
+  expected: unknown,
+  text: string,
+): string {
+  let message: string = red(
+    `"${getValueOrName(actual)}"`,
+  );
+  message = message.concat(` ${text} `);
+  return message.concat(
+    green(`"${getValueOrName(expected)}".`),
+  );
+}

tests/equality.test.ts

@@ -6,6 +6,8 @@ import {
   greaterOrEqual,
   less,
   lessOrEqual,
+  instanceOf,
+  typeOf,
 } from "../src/equality.ts";
 
 Deno.test("Equals Boolean", () => {
@@ -67,3 +69,40 @@ Deno.test("Less or Equal Fail", () => {
 
   assertTrue(result.isError());
 });
+
+Deno.test("Instance Of", () => {
+  class Foo {}
+
+  const foo = new Foo();
+
+  const result: Result<string> = instanceOf(foo, Foo);
+
+  assertTrue(result.isOk());
+});
+
+Deno.test("Instance Of Fail", () => {
+  class Foo {}
+  class Bar {}
+
+  const foo = new Foo();
+
+  const result: Result<string> = instanceOf(foo, Bar);
+
+  assertTrue(result.isError());
+});
+
+Deno.test("Type Of", () => {
+  const hello = "World";
+
+  const result: Result<string> = typeOf(hello, "string");
+
+  assertTrue(result.isOk());
+});
+
+Deno.test("Type Of Fail", () => {
+  const hello = "World";
+
+  const result: Result<string> = typeOf(hello, "boolean");
+
+  assertTrue(result.isError());
+});

tests/message.test.ts

@@ -3,7 +3,7 @@ import {
   green,
 } from "https://deno.land/std/fmt/colors.ts";
 import { assertSame } from "../mod.ts";
-import { error } from "../src/message.ts";
+import { error, errorSimple } from "../src/message.ts";
 
 Deno.test("Create Message", () => {
   const actual = error(true, true, "equals");
@@ -37,3 +37,16 @@ Deno.test("Create Message With Functions", () => {
 
   assertSame(actual, expected);
 });
+
+Deno.test("Create Simple Message", () => {
+  class Foo {}
+  class Bar {}
+
+  const foo = new Foo();
+
+  const actual = errorSimple(foo, Bar, "is not instance of");
+  const expected = red(`"Foo"`) + " is not instance of " +
+    green(`"Bar".`);
+
+  assertSame(actual, expected);
+});

tests/mod.test.ts

@@ -14,6 +14,8 @@ import {
   assertGreaterOrEqual,
   assertLess,
   assertLessOrEqual,
+  assertInstanceOf,
+  assertTypeOf,
 } from "../mod.ts";
 
 Deno.test("Assert True", () => {
@@ -170,3 +172,101 @@ Deno.test("Assert Greater or Equal Fail", () => {
     message,
   );
 });
+
+Deno.test("Assert Instance Of", () => {
+  class Foo {}
+  const foo = new Foo();
+  assertInstanceOf(foo, Foo);
+});
+
+Deno.test("Assert Instance Of Fail", () => {
+  const message = red(`"Foo"`) +
+    " is not an instance of " +
+    green(`"Bar".`);
+
+  class Foo {}
+  class Bar {}
+  const foo = new Foo();
+
+  assertThrows(
+    (): void => {
+      assertInstanceOf(foo, Bar);
+    },
+    AssertionError,
+    message,
+  );
+});
+
+Deno.test("Assert Type Of", () => {
+  assertTypeOf(2, "number");
+});
+
+Deno.test("Assert Type Of Fail", () => {
+  const message = red(`"3"`) +
+    " is not a type of " +
+    green(`"string".`);
+
+  assertThrows(
+    (): void => {
+      assertTypeOf(3, "string");
+    },
+    AssertionError,
+    message,
+  );
+});
+
+Deno.test("Assert True Example", () => {
+  function isOlderThanFive(age: number): boolean {
+    return age >= 5;
+  }
+
+  const childAge: number = 6;
+
+  const result: boolean = isOlderThanFive(childAge);
+
+  assertTrue(result);
+});
+
+Deno.test("Assert Instance Of Example", () => {
+  interface Person {
+    name: string;
+    age: number;
+    location: string;
+  }
+
+  class Adult implements Person {
+    name: string;
+    age: number;
+    location: string;
+
+    constructor(name: string, age: number, location: string) {
+      this.name = name;
+      this.age = age;
+      this.location = location;
+    }
+  }
+
+  class Child implements Person {
+    name: string;
+    age: number;
+    location: string;
+
+    constructor(name: string, age: number, location: string) {
+      this.name = name;
+      this.age = age;
+      this.location = location;
+    }
+  }
+
+  function createPerson(name: string, age: number, location: string): Person {
+    if (age < 18) {
+      return new Child(name, age, location);
+    }
+
+    return new Adult(name, age, location);
+  }
+
+  const jenny = createPerson("Jenny Brown", 12, "US");
+
+  assertInstanceOf(jenny, Child);
+});