Skip to content

Commit

Permalink
Clarify effect of .skip()
Browse files Browse the repository at this point in the history
The fact that code inside of a skipped suite is executed, is potentially
counter-intuitive.  By using alternative phrasing, we make it clear how
mocha handles code in skipped suites.

Closes #3932
  • Loading branch information
oliversalzburg committed Jun 6, 2019
1 parent d02a096 commit 0a8f534
Showing 1 changed file with 14 additions and 10 deletions.
24 changes: 14 additions & 10 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -566,32 +566,36 @@ _Note_: Hooks, if present, will still be executed.
## Inclusive Tests

This feature is the inverse of `.only()`. By appending `.skip()`, you may tell Mocha to simply ignore these suite(s) and test case(s). Anything skipped will be marked as [pending](#pending-tests), and reported as such. Here's an example of skipping an entire suite:
This feature is the inverse of `.only()`. By appending `.skip()`, you may tell Mocha to simply ignore test case(s). Anything skipped will be marked as [pending](#pending-tests), and reported as such. Here's an example of skipping an individual test:

```js
describe('Array', function() {
describe.skip('#indexOf()', function() {
// ...
describe('#indexOf()', function() {
it.skip('should return -1 unless present', function() {
// this test will not be run
});

it('should return the index when present', function() {
// this test will be run
});
});
});
```

Or a specific test-case:
You can also put `.skip()` on an entire suite. This is equivalent to appending `.skip()` onto all tests in the suite. Hooks in the suite are also skipped.

```js
describe('Array', function() {
describe('#indexOf()', function() {
it.skip('should return -1 unless present', function() {
describe.skip('#indexOf()', function() {
it('should return -1 unless present', function() {
// this test will not be run
});

it('should return the index when present', function() {
// this test will be run
});
});
});
```

_Note_: Code in skipped suites, that is placed outside of hooks or tests is still executed, as mocha will still invoke the suite function to build up the suite structure for visualization.

> _Best practice_: Use `.skip()` instead of commenting tests out.
You may also skip _at runtime_ using `this.skip()`. If a test needs an environment or configuration which cannot be detected beforehand, a runtime skip is appropriate. For example:
Expand Down

0 comments on commit 0a8f534

Please sign in to comment.