69cb2d3e2c
Signed-off-by: Tyler Smalley <tyler.smalley@elastic.co> # Conflicts: # .github/ISSUE_TEMPLATE/v8_breaking_change.md # .github/PULL_REQUEST_TEMPLATE.md
88 lines
3.8 KiB
Plaintext
88 lines
3.8 KiB
Plaintext
[[development-unit-tests]]
|
||
== Unit testing frameworks
|
||
|
||
{kib} is doing unit testing doing `Jest`.
|
||
|
||
[discrete]
|
||
== Jest
|
||
Jest tests are stored in the same directory as source code files with the `.test.{js,mjs,ts,tsx}` suffix.
|
||
|
||
Each plugin and package contains it's own `jest.config.js` file to define its root, and any overrides
|
||
to the jest-preset provided by `@kbn/test`. When working on a single plugin or package, you will find
|
||
it's more efficient to supply the Jest configuration file when running.
|
||
|
||
["source","shell"]
|
||
-----------
|
||
yarn jest --config src/plugins/discover/jest.config.js
|
||
-----------
|
||
|
||
[discrete]
|
||
==== Writing Jest Unit Tests
|
||
|
||
In order to write those tests there are two main things you need to be aware of.
|
||
The first one is the different between `jest.mock` and `jest.doMock`
|
||
and the second one our `jest mocks file pattern`. As we are running `js` and `ts`
|
||
test files with `babel-jest` both techniques are needed
|
||
specially for the tests implemented on Typescript in order to benefit from the
|
||
auto-inference types feature.
|
||
|
||
[discrete]
|
||
==== Jest.mock vs Jest.doMock
|
||
|
||
Both methods are essentially the same on their roots however the `jest.mock`
|
||
calls will get hoisted to the top of the file and can only reference variables
|
||
prefixed with `mock`. On the other hand, `jest.doMock` won't be hoisted and can
|
||
reference pretty much any variable we want, however we have to assure those referenced
|
||
variables are instantiated at the time we need them which lead us to the next
|
||
section where we'll talk about our jest mock files pattern.
|
||
|
||
[discrete]
|
||
==== Jest Mock Files Pattern
|
||
|
||
Specially on typescript it is pretty common to have in unit tests
|
||
`jest.doMock` calls which reference for example imported types. Any error
|
||
will thrown from doing that however the test will fail. The reason behind that
|
||
is because despite the `jest.doMock` isn't being hoisted by `babel-jest` the
|
||
import with the types we are referencing will be hoisted to the top and at the
|
||
time we'll call the function that variable would not be defined.
|
||
|
||
In order to prevent that we develop a protocol that should be followed:
|
||
|
||
- Each module could provide a standard mock in `mymodule.mock.ts` in case
|
||
there are other tests that could benefit from using definitions here.
|
||
This file would not have any `jest.mock` calls, just dummy objects.
|
||
|
||
- Each test defines its mocks in `mymodule.test.mocks.ts`. This file
|
||
could import relevant mocks from the generalised module's mocks
|
||
file `(*.mock.ts)` and call `jest.mock` for each of them. If there is
|
||
any relevant dummy mock objects to generalise (and to be used by
|
||
other tests), the dummy objects could be defined directly on this file.
|
||
|
||
- Each test would import its mocks from the test mocks
|
||
file mymodule.test.mocks.ts. `mymodule.test.ts` has an import
|
||
like: `import * as Mocks from './mymodule.test.mocks'`,
|
||
`import { mockX } from './mymodule.test.mocks'`
|
||
or just `import './mymodule.test.mocks'` if there isn't anything
|
||
exported to be used.
|
||
|
||
[discrete]
|
||
[[debugging-unit-tests]]
|
||
=== Debugging Unit Tests
|
||
|
||
The standard `yarn test` task runs several sub tasks and can take
|
||
several minutes to complete, making debugging failures pretty painful.
|
||
In order to ease the pain specialized tasks provide alternate methods
|
||
for running the tests.
|
||
|
||
You could also add the `--debug` option so that `node` is run using
|
||
the `--debug-brk` flag. You’ll need to connect a remote debugger such
|
||
as https://github.com/node-inspector/node-inspector[`node-inspector`]
|
||
to proceed in this mode.
|
||
|
||
[discrete]
|
||
=== Unit Testing Plugins
|
||
|
||
Even when using
|
||
https://github.com/elastic/kibana/tree/main/packages/kbn-plugin-generator[Kibana
|
||
plugin generator] we do not enforce a way for unit testing your plugin. Please setup and you use
|
||
the tools of your choice. If the plugin will live inside the Kibana repo `Jest` must be used. |