From 0a8f53490fed166606ee2e399c117939ace10928 Mon Sep 17 00:00:00 2001 From: Oliver Salzburg Date: Fri, 7 Jun 2019 00:33:35 +0200 Subject: [PATCH] Clarify effect of .skip() 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 a3fa090632..3ff9793df1 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: