Releases: Minivera/testifyjs
Build the package
Correct module transpilation
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
Testifyjs
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...