🧐 cynic

async testing framework for es modules

• cynic is designed to be dirt-simple, because i'm sick of overcomplicated testing frameworks
• the test suites are just nested async functions
• the whole framework is just simple es modules that run anywhere: node, browser, puppeteer, deno
• no magic assumptions are made about or foisted onto the environment: the assertion library and everything else is just simply imported like from any other module
• examples here are shown in typescript, but of course you can use vanilla js

let's get cynical, and make a damn test suite!

1. install cynic into your project

   1npm install --save-dev cynic

2. write a test suite, example.test.ts

   1import {Suite, assert, expect} from "cynic"
   2
   3export default <Suite>{
   4  "alpha system": {
   5    "can sum two numbers (boolean return)": async() => {
   6      const a = 1
   7      const b = 2
   8      // no assertion library required:
   9      // simply returning false, or throwing, will fail a test
   10      return (a + b) === 3
   11    },
   12    "can sum three numbers (assert)": async() => {
   13      const a = 1
   14      const b = 2
   15      const c = 3
   16      // benefits of 'assert'
   17      //  - you get a stack trace
   18      //  - you can provide a custom message for each failure
   19      assert((a + b + c) === 6, `sum is wrong`)
   20    }
   21  },
   22  "bravo system": {
   23    "can multiply numbers (expect)": async() => {
   24      const a = 2
   25      const b = 3
   26      // benefits of 'expect'
   27      //  - you get a stack trace
   28      //  - cynic tries to invent a message about the failure
   29      expect(a * b).equals(6)
   30      expect(a * b * a).equals(12)
   31    }
   32  }
   33}

now run it!

• you can run the suite file through the cynic cli

  1# run your tests in node
  2cynic node example.test.js
  3
  4# run your tests in browser
  5cynic browser example.test.js
  6
  7# run your tests in puppeteer (headless browser)
  8cynic puppeteer example.test.js
  9
  10# use node debugger
  11node inspect node_modules/cynic/dist/cli.js node example.test.js

  cynic executes the default export as a test suite

  optional arguments for all runtimes:

  • --label="test suite" — the report title

  optional arguments for browser and puppeteer runtimes:

  • --open=false — true to prompt open your default browser
  • --port=8021 — run the server on a different port
  • --origin="http://localhost:8021" — connect to the server via an alternative url (mind the port number!)
  • --cynic-path=node_modules/cynic — use an alternative path to the cynic library's root
  • --importmap-path=./dist/importmap.json — provide an import map for your test suites

  if puppeteer isn't running properly, see puppeteer's troubleshooting.md

• or you can just execute your test suite, manually, anywhere

  this should work anywhere you can import an es module

  1import {test} from "cynic"
  2import suite from "./example.test.js"
  3
  4;(async() => {
  5
  6  // run the test suite
  7  const {report, ...stats} = await test("example suite", suite)
  8
  9  // emit the report text to console
  10  console.log(report)
  11
  12  // handle results programmatically
  13  if (stats.failed === 0) console.log("done")
  14  else console.log("failed!")
  15
  16  // returns stats about the test run results
  17  console.log(stats)
  18
  19})()

  see which stats are available in the Stats interface in types.ts

so what do the console reports look like?

• report: successful run

  cynic example suite
  
    ▽ examples
      ▽ alpha system
        ✓ can sum two numbers (boolean return)
        ✓ can sum three numbers (assertion)
      ▽ bravo system
        ✓ can multiply numbers (expectation)
  
  0 failed tests
  0 thrown errors
  3 passed tests
  3 total tests
  0.00 seconds
  

• report: a test returns false
  return false to indicate a failed test

  cynic example suite
  
    ▽ examples
      ▽ alpha system
  
  ═════ ✘ can sum two numbers (boolean return)
  
      ▽ bravo system
  
  ✘ can sum two numbers (boolean return) — failed
  
  1 FAILED tests
  0 thrown errors
  2 passed tests
  3 total tests
  0.00 seconds
  

• report: a test throws
  a thrown string or error will be shown as the failure reason

  cynic example suite
  
    ▽ examples
      ▽ alpha system
  
  ═════ ✘ can sum two numbers (boolean return)
  ――――――― arithmetic failed for interesting reasons
  
      ▽ bravo system
  
  ✘ can sum two numbers (boolean return) — arithmetic failed for interesting reasons
  
  1 FAILED tests
  1 thrown errors
  2 passed tests
  3 total tests
  0.00 seconds
  

• report: a test fails an assertion
  assertions will display a stack trace, and optional custom message

  cynic example suite
  
    ▽ examples
      ▽ alpha system
  
  ═════ ✘ can sum three numbers (assertion)
  ――――――― CynicBrokenAssertion: sum is wrong
            at assert (file:///work/cynic/dist/assert.js:7:15)
            at can sum three numbers (assertion) (file:///work/cynic/dist/internals/example.test.js:13:20)
            at execute (file:///work/cynic/dist/internals/execute.js:13:34)
            [...]
  
      ▽ bravo system
  
  ✘ can sum three numbers (assertion) — CynicBrokenAssertion: sum is wrong
  
  1 FAILED tests
  1 thrown errors
  2 passed tests
  3 total tests
  0.00 seconds
  

• report: a test fails an expectation
  stack trace is provided, and a failure reason is generated automatically

  cynic example suite
  
    ▽ examples
      ▽ alpha system
      ▽ bravo system
  
  ═════ ✘ can multiply numbers (expectation)
  ――――――― CynicBrokenExpectation: expect(7).equals(6): not equal, should be
            at composite (file:///work/cynic/dist/expect.js:46:19)
            at Object.equals (file:///work/cynic/dist/expect.js:25:125)
            at can multiply numbers (expectation) (file:///work/cynic/dist/internals/example.test.js:20:39)
            at execute (file:///work/cynic/dist/internals/execute.js:13:34)
            [...]
  
  ✘ can multiply numbers (expectation) — CynicBrokenExpectation: expect(7).equals(6): not equal, should be
  
  1 FAILED tests
  1 thrown errors
  2 passed tests
  3 total tests
  0.00 seconds
  

hot tips for big brains

• use object nesting to group and organize tests arbitrarily

  1import {Suite} from "cynic"
  2export default <Suite>{
  3  "nested tests": {
  4    "more nested": {
  5      "exceedingly nested": {
  6        "it works": async() => true
  7      }
  8    }
  9  }
  10}

• you can just throw strings as assertions

  1import {Suite} from "cynic"
  2export default <Suite>{
  3  "assertions and expectations": async() => {
  4    const example = "abc"
  5
  6    // let's call it "the spartan assertion"
  7    if (!example.includes("b"))
  8      throw `expected example to include "b"`
  9
  10    return true
  11  }
  12}

• or you can use the handy assert function to do that, you get stack traces

  1import {Suite, assert} from "cynic"
  2export default <Suite>{
  3  "using 'assert'": async() => {
  4    const example = "abc"
  5    assert(example === "abc", `example must equal "abc"`)
  6    assert(example.includes("b"), `example should include "b"`)
  7  }
  8}

• or you can also use the experimental new expect api, you get auto-generated messages and stack traces

  1import {Suite, expect} from "cynic"
  2export default <Suite>{
  3  "using 'expect'": async() => {
  4    const example = "abc"
  5    expect(example).defined()
  6    expect(example).equals("abc")
  7  }
  8}

• a suite or test can return another suite or test — easy setups!

  1export default <Suite>(async() => {
  2
  3  // doing some async setup
  4  const myFile = await loadFile("myfile.json")
  5
  6  // returning more tests
  7  return {
  8    "group of tests": {
  9      "my file exists": async() => {
  10        return !!myFile
  11      }
  12    }
  13  }
  14})

food for thought

• 🥃 chase moskal made this with open source love. please contribute!