docs: update docs for skip_very_good_optimization tag (#1386)

* doc: update docs for skip_very_good_optimization tag

* fix: format

* fix: tests

* fix: md docs

Author: matiasleyba

lib/src/commands/dart/commands/dart_test_command.dart

@@ -149,8 +149,10 @@ class DartTestCommand extends Command<int> {
         'optimization',
         defaultsTo: true,
         help:
-            'Whether to apply optimizations for test performance. '
-            'Automatically disabled when --platform is specified.',
+            'Whether to apply optimizations for test performance.\n'
+            'Automatically disabled when --platform is specified.\n'
+            'Add the `skip_very_good_optimization` tag to specific test files '
+            'to disable them individually.',
       )
       ..addOption(
         'concurrency',

lib/src/commands/test/test.dart

@@ -163,8 +163,10 @@ class TestCommand extends Command<int> {
         'optimization',
         defaultsTo: true,
         help:
-            'Whether to apply optimizations for test performance. '
-            'Automatically disabled when --platform is specified.',
+            'Whether to apply optimizations for test performance.\n'
+            'Automatically disabled when --platform is specified.\n'
+            'Add the `skip_very_good_optimization` tag to specific test files '
+            'to disable them individually.',
       )
       ..addOption(
         'concurrency',

site/docs/commands/test.md

@@ -16,6 +16,8 @@ very_good test [arguments]
     --coverage                        Whether to collect coverage information.
 -r, --recursive                       Run tests recursively for all nested packages.
     --[no-]optimization               Whether to apply optimizations for test performance.
+                                      Automatically disabled when --platform is specified.
+                                      Add the `skip_very_good_optimization` tag to specific test files to disable them individually.
                                       (defaults to on)
 -j, --concurrency                     The number of concurrent test suites run.
                                       (defaults to "4")
@@ -60,4 +62,15 @@ Golden tests are tests that compare the output of a test to a "golden" file. If
 
 [Very Good CLI](https://cli.vgv.dev/) supports golden tests out of the box, with and without a custom [`goldenFileComparator`](https://api.flutter.dev/flutter/flutter_test/goldenFileComparator.html). This means that **no change is required** to your test code to run them with `very_good test`.
 
-:::info For an example on specifying a custom [`GoldenFileComparator`](https://api.flutter.dev/flutter/flutter_test/GoldenFileComparator-class.html) that accepts a certain amount of difference (toleration threshold), refer to the [`goldenFileComparator` Flutter documentation](https://api.flutter.dev/flutter/flutter_test/goldenFileComparator.html). :::
+:::info For an example on specifying a custom [`GoldenFileComparator`](https://api.flutter.dev/flutter/flutter_test/GoldenFileComparator-class.html) that accepts a certain amount of difference (toleration threshold), refer to the [`goldenFileComparator` Flutter documentation](https://api.flutter.dev/flutter/flutter_test/goldenFileComparator.html).
+:::
+
+### Skip optimization for specific tests
+
+By default, all tests run with optimizations enabled; use the `--no-optimization` flag to disable globally, or add the `skip_very_good_optimization` tag to specific test files to disable them individually.
+
+```js
+@Tags(['skip_very_good_optimization'])
+
+import 'package:test/test.dart';
+```

test/src/commands/dart/commands/dart_test_test.dart

@@ -27,7 +27,9 @@ const expectedTestUsage = [
       '-h, --help                            Print this usage information.\n'
       '    --coverage                        Whether to collect coverage information.\n'
       '-r, --recursive                       Run tests recursively for all nested packages.\n'
-      '    --[no-]optimization               Whether to apply optimizations for test performance. Automatically disabled when --platform is specified.\n'
+      '    --[no-]optimization               Whether to apply optimizations for test performance.\n'
+      '                                      Automatically disabled when --platform is specified.\n'
+      '                                      Add the `skip_very_good_optimization` tag to specific test files to disable them individually.\n'
       '                                      (defaults to on)\n'
       '-j, --concurrency                     The number of concurrent test suites run. Automatically set to 1 when --platform is specified.\n'
       '                                      (defaults to "4")\n'

test/src/commands/test/test_test.dart

@@ -27,7 +27,9 @@ const expectedTestUsage = [
       '-h, --help                                                   Print this usage information.\n'
       '    --coverage                                               Whether to collect coverage information.\n'
       '-r, --recursive                                              Run tests recursively for all nested packages.\n'
-      '    --[no-]optimization                                      Whether to apply optimizations for test performance. Automatically disabled when --platform is specified.\n'
+      '    --[no-]optimization                                      Whether to apply optimizations for test performance.\n'
+      '                                                             Automatically disabled when --platform is specified.\n'
+      '                                                             Add the `skip_very_good_optimization` tag to specific test files to disable them individually.\n'
       '                                                             (defaults to on)\n'
       '-j, --concurrency                                            The number of concurrent test suites run. Automatically set to 1 when --platform is specified.\n'
       '                                                             (defaults to "4")\n'