Skip to content

Commit

Permalink
docs: Add test file location -> test runner table (elastic#34986)
Browse files Browse the repository at this point in the history
* docs: Add test file location -> test runner table

* Use scripts/mocha instead of if yarn test:mocha and clarify arguments

* docs: add some examples of running tests suites with grep patterns

* Split out x-pack testing docs, add test runner column

* Split out x-pack testing docs, add test runner column #2

* Use node scripts for jest and split functional runner/server
  • Loading branch information
rudolf authored Apr 19, 2019
1 parent cc9dea1 commit bb121ef
Show file tree
Hide file tree
Showing 2 changed files with 45 additions and 23 deletions.
43 changes: 30 additions & 13 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -327,19 +327,36 @@ macOS users on a machine with a discrete graphics card may see significant speed
`yarn debug` will start the server with Node's inspect flag. Kibana's development mode will start three processes on ports `9229`, `9230`, and `9231`. Chrome's developer tools need to be configured to connect to all three connections. Add `localhost:<port>` for each Kibana process in Chrome's developer tools connection tab.

### Unit testing frameworks
Kibana is migrating unit testing from Mocha to Jest. Legacy unit tests still exist in Mocha but all new unit tests should be written in Jest.

#### Mocha (legacy)
Mocha tests are contained in `__tests__` directories.

#### Jest
Jest tests are stored in the same directory as source code files with the `.test.js` suffix.

### Running Jest Unit Tests

```bash
node scripts/jest
```
Kibana is migrating unit testing from Mocha to Jest. Legacy unit tests still
exist in Mocha but all new unit tests should be written in Jest. Mocha tests
are contained in `__tests__` directories. Whereas Jest tests are stored in
the same directory as source code files with the `.test.js` suffix.

### Running specific Kibana tests

The following table outlines possible test file locations and how to invoke them:

| Test runner | Test location | Runner command (working directory is kibana root) |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Jest | `src/**/*.test.js`<br>`src/**/*.test.ts` | `node scripts/jest -t regexp [test path]` |
| Jest (integration) | `**/integration_tests/**/*.test.js` | `node scripts/jest_integration -t regexp [test path]` |
| Mocha | `src/**/__tests__/**/*.js`<br>`packages/kbn-datemath/test/**/*.js`<br>`packages/kbn-dev-utils/src/**/__tests__/**/*.js`<br>`tasks/**/__tests__/**/*.js` | `node scripts/mocha --grep=regexp [test path]` |
| Functional | `test/*integration/**/config.js`<br>`test/*functional/**/config.js` | `node scripts/functional_tests_server --config test/[directory]/config.js`<br>`node scripts/functional_test_runner --config test/[directory]/config.js --grep=regexp` |

For X-Pack tests located in `x-pack/` see [X-Pack Testing](x-pack/README.md#testing)

Test runner arguments:
- Where applicable, the optional arguments `-t=regexp` or `--grep=regexp` will only run tests or test suites whose descriptions matches the regular expression.
- `[test path]` is the relative path to the test file.

Examples:
- Run the entire elasticsearch_service test suite with yarn:
`node scripts/jest src/core/server/elasticsearch/elasticsearch_service.test.ts`
- Run the jest test case whose description matches 'stops both admin and data clients':
`node scripts/jest -t 'stops both admin and data clients' src/core/server/elasticsearch/elasticsearch_service.test.ts`
- Run the api integration test case whose description matches the given string:
`node scripts/functional_tests_server --config test/api_integration/config.js`
`node scripts/functional_tests_runner --config test/api_integration/config.js --grep='should return 404 if id does not match any sample data sets'`

### Debugging Unit Tests

Expand Down
25 changes: 15 additions & 10 deletions x-pack/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,22 @@ Elasticsearch will run with a basic license. To run with a trial license, includ
Example: `yarn es snapshot --license trial --password changeme`

# Testing
## Running specific tests
| Test runner | Test location | Runner command (working directory is kibana/x-pack) |
| ------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Jest | `x-pack/**/*.test.js`<br>`x-pack/**/*.test.ts` | `cd x-pack && node scripts/jest -t regexp [test path]` |
| Functional | `x-pack/test/*integration/**/config.js`<br>`x-pack/test/*functional/config.js` | `node scripts/functional_tests_server --config x-pack/test/[directory]/config.js`<br>`node scripts/functional_test_runner --config x-pack/test/[directory]/config.js --grep=regexp` |

## Running unit tests_bundle
Examples:
- Run the jest test case whose description matches 'filtering should skip values of null':
`cd x-pack && yarn test:jest -t 'filtering should skip values of null' plugins/ml/public/explorer/explorer_charts/explorer_charts_container_service.test.js`
- Run the x-pack api integration test case whose description matches the given string:
`node scripts/functional_tests_server --config x-pack/test/api_integration/config.js`
`node scripts/functional_test_runner --config x-pack/test/api_integration/config.js --grep='apis Monitoring Beats list with restarted beat instance should load multiple clusters'`

In addition to to providing a regular expression argument, specific tests can also be run by appeding `.only` to an `it` or `describe` function block. E.g. `describe(` to `describe.only(`.

## Running all tests

You can run unit tests by running:

Expand All @@ -28,15 +42,6 @@ If you want to run tests only for a specific plugin (to save some time), you can
yarn test --plugins <plugin>[,<plugin>]* # where <plugin> is "reporting", etc.
```

#### Running single test file
Edit test file, changing top level `describe` to `describe.only`. Run tests with normal commands.

#### Running Jest Unit Tests
```bash
# from x-pack folder
node scripts/jest
```

#### Debugging browser tests
```
yarn test:browser:dev
Expand Down

0 comments on commit bb121ef

Please sign in to comment.