Skip to content

Commit

Permalink
Clarify effect of .skip() (#3947)
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 authored and craigtaub committed Jul 22, 2019
1 parent 1e6cf3b commit b269ad0
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() {

This comment has been minimized.

Copy link
@m0nusingh

m0nusingh Jul 25, 2019

Skipping now

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

1 comment on commit b269ad0

@m0nusingh
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good one !!

Please sign in to comment.