1 | # Jest Console
|
2 |
|
3 | Custom [Jest](https://jestjs.io/) matchers for the [Console](https://developer.mozilla.org/en-US/docs/Web/API/Console)
|
4 | object to test JavaScript code in WordPress.
|
5 |
|
6 | This package converts `console.error`, `console.info`, `console.log` and `console.warn` functions into mocks and tracks their calls.
|
7 | It also enforces usage of one of the related matchers whenever tested code calls one of the mentioned `console` methods.
|
8 | It means that you need to assert with `.toHaveErrored()` or `.toHaveErroredWith( arg1, arg2, ... )` when `console.error`
|
9 | gets executed, and use the corresponding methods when `console.info`, `console.log` or `console.warn` are called.
|
10 | Your test will fail otherwise! This is a conscious design decision which helps to detect deprecation warnings when
|
11 | upgrading dependent libraries or smaller errors when refactoring code.
|
12 |
|
13 | ## Installation
|
14 |
|
15 | Install the module:
|
16 |
|
17 | ```bash
|
18 | npm install @wordpress/jest-console --save-dev
|
19 | ```
|
20 |
|
21 | **Note**: This package requires Node.js 14.0.0 or later. It is not compatible with older versions.
|
22 |
|
23 | ### Setup
|
24 |
|
25 | The simplest setup is to use Jest's `setupFilesAfterEnv` config option:
|
26 |
|
27 | ```js
|
28 | "jest": {
|
29 | "setupFilesAfterEnv": [
|
30 | "@wordpress/jest-console"
|
31 | ]
|
32 | },
|
33 | ```
|
34 |
|
35 | ### Usage
|
36 |
|
37 | ### `.toHaveErrored()`
|
38 |
|
39 | Use `.toHaveErrored` to ensure that `console.error` function was called.
|
40 |
|
41 | For example, let's say you have a `drinkAll( flavor )` function that makes you drink all available beverages.
|
42 | You might want to check if function calls `console.error` for `'octopus'` instead, because `'octopus'` flavor is really
|
43 | weird and why would anything be octopus-flavored? You can do that with this test suite:
|
44 |
|
45 | ```js
|
46 | describe( 'drinkAll', () => {
|
47 | test( 'drinks something lemon-flavored', () => {
|
48 | drinkAll( 'lemon' );
|
49 | expect( console ).not.toHaveErrored();
|
50 | } );
|
51 |
|
52 | test( 'errors when something is octopus-flavored', () => {
|
53 | drinkAll( 'octopus' );
|
54 | expect( console ).toHaveErrored();
|
55 | } );
|
56 | } );
|
57 | ```
|
58 |
|
59 | ### `.toHaveErroredWith( arg1, arg2, ... )`
|
60 |
|
61 | Use `.toHaveErroredWith` to ensure that `console.error` function was called with
|
62 | specific arguments.
|
63 |
|
64 | For example, let's say you have a `drinkAll( flavor )` function again makes you drink all available beverages.
|
65 | You might want to check if function calls `console.error` with a specific message for `'octopus'` instead, because
|
66 | `'octopus'` flavor is really weird and why would anything be octopus-flavored? To make sure this works, you could write:
|
67 |
|
68 | ```js
|
69 | describe( 'drinkAll', () => {
|
70 | test( 'errors with message when something is octopus-flavored', () => {
|
71 | drinkAll( 'octopus' );
|
72 | expect( console ).toHaveErroredWith(
|
73 | 'Should I really drink something that is octopus-flavored?'
|
74 | );
|
75 | } );
|
76 | } );
|
77 | ```
|
78 |
|
79 | ### `.toHaveInformed()`
|
80 |
|
81 | Use `.toHaveInformed` to ensure that `console.info` function was called.
|
82 |
|
83 | Almost identical usage as `.toHaveErrored()`.
|
84 |
|
85 | ### `.toHaveInformedWith( arg1, arg2, ... )`
|
86 |
|
87 | Use `.toHaveInformedWith` to ensure that `console.info` function was called with
|
88 | specific arguments.
|
89 |
|
90 | Almost identical usage as `.toHaveErroredWith()`.
|
91 |
|
92 | ### `.toHaveLogged()`
|
93 |
|
94 | Use `.toHaveLogged` to ensure that `console.log` function was called.
|
95 |
|
96 | Almost identical usage as `.toHaveErrored()`.
|
97 |
|
98 | ### `.toHaveLoggedWith( arg1, arg2, ... )`
|
99 |
|
100 | Use `.toHaveLoggedWith` to ensure that `console.log` function was called with
|
101 | specific arguments.
|
102 |
|
103 | Almost identical usage as `.toHaveErroredWith()`.
|
104 |
|
105 | ### `.toHaveWarned()`
|
106 |
|
107 | Use `.toHaveWarned` to ensure that `console.warn` function was called.
|
108 |
|
109 | Almost identical usage as `.toHaveErrored()`.
|
110 |
|
111 | ### `.toHaveWarnedWith( arg1, arg2, ... )`
|
112 |
|
113 | Use `.toHaveWarneddWith` to ensure that `console.warn` function was called with
|
114 | specific arguments.
|
115 |
|
116 | Almost identical usage as `.toHaveErroredWith()`.
|
117 |
|
118 | ## Contributing to this package
|
119 |
|
120 | This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects.
|
121 |
|
122 | To find out more about contributing to this package or Gutenberg as a whole, please read the project's main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).
|
123 |
|
124 | <br /><br /><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>
|