<div align="center">

# @zoroaster/assert

[![npm version](https://badge.fury.io/js/%40zoroaster%2Fassert.svg)](https://www.npmjs.com/package/@zoroaster/assert)
<a href="https://gitlab.com/artdeco/contexttesting/assert/-/commits/master">
  <img src="https://gitlab.com/artdeco/contexttesting/assert/badges/master/pipeline.svg"
    alt="Pipeline Badge">
</a>
</div>

`@zoroaster/assert` is An Assertion Library For Zoroaster Context Testing Framework Including Deep Equal & Assert Throws.

```sh
yarn add -D @zoroaster/assert
```

## Table Of Contents

- [Table Of Contents](#table-of-contents)
- [API](#api)
- [`deepEqual(actual: ?, expected: ?, message=: string): void`](#deepequalactual-expected-message-string-void)
- [`async assertThrows(config: _assertThrows.Config): void`](#async-assertthrowsconfig-_assertthrowsconfig-void)
  * [`_assertThrows.Assertion`](#type-_assertthrowsassertion)
  * [`_assertThrows.Config`](#type-_assertthrowsconfig)
- [Copyright & License](#copyright--license)

<div align="center"><a href="#table-of-contents">
  <img src="/.documentary/section-breaks/0.svg?sanitize=true">
</a></div>

## API

The package is available by importing its named functions:

```js
import deepEqual,
  throws,
  assert,
  equal,
  ok,
} from '@zoroaster/assert'
```

<div align="center"><a href="#table-of-contents">
  <img src="/.documentary/section-breaks/1.svg?sanitize=true">
</a></div>

## <code><ins>deepEqual</ins>(</code><sub><br/>&nbsp;&nbsp;`actual: ?,`<br/>&nbsp;&nbsp;`expected: ?,`<br/>&nbsp;&nbsp;`message=: string,`<br/></sub><code>): <i>void</i></code>
Calls `assert.deepStrictEqual` and then creates a visual representation of the difference between objects if it throws.

 - <kbd><strong>actual*</strong></kbd> <em><code>?undefined</code></em>: The actual value.
 - <kbd><strong>expected*</strong></kbd> <em><code>?undefined</code></em>: The expected value.
 - <kbd>message</kbd> <em>`string`</em> (optional): The message with which to fail if the assertion didn't succeed.

<div align="center"><a href="#table-of-contents">
  <img src="/.documentary/section-breaks/2.svg?sanitize=true">
</a></div>

## <code>async <ins>assertThrows</ins>(</code><sub><br/>&nbsp;&nbsp;`config: _assertThrows.Config,`<br/></sub><code>): <i>void</i></code>
Assert that a function throws and check the thrown error properties.
  ```js
  await throws({
    fn: method,
    args: ['test', true],
    message: /An error occurred:/, // regex
    code: 'ENOTEST',               // string
    stack(stack) {                 // function
      equal(stack.length, 2)
    }
  })
  ```


 - <kbd><strong>config*</strong></kbd> <em><code><a href="#type-_assertthrowsconfig" title="Parameters to the `assert-throws` method.">_assertThrows.Config</a></code></em>: Parameters to the `assert-throws` method.

<code>!(string \| RegExp \| !Function)</code> <strong><a name="type-_assertthrowsassertion">`_assertThrows.Assertion`</a></strong>: An assertion to perform.


<strong><a name="type-_assertthrowsconfig">`_assertThrows.Config`</a></strong>: Parameters to the `assert-throws` method.


|  Name   |                                                     Type                                                     |                                     Description                                      |
| ------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| __fn*__ | <em>!Function</em>                                                                                           | The function to test, either sync or async.                                          |
| args    | <em>(* \| !Array&lt;*&gt;)</em>                                                                              | The arguments or single argument to pass to the function.                            |
| context | <em>*</em>                                                                                                   | The context in which to execute the function. Global context will be set by default. |
| message | <em><a href="#type-_assertthrowsassertion" title="An assertion to perform.">_assertThrows.Assertion</a></em> | A string, regex, or function to test the message.                                    |
| code    | <em><a href="#type-_assertthrowsassertion" title="An assertion to perform.">_assertThrows.Assertion</a></em> | A string, regex, or function to test the code.                                       |
| stack   | <em><a href="#type-_assertthrowsassertion" title="An assertion to perform.">_assertThrows.Assertion</a></em> | A string, regex, or function to test the stack.                                      |
| prop    | <em><a href="#type-_assertthrowsassertion" title="An assertion to perform.">_assertThrows.Assertion</a></em> | A string, regex, or function to test any other property of the error.                |
| error   | <em>Error</em>                                                                                               | An error to perform strict comparison against.                                       |

<div align="center"><a href="#table-of-contents">
  <img src="/.documentary/section-breaks/3.svg?sanitize=true">
</a></div>

## Copyright & License

GNU Affero General Public License v3.0

<table>
  <tr>
    <th>
      <a href="https://www.artd.eco">
        <img width="100" src="https://gitlab.com/uploads/-/system/group/avatar/7454762/artdeco.png"
          alt="Art Deco">
      </a>
    </th>
    <th>© <a href="https://www.artd.eco">Art Deco™</a> for <a href="https://www.contexttesting.com">ContextTesting</a> 2020</th>
    <th>
      <a href="https://www.contexttesting.com">
        <img src="https://avatars1.githubusercontent.com/u/44418436?s=100" width="100" alt="ContextTesting">
      </a>
    </th>
    <th><a href="LICENSE"><img src=".documentary/agpl-3.0.svg" alt="AGPL-3.0"></a></th>
  </tr>
</table>

<div align="center"><a href="#table-of-contents">
  <img src="/.documentary/section-breaks/-1.svg?sanitize=true">
</a></div>