Update the documentation for the skip parameter in the test (#2102)

Document that a `skip: false` on a `test` can override a skipped group,
but not a skipped suite.

Add a unit test for the behavior between `group` and `test`.

Update an integration test to demonstrate that a suite level `@Skip()`
annotation cannot be overridden, it will always show as _one_ test
skipped for the entire suite.

pkgs/test/test/runner/engine_test.dart

@@ -257,6 +257,18 @@ void main() {
       expect(bodyRun, isTrue);
     });
 
+    test('runs tests in the group when they are skip: false', () async {
+      var bodyRun = false;
+      var engine = declareEngine(() {
+        group('group', () {
+          test('test', skip: false, () => bodyRun = true);
+        }, skip: true);
+      });
+
+      await engine.run();
+      expect(bodyRun, isTrue);
+    });
+
     test('exposes a LiveTest that emits the correct states', () {
       var entries = declare(() {
         group('group', () {

pkgs/test/test/runner/runner_test.dart

@@ -519,7 +519,8 @@ $_usage''');
         import 'package:test/test.dart';
 
         void main() {
-          test("success", () {});
+          test('success', () {});
+          test('explicitly unskipped', skip: false, () {});
         }
       ''').create();
     });
@@ -532,7 +533,7 @@ $_usage''');
 
     test('runs all tests with --run-skipped', () async {
       var test = await runTest(['--run-skipped', 'test.dart']);
-      expect(test.stdout, emitsThrough(contains('+1: All tests passed!')));
+      expect(test.stdout, emitsThrough(contains('+2: All tests passed!')));
       await test.shouldExit(0);
     });
   });

pkgs/test_core/lib/src/scaffolding.dart

@@ -90,7 +90,12 @@ Declarer get _declarer {
 ///
 /// If [skip] is a String or `true`, the test is skipped. If it's a String, it
 /// should explain why the test is skipped; this reason will be printed instead
-/// of running the test.
+/// of running the test. If a call to [test] is nested within a [group], a
+/// non-null `skip` parameter for the `test` will take precedence over the skip
+/// parameter in the `group`. For instance, if a `group` is set to `skip: true`,
+/// but a `test` within it is configured as `skip: false`, the `test` will not
+/// be skipped. A suite level `@Skip()` annotation cannot be overridden with
+/// `skip` arguments to `test` or `group`.
 ///
 /// If [tags] is passed, it declares user-defined tags that are applied to the
 /// test. These tags can be used to select or skip the test on the command line,