Skip to content

Releases: Minivera/testifyjs

Build the package

06 Apr 18:42
Compare
Choose a tag to compare

Package was not built when running the release actions, it should now be correctly package and published.

Correct module transpilation

06 Apr 18:37
Compare
Choose a tag to compare

The module configuration when building with TypeScript was configured to output ESNext modules. Since this a node package, commonJS modules need to be outputted instead. This patch version bump fixes this issue and enables the usage of the package in node.

Initial release

08 Jan 19:00
ebfb642
Compare
Choose a tag to compare

Testifyjs

codecov
Pull Request validation

Testify is a unit-testing framework for JavaScript and TypeScript providing and recognizable experience, but with added
simplicity, clarity, and reusability. Written in TypeScript, Testify can be integrated in any project without having
to learn a separate CLI and configuration system. Just load testify and execute your script with node!

Why another testing framework?

I was relatively unhappy with how much magic and configuration goes into the average testing framework. I wanted
to experiment with a framework where I can focus on writing simple and reusable code without any headaches. A test
framework should not a challenge to use, understand, or implement, I wanted to know if an alternative was possible.

Another major difficulty I have with testing framework is the lack of a traditional unit test structure. It leads
to big tests where it gets hard to find where the data is set, where the test is executed, and where the data is
checked. I've always been a fan of the Arrange-Act-Assert
structure for unit tests, and I wanted to see if a framework would be built around this standard.

Testify is not an attempt at revolutionizing the way people write tests in JavaScript, nor is it a killer. It's a small project I designed to answer the above questions. I hope you will enjoy trying
out testify for yourself and seeing if it helps you write better tests.

Why use Testify?

  • Very small library and API
  • Built with TypeScript, for TypeScript
  • Asynchronous support out of the box
  • Support for test suites
  • No magic or global injected variables, everything is imported or provided
  • Bring your own assertion framework or mocking library
  • All tests are sequential
  • Encourages writing small testing helpers over massive test methods (Arrange-Act-Assert)
  • No CLI, bring your own node and run testify with your configuration

How to use

To get started, install testify using NPM

npm install @minivera/testifyjs

Create a main test file somewhere in your code base, import testify, and run it.

import { testify, test } from '@minivera/testifyjs';

// Create a single test
test('Hello, World!', test => {
  test
    // Arrange your data before acting
    .arrange(() => ({
      message: '',
    }))
    // Update the data based on what you are testing
    .act(({ message }) => ({
      message: 'Hello, World!'
    }))
    // Assert that the actions executed properly
    .assert(({ message }) => {
      if (message !== 'Hello, World!') {
        throw new Error('Message should be "Hello, World!"');
      }
    });
});

// Run all the tests in the order they were created
await testify();

Execute this script with node and let testify take over.

node test.js

TypeScript support

Testify was built in TypeScript, for TypeScript. Here is the same example, but built in TypeScript.

import { testify, test } from '@minivera/testifyjs';

test('Hello, World!', test => {
  interface Input {
    message: string;
  }
    
  test
    // First generic is the type of the parameter, second is the return type
    .arrange<{}, Input>(() => ({
      message: '',
    }))
    .act<Input>(({ message }) => ({
      message: 'Hello, World!'
    }))
    .assert<Input>(({ message }) => {
      if (message !== 'Hello, World!') {
        throw new Error('Message should be "Hello, World!"');
      }
    });
});

await testify();

All the type definitions are available directly form the main testify import.

Asynchronous code

Async methods are supported by default, simply create a function returning a promise or an async function, and testify
will make sure to execute the code synchronously.

import { testify, test } from '@minivera/testifyjs';

const someApiCall = async (body: string) => {
  return await fetch('somewhere', body);  
};


test('async test', test => {
  interface Input {
    body: string;
  }
  
  interface Output {
    body: string;
    result: string;
  }
    
  test
    .arrange<{}, Input>(() => ({
      body: JSON.stringify({}),
    }))
    .act<Input, Output>(async ({ body }) => {
        const result = await someApiCall(body);
        return {
            body,
            result,
        };
    })
    .assert<Output>(({ result }) => {
      if (result !== 'Hello, World!') {
        throw new Error('Message should be "Hello, World!"');
      }
    });
});

await testify();

Triggering a test failure

At any point in you tests, you may throw an error to trigger a test failure. Testify will gracefully report the error
and report the test failure.

import { testify, test } from '@minivera/testifyjs';

test('failing test', test => {
  const triggerError = () => {
      throw new Error('test');
  };
    
  test
    .arrange(triggerError)
    .act(triggerError) // Will never be executed
    .assert(triggerError); // Will never be executed
});

await testify();

Using suites

Testify supports test suites to better organize tests or trigger specific behavior before and after tests.

import { testify, suite } from '@minivera/testifyjs';

suite('test suite', suite => {
  suite.setup(() => {
    // Will be executed when the suite starts, may be async
  });
  
  suite.tearDown(() => {
    // Will be executed when the suite ends, may be async
  });
  
  suite.beforeEach(() => {
    // Will be executed before every test or nested test suite, may be async
  });

  suite.afterEach(() => {
    // Will be executed after every test or nested test suite, may be async
  });
    
  // Can run individual test, they will be printed as part of the suite
  suite.test('test', test => {
    test
      .arrange(someArrange)
      .act(someAct)
      .assert(someAssert);
  });

  // Suites can be freely nested
  suite.suite('nested', suite => {
    // ...
  });
});

await testify();

Tests in multiple files

testify will execute all registered tests at the moment it's run. You can divide your tests into multiple files
by using the node module system. Make sure to call testify after you import all your tests.

// somefile.ts
import { test } from '@minivera/testifyjs';

test('some test', () => { /* ... */ });

// test.ts
import './somefile';

await testify();

API

The test function

import { test } from '@minivera/testifyjs';

test takes two arguments, a name to be displayed when executing the test, and a test configuration function. The
function receives the test object as its only parameter.

The suite function

import { suite } from '@minivera/testifyjs';

suite takes two arguments, a name to be displayed when executing the suite's test, and a suite configuration function.
The function receives the suite object as its only parameter.

The testify function

import { testify } from '@minivera/testifyjs';

testify executes all the tests saved up to this point.

The Test object

test('name', test => { /* test is your test object */});

The test object is used to configure a single test. By itself, the test configuration function does nothing, we
need to provide it with test units.

test.arrange takes a function as its parameter. This function will have the return value from the previous function
in the chain as its parameter. A function may not return anything, in which case the return value from the previous
chain is used as the return value. The first function receives an empty object as its parameter.

In TypeScript, the two generic parameters can be used to add type definitions to the input parameters and the output
value. The second generic can be omitted, it will use the first value by default.

For example:

import { test } from '@minivera/testifyjs';

test('some test', test => {
  interface A {
    test: number;
  }

  interface B {
    test: string;
  }
    
  test.arrange<{}, A>(params => {
    // params is {}
    return {
      test: 1,
    };
  }).arrange<A>(params => {
    // params is { test: 1 }
  }).arrange<A, B>(params => {
    // params is still { test: 1 }
    return {
      test: `${params.test}`,
    }
  })
});

arrange, act, and assert may be called as a chain to continue configuring this single test. and is also
available as syntactic sugar to call arrange multiple times.

test.act is identical to test.arrange, with the difference that only act and assert are available for chaining
and is still available as syntactic sugar to call act multiple times.

test.act is identical to test.act, with the difference that only assert is available for chaining
and is still available as syntactic sugar to call assert multiple times.

All functions provided to arrange, act, and assert may be async or return a promise. All steps will be executed
sequentially and async methods will be await-ed.

The Suite object

suite('name', suite => { /* suite is your suite object */});

The suite object is used to configure a test suite. The suite function does nothing if the suite is not configured
by calling its methods. It also provides hooks to prepare data before or after the execution of the suites or individual
tests.

The suite.setup hook takes a function as its single parameter and will set that function to be execu...

Read more