Skip to content
Test generators with ease
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore
.travis.yml
LICENSE.md
README.md
index.d.ts
index.js
package.json
prettier.config.js
test.js
yarn.lock

README.md

gen-tester Build Status

Test generators with ease

Why?

Testing generators is kind of a pain to do manually. Because of the way generators work, the order in which mock values are injected into a generator relates to the previous yield.

How?

const { call } = require('cosed'); // side-effects as data library
const test = require('tape');
const { genTester, yields } = require('gen-tester');

function* genCall() {
  const resp = yield call(fetch, 'http://httpbin.org/get');
  const data = yield call([resp, 'json']);
  return { ...data, extra: 'stuff' };
}

test('genCall', (t) => {
  t.plan(1);

  const respValue = { resp: 'value', json: 'hi' };
  const returnValue = { data: 'value', extra: 'stuff' };

  const tester = genTester(genCall);
  const { actual, expected } = tester(
    yields(
      call(fetch, 'http://httpbin.org/get'),
      respValue, // the result value of `resp` in the generator
    ),
    yields(
      call([respValue, 'json']),
      { data: 'value' }, // the result value of `data` in the generator
    ),
    returnValue,
  );

  t.deepEqual(actual, expected);
});

This is what the test would look like using a manual approach

test('genCall', (t) => {
  const gen = genCall();

  t.plan(4);

  t.deepEqual(
    gen.next().value,
    call(fetch, 'http://httpbin.org/get'),
    'should make http request',
  );

  const respValue = { resp: 'value', json: 'hi' };
  t.deepEqual(
    gen.next(respValue).value,
    call([respValue, 'json']),
    'should get json from response',
  );

  const last = gen.next({ data: 'value' });
  t.ok(last.done, 'generator should finish');
  t.deepEqual(last.value, { data: 'value' }, 'should return data');
});

API

genTester

genTester accepts a generator function and arguments to pass to generator and returns a function that accepts an array of yields, described below:

  • generator (generator function), the generator function to test
  • args (array, default: []), a list of arguments being called with generator
const tester = genTester(generator, arg1, arg2, ...);

tester which is the return value of genTester accepts an array of yields and returns a list of results from the generator at each step

  • yields (array, default: []), a list of yields that the generator will call with the value that will be the result of the yield as well as what was expected of that yield.
const { genTester, yields } = require('gen-tester');

const tester = genTester(someFn);
const results = tester(yields('each', 1), yields('yield', 2), 'and return');
console.log(results);
/*
{
  actual: ['each', 'yield', 'and return'],
  expected: ['each', 'yield', 'and return'],
}
*/

yields

yields is a helper function that will allow the user to send the expected results of a yield as well as the return value of that yield. This is primarily used to inject values into yields for mocking purposes.

  • expected (any), what we expect the yield to yield
  • returns (any), what we want the yield to yield for mocking

skip

skip is a helper function that will allow the user to skip a yield. The generator will progress to the next steps as normal, but we will not keep track of the results or expectations of that yield.

  • returns (any), what we want the yield to yield for mocking
const { skip } = require('gen-tester');

function* test() {
  yield 1;
  const resp = yield call(fetch, 'google.com');
  if (resp.status !== 200) {
    return;
  }
  const val = yield call([resp, 'json']);
  return val;
}

const results = tester(
  skip(),
  yields(call(fetch, 'google.com'), { status: 200 }),
  skip({ with: 'value' }),
  { with: 'value' },
);

throws

throws allows the developer to throw an exception inside a generator.

  • returns (any)
const assert = require('assert');
const { genTester, throws, skip } = require('gen-tester');

function* test() {
  let value = 1;
  try {
    yield 1;
  } catch (err) {
    value = 2;
    yield err + ' handled';
  }

  return value;
}

const tester = genTester(test);
const { actual, expected } = tester(
  yields(1, throws('ERROR')),
  yields('ERROR handled'),
  2,
);
console.log(actual, expected);

assert.deepEqual(actual, expected);

throws can also be used when something throws an exception between yields. When asserting that an exception is raised, you must pass it a function which will receive the error as an argument.

const assert = require('assert');
const { genTester, yields, throws } = require('gen-tester');

function* test() {
  yield 1;
  throw new Error('Something happened');
}

const tester = genTester(test);
const { actual, expected } = tester(
  yields(1);
  throws((error) => error.message === 'Something happened');
);
console.log(actual, expected);

assert.deepEqual(actual, expected);

finishes

finishes ensures that the last step is marked as done by the generator.

const { genTester, finishes } = require('gen-tester');

test('generator finished with finishes', (t) => {
  t.plan(1);

  function* fn() {
    yield 1;
    yield 2;
    return 3;
  }

  const tester = genTester(fn);
  const { actual, expected } = tester(1, 2, finishes(3));
  t.deepEqual(actual, expected);
});

evaluateSteps

evaluateSteps is a helper that takes the results of genTester and determines what steps are no equal and displays more useful information.

const { genTester } = require('gen-tester');
const deepEqual = require('fast-deep-equal');

function* fn() {
  yield 1;
  yield 2;
  return 3;
}

const tester = genTester(fn);
// message gets called when a step is not equal
const message = (actual, expected, index) => {
  return `error on step ${index + 1}:

  actual: ${actual}
  expected: ${expected}`;
};
const { actual, expected } = tester(1, 4, 3);
const results = evauluateSteps({ actual, expected, equal: deepEqual, message });
console.log(results);
/*
{
  message: [Function: message],
  pass: false,
  actual: 2,
  expected: 4,
}
*/

stepsToBeEqual

stepsToBeEqual is a jest matcher that uses evaluateSteps

const { genTester, stepsToBeEqual } = require('gen-tester');

expect.extend({
  stepsToBeEqual,
});

function* fn() {
  yield 1;
  yield 2;
  return 3;
}

const tester = genTester(fn);
const results = tester(1, 2, 3);
expect(results).stepsToBeEqual();
You can’t perform that action at this time.