given3 v1.4.0
Given3
Given3 makes the process of testing better by allowing you to define lazily computed values that are scoped to individual tests or suites.
Given3 is designed to work with Jest, Mocha, and Jasmine
installation
Install via NPM npm install given3 or Yarn yarn add given3
Upgrading from given2
In order to ease the process of upgrading from the given2 library (https://www.npmjs.com/package/given2) a compatibility layer is provided. Simply replace:
import given from 'given2';with
import { given2 as given } from 'given3';Usage
Use the given function import { given } from 'given3';
Calling the function you may either call it without arguments to create an non-defined given or call it with a definition function to set an initial value.
const givenWithoutValue = given<number>(); // no value currently, will throw an error if referenced.
const givenWithValue = given(() => 0); // has the value of 0The given object has a property value that lazily computes and returns the value of the given.
const givenWithValue = given(() => 0);
it('has value of 0', () => {
expect(givenWithValue.value).toBe(0);
});The given value is cached so repeated accesses within a test will not recompute the value;
const givenWithRandomValue = given(() => Math.random());
it('is cached', () => {
expect(givenWithRandomValue.value).toBe(givenWithRandomValue.value);
});You an update the value of a given using the define method to define a new value for it
const givenWithValue = given(() => 0);
describe('given the value is 1', () => {
// within the scope of the current define block the given will be 1
givenWithValue.define(() => 1);
it('the value is one', () => {
expect(givenWithValue.value).toBe(1);
});
});
it('the value is zero', () => {
expect(givenWithValue.value).toBe(0);
});Examples
An inputs and outputs
Using given3 you can define stubs for values and define, or re-define the values later. This allows you to for-instance create givens for the inputs to your system, and vary the inputs in tests.
import { given } from 'given3';
describe('Math.min', () => {
// input stubs have no value initially
const input1 = given<number>();
const input2 = given<number>();
// lazily evaluated result won't be evaluated until the value is referenced
const result = given(() => Math.min(input1.value, input2.value));
describe('given input1 is 0', () => {
input1.define(() => 0);
describe('given input 2 is 0', () => {
input2.define(() => 0);
it('has a result of zero', () => {
expect(result.value).toBe(0);
});
});
describe('given input 2 is 1', () => {
input2.define(() => 1);
it('has a result of zero', () => {
expect(result.value).toBe(0);
});
});
describe('given input 2 is smaller than input 1', () => {
// you can define one given with respect to another
input2.define(() => input1.value - 1);
it('has a result equal to input2', () => {
expect(result.value).toBe(input2.value);
});
});
});
});value refining
It is often useful to be able to reference the previously defined value to refine it. Within the definition of a value simply referencing the given will return the previously defined value.
import { given } from 'given3';
describe('Math.min', () => {
const input = given<number[]>(() => []);
const result = given(() => Math.min(...input.value));
describe('given the input includes 1', () => {
// define input as the previous value
input.define(() => [...input.value, 1]);
it('the result is 1', () => {
expect(result.value).toBe(1);
});
describe('given the input includes 0', () => {
// further add to the input
input.define(() => [...input.value, 0]);
it('the result is 0', () => {
expect(result.value).toBe(0);
});
});
});
});The .refine method is a more readable way of doing this
import { given } from 'given3';
describe('Math.min', () => {
const input = given<number[]>(() => []);
const result = given(() => Math.min(...input.value));
describe('given the input includes 1', () => {
// define input as the previous value
input.refine((value) => [...value, 1]);
it('the result is 1', () => {
expect(result.value).toBe(1);
});
describe('given the input includes 0', () => {
// further add to the input
input.refine((value) => [...value, 0]);
it('the result is 0', () => {
expect(result.value).toBe(0);
});
});
});
});cleanup
While we try to avoid side effects in our tests practically there are times when things may need to be cleaned up after our tests are run.
Use the cleanUp method to define any cleanups that need to be done.
import { given } from 'given3';
import { Database } from '../database';
import { service } from '../service';
describe('API', () => {
// define a cleanup function
const db = given(() => new Database()).cleanUp((db) => db.shutDown());
const api = given(() => service({ db: db.value }));
it('stores a user', () => {
expect(api.value.put({ user: true })).toEqual({ success: true });
});
});Advanced Features
Scope
Options: 'Each' | 'All'
Default: 'Each' for define, 'All' for cleanUp
Specifies when the cache will be released, or when the cleanup function will run. Use the 'All' scope to define a value that caches for the whole suite, useful for givens that initialize external resources.
Immediate
Option: boolean
Default: false
If true the value will be computed and cached before the test is run.
Cache
Options: boolean | 'smart'
Default: true
If false no value will be cached on reads. If the value is smart then smart caching will be enabled.
Smart Caching
When the cache argument is set to 'smart' smart caching is enabled. A smart cached value will be evicted if any of the given values that are referenced in the definition have changed since the cached value was computed. As an example using an API:
import { given } from 'given3';
import { service } from '../service';
describe('API Calls', () => {
// mark cacheScope as All to ensure that a consistent object is returned
// until the value is redefined.
const arguments = given(() => ({ id: '1234' }), { cacheScope: 'All' });
// smart cached value for the service response
const result = given(() => service.invoke(arguments.value), {
cacheScope: 'All',
cache: 'smart'
});
// service result will be re-used here because the cacheScope is All and arguments haven't changed
it('has a positive result', async () => {
await expect(result.value).resolves.toHaveProperty('status', 200);
});
it('has a response body', async () => {
await expect(result.value).resolve.toHaveProperty('body', expect.any(String));
});
describe('given a missing id', () => {
// override the value of arguments, trigger smart cache eviction of result.
arguments.define(() => ({ id: 'not-found' }));
it('has a missing result', async () => {
await expect(result.value).resolves.toHaveProperty('status', 404);
});
});
});Factories
Factories are a way to package a set of reusable object constructors.
Create a Factory
use the factory function to create a factory
import { factory } from 'given3';
export const userFactory = factory(() => ({
id: factory.seq() // sequence returns a sequential numeric id
}));Using a Factory
factories are constructor functions and can be plugged directly into given
import { userFactory } from './factories';
import { given } from 'given3';
describe('given a user', () => {
const user = given(userFactory);
});Modifying the Factory Result
Use the .merge method to modify the result of the factory for your specific needs. Merge supports
a deep merge algorithm that allows setting partial values deep in the object structure.
import { userFactory } from './factories';
import { given } from 'given3';
describe('given a user', () => {
const user = given(userFactory.merge({ id: 0 }));
});Generating a List
Use the .list property to return a list of items
import { userFactory } from './factories';
import { given } from 'given3';
describe('given a userList', () => {
const userList = given(userFactory.list);
const longUserList = given(userFactory.list.of(100)); // specify the length of the list
});Refine the Value with Using
the .using property on a factory creates a refiner that can refine an existing value.
import { userFactory } from './factories';
import { given } from 'given3';
describe('given a user', () => {
const user = given(userFactory);
const userList = given(userFactory.list);
describe('given the id is 0', () => {
user.refine(userFactory.using.merge({ id: 0 }));
userList.refine(userFactory.using.merge({ id: 0 }).list.of(1)); // refine entries and length
});
});Capture a Set of Refinements as a Trait
You can capture refinements as a trait on a specific factory
// factories.ts
import { factory } from 'given3';
export const userFactory = factory(() => ({ id: factory.seq() }))
.using.merge({ id: 0 })
.as('admin');// test.ts
import { userFactory } from './factories';
import { given } from 'given3';
describe('given an admin user', () => {
const user = given(userFactory.admin); // can also refine with userFactory.using.admin
});Extending a Factory
Factories can extend other factories, inheriting their constructor and traits.
import { factory } from 'given3';
export const userFactory = factory(() => ({ id: factory.seq() }))
.using.merge({ id: 0 })
.as('admin');
export const expertUserFactory = factory.extends(userFactory, (user) => ({
...user,
expertIn: 'Testing'
}));Extending Traits
It can be useful to extend a trait when extending a factory, you can do this by first invoking the trait as part of the trait definition.
export const expertUserFactory = factory
.extends(userFactory, (user) => ({
...user,
expertIn: 'Testing'
}))
.using.admin.merge({ expertIn: 'Admin-ing' })
.as('admin'); // admin will be redefined and capture the userFactory transform.