From b269ad01b8faedc21d0bc0a955495719a06bae9d Mon Sep 17 00:00:00 2001 From: Oliver Salzburg Date: Mon, 22 Jul 2019 16:22:13 +0200 Subject: [PATCH] Clarify effect of .skip() (#3947) 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 --- docs/index.md | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/index.md b/docs/index.md index ab898764c0..30613b87bf 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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: