Skip child suites when using this.skip()

When using `this.skip()` in a before hook, it skips all the tests in
the current suite, but runs the tests in all the child suites.

This patch expands the fixtures in skip-[a]sync-before fixtures to
cover the more expected behavior, and corrects the handling of Pending
exceptions in runner.js accordingly.

Fixes mochajs#2819

docs/index.md

@@ -594,6 +594,8 @@ before(function() {
 });
 ```
 
+This will skip all the tests and beforeEach/afterEach hooks in the current suite, and all hooks and tests of any child suites. It will, however, continue running the before all and after all hooks of the current suite.
+
 > Before Mocha v3.0.0, `this.skip()` was not supported in asynchronous tests and hooks.
 
 ## Retry Tests

lib/runner.js

@@ -314,6 +314,9 @@ Runner.prototype.hook = function (name, fn) {
             suite.tests.forEach(function (test) {
               test.pending = true;
             });
+            suite.suites.forEach(function (suite) {
+              suite.pending = true;
+            });
             // a pending hook won't be executed twice.
             hook.pending = true;
           }

test/integration/fixtures/pending/skip-async-before.fixture.js

@@ -8,11 +8,41 @@ describe('skip in before', function () {
     }, 50);
   });
 
+  beforeEach(function () {
+    throw new Error('never thrown');
+  });
+
+  afterEach(function () {
+    throw new Error('never thrown');
+  });
+
   it('should never run this test', function () {
     throw new Error('never thrown');
   });
 
   it('should never run this test', function () {
     throw new Error('never thrown');
   });
+
+  describe('in child suites', function () {
+    before(function () {
+      throw new Error('never thrown');
+    });
+
+    after(function () {
+      throw new Error('never thrown');
+    });
+
+    beforeEach(function () {
+      throw new Error('never thrown');
+    });
+
+    afterEach(function () {
+      throw new Error('never thrown');
+    });
+
+    it('should never run this test', function () {
+      throw new Error('never thrown');
+    });
+  });
 });

test/integration/fixtures/pending/skip-sync-before.fixture.js

@@ -5,11 +5,41 @@ describe('skip in before', function () {
     this.skip();
   });
 
+  beforeEach(function () {
+    throw new Error('never thrown');
+  });
+
+  afterEach(function () {
+    throw new Error('never thrown');
+  });
+
   it('should never run this test', function () {
     throw new Error('never thrown');
   });
 
   it('should never run this test', function () {
     throw new Error('never thrown');
   });
+
+  describe('in child suites', function () {
+    before(function () {
+      throw new Error('never thrown');
+    });
+
+    after(function () {
+      throw new Error('never thrown');
+    });
+
+    beforeEach(function () {
+      throw new Error('never thrown');
+    });
+
+    afterEach(function () {
+      throw new Error('never thrown');
+    });
+
+    it('should never run this test', function () {
+      throw new Error('never thrown');
+    });
+  });
 });

test/integration/pending.spec.js

@@ -58,7 +58,7 @@ describe('pending', function () {
             done(err);
             return;
           }
-          assert.equal(res.stats.pending, 2);
+          assert.equal(res.stats.pending, 3);
           assert.equal(res.stats.passes, 0);
           assert.equal(res.stats.failures, 0);
           assert.equal(res.code, 0);
@@ -108,7 +108,7 @@ describe('pending', function () {
             done(err);
             return;
           }
-          assert.equal(res.stats.pending, 2);
+          assert.equal(res.stats.pending, 3);
           assert.equal(res.stats.passes, 0);
           assert.equal(res.stats.failures, 0);
           assert.equal(res.code, 0);