unexpected-eventemitter/README.md

EventEmitter assertions for Unexpected

# unexpected-eventemitter

> [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) assertions for [Unexpected](http://unexpected.js.org/)

## Installation

```shell
$ npm i unexpected unexpected-eventemitter --save-dev
```

- This module requires Node.js v8+, IE11, or a modern browser.
- [unexpected](http://unexpected.js.org) is a _peer dependency_ of this module.
- In a browser, this module is exposed as `global.unexpectedEventEmitter`.

## Example

```js
const unexpected = require('unexpected');
const {EventEmitter} = require('events');

const expect = unexpected.clone().use(require('unexpected-eventemitter'));

const ee = new EventEmitter();

// "to emit from" with sync function
expect(
  () => {
    ee.emit('foo', {bar: 'baz'});
  },
  'to emit from',
  ee,
  'foo',
  {
    bar: 'baz',
  }
); // ok

// "to emit from" with async function
expect(
  async () => {
    await somethingAsync();
    ee.emit('foo', {bar: 'baz'});
  },
  'to emit from',
  ee,
  'foo',
  {
    bar: 'baz',
  }
); // ok

// "to emit from" with Promise
expect(
  somethingAsync().then(() => {
    ee.emit('foo', {bar: 'baz'});
  }),
  'to emit from',
  ee,
  'foo',
  {
    bar: 'baz',
  }
); // ok

// "not to emit from" with async function
expect(
  async () => {
    await somethingAsync();
    ee.emit('foo', {bar: 'baz'});
  },
  'not to emit from',
  ee,
  'foo'
); // assertion failure!

// "to emit with error from"
expect(
  Promise.resolve().then(() => {
    ee.emit('foo', {bar: 'baz'});
    throw new Error('uh oh');
  }),
  'to emit with error from',
  ee,
  'foo',
  /uh oh/
); // ok
```

## Assertions

### `to emit from`

`<function|Promise> [not] to emit from <EventEmitter> <string> <any*>`

- `<function|Promise>` may be a Promise, async, or synchronous function
- `<EventEmitter>` may be a duck-typed Node.js [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
- `<string>` is the event name
- `<any*>` corresponds to _zero (0) or more_ values which may be emitted. Do not use an array unless you expect the value to be an array!
- An `EventEmitter` emitting _more_ values than expected _will not_ fail an assertion.
- Values are checked with ["to satisfy"](http://unexpected.js.org/assertions/any/to-satisfy/) for flexibility.

### `to emit with error from`

`<function|Promise> to emit with error from <Error> <EventEmitter> <string> <any*>`

- Use when the subject `<function|Promise>` emits, but _also_ throws or rejects.
- There is no converse of this assertion; you cannot use `[not]`.

## Contributing

Please use the [Conventional Commits](https://www.conventionalcommits.org) commit message format.

## Related Projects

- [unexpected-events](https://npm.im/unexpected-events): Provides an alternative syntax, with the ability to test multiple events at once

## License

:copyright: 2017-2020 [Christopher Hiller](https://boneskull.com). Licensed Apache-2.0.