# test-when-it

> Adds 'When' syntax to Mocha for more expressive test setups.

Latest version **1.1.0** (published 2016-11-16) · UNLICENSED license · 0 weekly downloads

## Install

```sh
npm install test-when-it
pnpm add test-when-it
yarn add test-when-it
bun add test-when-it
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2016-11-16 |
| First published | 2016-10-14 |
| Weekly downloads | 0 |
| License | UNLICENSED |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Jeff Valore |
| Maintainers | codingwithspike |
| Keywords | mocha, mochajs, jasmine, testing, unit-testing |

## Links

- npm: https://www.npmjs.com/package/test-when-it
- Repository: https://github.com/rally25rs/test-when-it
- Homepage: https://github.com/rally25rs/test-when-it#readme
- Issues: https://github.com/rally25rs/test-when-it/issues
- npm.io page: https://npm.io/package/test-when-it

## Alternatives

- [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads
- [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads
- [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads
- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads

## Recent versions

- 1.1.0 (latest) — 2016-11-16
- 1.0.1 — 2016-10-14
- 1.0.0 — 2016-10-14

## README

## WhenIt / ThenIt syntax for JS unit tests.

Works with Mocha or Jasmine test frameworks.

The intent is to provide a way to make small reusable functions that are used between several tests, without having to duplicate code between tests. It also provides a way to move test names from plain strings into function names.

# Installation

Get the files.

> npm install when-it --save-dev

Add to your test environment.

```
require('when-it');

// or with a regular script tag

<script src="node_modules/test-when-it/index.js" type="text/javascript"></script>
```

# Use

## setIt(propertyName, propertyValue)

This function assignes a property getter with the name `propertyName` to the `this` context. The property is deleted after each test.

The `propertyValue` parameter can be a literal value, or a function. If a function is passed, it is called each time the property is accessed and the return value is used as the property value (like a property getter). (The value is _not_ memoized like Ruby/rspec's `let()`)

```
describe('using setIt', function() {
	setIt('fromLiteral', 'valueFromLiteral');

	setIt('fromFunc', function() {
		return 'valueFromFunc';
	});

	it('makes a value available on the test context', function() {
		expect(this.fromLiteral).to.equal('valueFromLiteral');
	});

	it('makes the return value of a function available on the test context', function() {
		expect(this.fromFunc).to.equal('valueFromFunc');
	});

});
```

## whenIt(..)

The `whenIt(...)` function takes any number of arguments that act as test setup (aka `beforeEach`). The _last_ parameter must be a function that is executed as the test context.

The following things can be passed to the `whenIt` function:

* `Function` - The function will be executed as a `beforeEach` step. If the function has a `.name` then the name will be appended to the test name. If the function returns another `function`, then that returned function will be called in an `afterEach` step. Example:

```
describe('example', function() {
	function setsUserToBob() {
		this.user = 'Bob';

		return function() {
			delete this.user;
		}
	}

	whenIt(setsUserToBob, function() {
		it('can access the user name', function() {
			expect(this.user).to.equal('Bob');
		});
	});
});

// The above code is equivelant to this "normal" mocha test code:

describe('example', function() {
	describe('when it sets user to bob ', function() {
		beforeEach(function() {
			this.user = 'Bob';
		});

		afterEach(function() {
			delete this.user;
		});

		it('then it can access the user name', function() {
			expect(this.user).to.equal('Bob');
		});
	});
});
```

* `String` - The string will be appended to the test name.

* `Object` - The properties of the object will be copied to the `this` test context during the `beforeEach` step. The properties will then be deleted from the `this` context in the `afterEach`. Example:

```
describe('example', function() {
	whenIt('sets user to bob', { user: 'Bob' }, function() {
		it('can access the user name', function() {
			expect(this.user).to.equal('Bob');
		});
	});
});
```

* `Fixture` - See further information below.

## thenIt(..)

The `thenIt` function can be passed multiple `function`s. Each function is executed as its own `it()` test. Example:

```
describe('example', function() {
	function setsTheUserToAString() {
		expect(this.user).to.be.instanceOf(String);
	}

	function setsTheUserToBob() {
		expect(this.user).to.equal('Bob');
	}

	whenIt('sets user to bob', { user: 'Bob' }, function() {
		thenIt(setsTheUserToAString, setsTheUserToBob);
	});
});

// The above code is equivelant to this "normal" mocha test code:

describe('example', function() {
	describe('when it sets user to Bob', function() {
		beforeEach(function() {
			this.user = 'Bob';	
		});

		afterEach(function() {
			delete this.user;
		});

		it('sets the user to a string', function() {
			expect(this.user).to.be.instanceOf(String);
		});

		it('sets the user to Bob', function() {
			expect(this.user).to.equal('Bob');
		});
	});
});
```

## new Fixture(...)

An instance of the `Fixture` object can be passed to `whenIt` and it used to encapsulate a name and test before/after steps.

The constructor must be passed an object of the form:

```
var doesSomething = new Fixture({
	name: 'a string name to insert into the test name', // required.
	before: function() {}, // run during beforeEach. optional.
	after: function() {} // run during afterEach. optional.
});

whenIt(doesSomething, function() {
	it(...);
});
```

The instance also exposes a `.apply()` function. You can pass any arguments to the function, and those arguments will be passed to the `before` and `after` functions.

```
var setsUser = new Fixture({
	name: 'sets the user',
	before: function(name) { this.user = name; },
	after: function(name) { delete this.user; }
});

whenIt(setsUser.apply('Bob'), 'to Bob', function() {

	// full test name is "when it sets the user to Bob the user is set to Bob"
	it('the user is set to Bob', function() {
		expect(this.user).to.equal('Bob');
	});
});
```

---
_Source: https://npm.io/package/test-when-it · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._