merlin@v1.0.6

Testing and Benchmarking framework for deno 🧙‍♂️

Merlin

Merlin is a Jest-inspired testing framework for deno.

Using Matchers

Common Matchers

assertEqual(label: string, config)
assertNotEqual(label: string, config)
evalEquals(testEqual[])
stringContains(label: string, config)
arrayContains(label: string, config)
beNull(label: string, config)
beFalsy(label: string, config)
beTruthy(label: string, config)

All Matchers

assertEqual(label: string, config) Compare two values and throws an error if the expect and toBe are not equal
assertNotEqual(label: string, config) Compare two values and throws an error if the expect and notBe are equal
evalEquals(testEqual[]) evaluate multiple equality tests in an array. If the data is not the same it throws an error
fetchEqual(label: string, config) evaluate if two values are equal. If the request data is not the same as expected, it throws an error
arrayContains(label: string, config) evaluates that the array contains an specific data. if the array does not contain the data it throws an error
stringContains(label: string, config) evaluates if a string contains an specific word. if the string does not contain the word it throws an error
beNull(label: string, config) evaluates if a data is null
beFalsy(label: string, config) evaluates if a data is a falsy value
beTruthy(label: string, config) evaluates if a data is a truthy value
isBigInt(label: string, config) evaluates if a data is a bigInt value type
isZero(label: string, config) evaluates if a data is a Zero
isNaN(label: string, config) evaluates if a data is NaN value
sameLength(label: string, config) evaluates if data has a specific length
assertRegExp(label: string, config) evaluates if a regular expression match
isFunction(label: string, config) evaluates if a data is a function
isSymbol(label: string, config) evaluates if a data is a symbol
isUndefined(label: string, config) evaluates if a data is undefined
isString(label: string, config) evaluates if a data is string
isNumber(label: string, config) evaluates if a data is number
isEmpty(label: string, config) evaluates if a data is empty
assertSame(label: string, config) evaluates if two values are strictly the same
assertGreaterOrEqual(label: string, config) evaluates whether the expected data is greater than or equal to another
assertGreater(label: string, config) evaluates whether the expected data is greater than another
assertLess(label: string, config) evaluates if the expected data is less than another
assertLessOrEqual(label: string, config) evaluates if the expected data is less than or equal to another
assertInstanceOf(label: string, config) evaluates that one object is an instance of another
assertFloat(label: string, config) evaluates if two decimal numbers are equal
assertThrows(label: string, config) expect it throws an error
assertThrowsSync(label: string, config) expect it throws an async error
haveProperty(label: string, config) expect an object to contain the properties in its value

Statics

Merlin.Error(msg?: string) force to throw an error
Merlin.Unimplemented(msg?: string) Use this to throw a method not implemented error
Merlin.Unreachable() Use this to throw an Unreachable method error

Install Merlin

install merlin-cli (optional)

deno install --allow-run -n merlin https://deno.land/x/merlin/cli.ts

Mirrors

you can get Merlin from different url.

from deno.land/x

import { Merlin } from "https://deno.land/x/merlin/mod.ts";

from nest.land

import { Merlin } from "https://x.nest.land/merlin@<version>/mod.ts";

from github repo

import { Merlin } from "http://denopkg.com/crewdevio/merlin/mod.ts";

Basic Use

simple assertions.

example.test.ts

import { Merlin } from "https://deno.land/x/merlin/mod.ts";

const test = new Merlin();

test.assertEqual("two plus two is four", {
  expect() {
    return 2 + 2;
  },
  toBe() {
    return 4;
  },
});

run this test in deno.

merlin start

deno test

you should see this output on the console.

running 1 tests
test two plus two is four ... ok (17ms)

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out (18ms)

Parameters

all assertions have parameters that they can receive, these parameters can change the behavior of the tests.

label add a description to the test.
expect() this function returns the data and then tests with its matchmaker.
toBe() this function returns the data that we hope is correct.
notBe() this function returns the data that we hope it is incorrect.
value() returns the data expected to be of that type.
ignore (optional) receives a boolean to ignore the test in case the value is true.
strict (optional) receives a boolean, it does a strict comparison of the expect() and toBe() values.
message (optional) receives a string with the message to display in case the test fails.
Ops (optional) receives a boolean, closes all the operations that never end, for example Deno.open("file.txt"). by default is true.
Resources (optional) receives a boolean, terminates all asynchronous processes that interact with the system. by default is true.
only (optional) receives a boolean, only tests that have only in true will be executed, the rest will not run.

about resources and ops sanitizers

Certain actions in Deno create resources in the resource table . 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.

async function writeSomething(): Promise<string> {
  const decoder = new TextDecoder("utf-8");
  Deno.createSync("./texts.txt");
  const Package = await Deno.readFileSync("./text.txt");
  await Deno.writeTextFile("./text.txt", "test");
  return decoder.decode(Package);
}

test.assertEqual("Leak resources test", {
  expect: async () => await writeSomething(),
  toBe: () => "test",
  only: true,
  Ops: false,
  Resources: false,
});

merlin start

test Leak resources test ... ok (5ms)

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Multiple tests

example.test.ts

test.evalEquals([
  {
    label: "object assignment",
    expect() {
      const data: any = { one: 1 };
      data["two"] = 2;

      return data;
    },
    toBe() {
      return { one: 1, two: 2 };
    },
  },
  {
    label: "two plus two is four",
    expect() {
      return 2 + 2;
    },
    toBe() {
      return 4;
    },
  },
]);

output

merlin start

running 2 tests
test object assignment ... ok (10ms)
test two plus two is four ... ok (1ms)

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out (13ms)

notEqual

example.test.ts

test.assertNotEqual("two plus two not is five", {
  expect() {
    return 2 + 2;
  },
  notBe() {
    return 4;
  },
});

output

merlin start

running 1 tests
test two plus two not is five ... FAILED (2ms)

failures:

two plus two not is five
AssertionError: actual: 4 expected: 4
    at assertNotEquals (https://deno.land/std/testing/asserts.ts:195:5)
    at fn (merlin.ts:105:9)
    at async asyncOpSanitizer ($deno$/testing.ts:34:5)
    at async Object.resourceSanitizer [as fn] ($deno$/testing.ts:68:5)
    at async TestRunner.[Symbol.asyncIterator] ($deno$/testing.ts:276:11)
    at async Object.runTests ($deno$/testing.ts:364:20)

failures:

        two plus two not is five

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out (2ms)

stringContains

example.test.ts

test.stringContains("hello world contains world", {
  Contains: () => "world",
  value: () => "Hello World",
});

merlin start

test hello world contains world ... ok (8ms)

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

fetchEqual

test.fetchEqual("fetch data", {
  url: "https://jsonplaceholder.typicode.com/todos/1",
  type: "json",
  toBe() {
    return { userId: 1, id: 1, title: "delectus aut autem", completed: false };
  },
});

merlin start

test fetch data ... ok (1440ms)

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

testRegExp

test.assertRegExp("regEx match", {
  expect: () => "https://google.com",
  toBe: () => new RegExp("^https?://[a-z.]+.com$"),
});

merlin start

test regEx match ... ok (6ms)

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out (342ms)

Using async code.

you can use asynchronous code by adding async in expect, toBe and value functions.

example

const test = new Merlin();

test.assertEqual("get error 404", {
  async expect() {
    const response = await fetch("https://deno.land/std/example/examples.ts");

    const data = response.text();

    return data;
  },
  toBe() {
    return "404: Not Found";
  },
});

Note: all the methods of the merlin class support async function since they have top level await

merlin gif

Create benchmarks using Maven

Maven is a benchmark tool for deno included in Merlin.

It’s easy to use. example:

import { Maven } from "https://deno.land/x/merlin/mod.ts";

const benchmark = new Maven();

benchmark.Bench({
  name: "Sorting arrays",
  fn: () => {
    new Array(10000).fill(Math.random()).sort();
  },
  steps: 1000,
});

benchmark.runBench();

this is the terminal output

gif

Parameters

maven receives the following parameters.

name: string benchmark name
fn(): void function that contains the code
steps: number number of times to repeat the benchmark

you can see the details at the end of the benchmark using

import { Maven } from "https://deno.land/x/merlin/mod.ts";

const benchmark = new Maven();

benchmark.Bench({
  name: "Sorting arrays",
  fn: () => {
    new Array(10000).fill(Math.random()).sort();
  },
  steps: 1000,
});

benchmark.runBench().then(benchmark.Result());

It has a table with the detailed values

▒▒▒▒▒▒▒▒ Benchmarking finished

┌───────────────────────────────────────────────────────────────────────────────────────────┐
│    Benchmark name:  Sorting array                                                         │
├───────────────────────┬──────────────────────────────┬────────────────────────────────────┤
│    Total runs: 1000   │  Total time: 1099.6591 ms    │  Avg time: 1.0997 ms               │
├───────────────────────┼────────────────────┬─────────┴───────────┬────────────────────────┤
│    min: 0.7768 ms     │ max: 9.9867 ms     │ mean: 5.3817 ms     │ median: 0.8511 ms      │
├───────────────────────┴────────────────────┴─────────────────────┴────────────────────────┤
│    Thresholds:  0 ========== 70 ========== 90 ========== ∞                                │
├───────────────────────────────┬───────────────────────────────────────────────────────────┤
│                               │                                                           │
│    0.7768 ms _[   965][96.5%] │========================================================   │
│    2.6188 ms _[    33][ 3.3%] │==                                                         │
│    4.4608 ms _[     1][ 0.1%] │=                                                          │
│    6.3027 ms _[     0][   0%] │                                                           │
│    8.1447 ms _[     1][ 0.1%] │=                                                          │
│                               │                                                           │
└───────────────────────────────┴───────────────────────────────────────────────────────────┘

Contributing

contributions are welcome, create a pull request and send us your feature, first check the CONTRIBUTING GUIDELINES.

Testing and Benchmarking framework for deno 🧙‍♂️

Merlin

Using Matchers

Common Matchers

All Matchers

Statics

Install Merlin

Mirrors

Basic Use

Parameters

about resources and ops sanitizers

Multiple tests

notEqual

stringContains

fetchEqual

testRegExp

Using async code.

Create benchmarks using Maven

Parameters

Contributing

LICENSE MIT