Use inline flags for test cases (#3931)

Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>

docs/contributing/the_basics.md

@@ -58,7 +58,26 @@ Further examples of invoking the tests
 (.venv)$ tox -e py -- --print-tree-diff=False
 ```
 
-`Black` has two pytest command-line options affecting test files in `tests/data/` that
+### Testing
+
+All aspects of the _Black_ style should be tested. Normally, tests should be created as
+files in the `tests/data/cases` directory. These files consist of up to three parts:
+
+- A line that starts with `# flags: ` followed by a set of command-line options. For
+  example, if the line is `# flags: --preview --skip-magic-trailing-comma`, the test
+  case will be run with preview mode on and the magic trailing comma off. The options
+  accepted are mostly a subset of those of _Black_ itself, except for the
+  `--minimum-version=` flag, which should be used when testing a grammar feature that
+  works only in newer versions of Python. This flag ensures that we don't try to
+  validate the AST on older versions and tests that we autodetect the Python version
+  correctly when the feature is used. For the exact flags accepted, see the function
+  `get_flags_parser` in `tests/util.py`. If this line is omitted, the default options
+  are used.
+- A block of Python code used as input for the formatter.
+- The line `# output`, followed by the output of _Black_ when run on the previous block.
+  If this is omitted, the test asserts that _Black_ will leave the input code unchanged.
+
+_Black_ has two pytest command-line options affecting test files in `tests/data/` that
 are split into an input part, and an output part, separated by a line with`# output`.
 These can be passed to `pytest` through `tox`, or directly into pytest if not using
 `tox`.

tests/data/cases/docstring_no_string_normalization.py

@@ -1,3 +1,4 @@
+# flags: --skip-string-normalization
 class ALonelyClass:
     '''
     A multiline class docstring.

tests/data/cases/docstring_preview_no_string_normalization.py

@@ -1,3 +1,4 @@
+# flags: --preview --skip-string-normalization
 def do_not_touch_this_prefix():
     R"""There was a bug where docstring prefixes would be normalized even with -S."""
 

tests/data/cases/funcdef_return_type_trailing_comma.py

@@ -1,3 +1,4 @@
+# flags: --preview --minimum-version=3.10
 # normal, short, function definition
 def foo(a, b) -> tuple[int, float]: ...
 

tests/data/cases/ignore_pyi.py

@@ -1,3 +1,4 @@
+# flags: --pyi
 def f():  # type: ignore
     ...
 

tests/data/cases/linelength6.py

@@ -1,3 +1,4 @@
+# flags: --line-length=6
 # Regression test for #3427, which reproes only with line length <= 6
 def f():
     """

tests/data/cases/nested_stub.py

@@ -1,3 +1,4 @@
+# flags: --pyi --preview
 import sys
 
 class Outer:

tests/data/cases/numeric_literals.py

@@ -1,5 +1,3 @@
-#!/usr/bin/env python3.6
-
 x = 123456789
 x = 123456
 x = .1
@@ -21,9 +19,6 @@
 
 # output
 
-
-#!/usr/bin/env python3.6
-
 x = 123456789
 x = 123456
 x = 0.1

tests/data/cases/numeric_literals_skip_underscores.py

@@ -1,5 +1,3 @@
-#!/usr/bin/env python3.6
-
 x = 123456789
 x = 1_2_3_4_5_6_7
 x = 1E+1
@@ -11,8 +9,6 @@
 
 # output
 
-#!/usr/bin/env python3.6
-
 x = 123456789
 x = 1_2_3_4_5_6_7
 x = 1e1

tests/data/cases/parenthesized_context_managers.py

@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.10
 with (CtxManager() as example):
     ...
 

tests/data/cases/pattern_matching_complex.py

@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.10
 # Cases sampled from Lib/test/test_patma.py
 
 # case black_test_patma_098

tests/data/cases/pattern_matching_extras.py

@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.10
 import match
 
 match something:

tests/data/cases/pattern_matching_generic.py

@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.10
 re.match()
 match = a
 with match() as match:

tests/data/cases/pattern_matching_simple.py

@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.10
 # Cases sampled from PEP 636 examples
 
 match command.split():

tests/data/cases/pattern_matching_style.py

@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.10
 match something:
     case b(): print(1+1)
     case c(

tests/data/cases/pep604_union_types_line_breaks.py

@@ -1,3 +1,4 @@
+# flags: --preview --minimum-version=3.10
 # This has always worked
 z= Loooooooooooooooooooooooong | Loooooooooooooooooooooooong | Loooooooooooooooooooooooong | Loooooooooooooooooooooooong
 

tests/data/cases/pep_570.py

@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.8
 def positional_only_arg(a, /):
     pass
 

tests/data/cases/pep_572.py

@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.8
 (a := 1)
 (a := a)
 if (match := pattern.search(data)) is None:

tests/data/cases/pep_572_do_not_remove_parens.py

@@ -1,3 +1,4 @@
+# flags: --fast
 # Most of the following examples are really dumb, some of them aren't even accepted by Python,
 # we're fixing them only so fuzzers (which follow the grammar which actually allows these
 # examples matter of fact!) don't yell at us :p

tests/data/cases/pep_572_py310.py

@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.10
 # Unparenthesized walruses are now allowed in indices since Python 3.10.
 x[a:=0]
 x[a:=0, b:=1]

tests/data/cases/pep_572_py39.py

@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.9
 # Unparenthesized walruses are now allowed in set literals & set comprehensions
 # since Python 3.9
 {x := 1, 2, 3}

tests/data/cases/pep_572_remove_parens.py

@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.8
 if (foo := 0):
     pass
 

tests/data/cases/pep_646.py

@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.11
 A[*b]
 A[*b] = 1
 A

tests/data/cases/pep_654.py

@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.11
 try:
     raise OSError("blah")
 except* ExceptionGroup as e:

tests/data/cases/pep_654_style.py

@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.11
 try:
     raise OSError("blah")
 except               * ExceptionGroup as e:

tests/data/cases/power_op_newline.py

@@ -1,3 +1,4 @@
+# flags: --line-length=0
 importA;()<<0**0#
 
 # output

tests/data/cases/preview_async_stmts.py

@@ -1,3 +1,4 @@
+# flags: --preview
 async def func() -> (int):
     return 0
 

tests/data/cases/preview_cantfit.py

@@ -1,3 +1,4 @@
+# flags: --preview
 # long variable name
 this_is_a_ridiculously_long_name_and_nobody_in_their_right_mind_would_use_one_like_it = 0
 this_is_a_ridiculously_long_name_and_nobody_in_their_right_mind_would_use_one_like_it = 1  # with a comment

tests/data/cases/preview_comments7.py

@@ -1,3 +1,4 @@
+# flags: --preview
 from .config import (
     Any,
     Bool,

tests/data/cases/preview_context_managers_38.py

@@ -1,3 +1,4 @@
+# flags: --preview --minimum-version=3.8
 with \
      make_context_manager1() as cm1, \
      make_context_manager2() as cm2, \

tests/data/cases/preview_context_managers_39.py

@@ -1,3 +1,4 @@
+# flags: --preview --minimum-version=3.9
 with \
      make_context_manager1() as cm1, \
      make_context_manager2() as cm2, \

tests/data/cases/preview_context_managers_autodetect_310.py

@@ -1,3 +1,4 @@
+# flags: --preview --minimum-version=3.10
 # This file uses pattern matching introduced in Python 3.10.
 
 

tests/data/cases/preview_context_managers_autodetect_311.py

@@ -1,3 +1,4 @@
+# flags: --preview --minimum-version=3.11
 # This file uses except* clause in Python 3.11.
 
 

tests/data/cases/preview_context_managers_autodetect_38.py

@@ -1,3 +1,4 @@
+# flags: --preview
 # This file doesn't use any Python 3.9+ only grammars.
 
 

tests/data/cases/preview_context_managers_autodetect_39.py

@@ -1,3 +1,4 @@
+# flags: --preview --minimum-version=3.9
 # This file uses parenthesized context managers introduced in Python 3.9.
 
 

tests/data/cases/preview_dummy_implementations.py

@@ -1,3 +1,4 @@
+# flags: --preview
 from typing import NoReturn, Protocol, Union, overload
 
 

tests/data/cases/preview_format_unicode_escape_seq.py

@@ -1,3 +1,4 @@
+# flags: --preview
 x = "\x1F"
 x = "\\x1B"
 x = "\\\x1B"

tests/data/cases/preview_long_dict_values.py

@@ -1,3 +1,4 @@
+# flags: --preview
 my_dict = {
     "something_something":
         r"Lorem ipsum dolor sit amet, an sed convenire eloquentiam \t"

tests/data/cases/preview_long_strings.py

@@ -1,3 +1,4 @@
+# flags: --preview
 x = "This is a really long string that can't possibly be expected to fit all together on one line. In fact it may even take up three or more lines... like four or five... but probably just three."
 
 x += "This is a really long string that can't possibly be expected to fit all together on one line. In fact it may even take up three or more lines... like four or five... but probably just three."

tests/data/cases/preview_long_strings__east_asian_width.py

@@ -1,3 +1,4 @@
+# flags: --preview
 # The following strings do not have not-so-many chars, but are long enough
 # when these are rendered in a monospace font (if the renderer respects
 # Unicode East Asian Width properties).

tests/data/cases/preview_long_strings__edge_case.py

@@ -1,3 +1,4 @@
+# flags: --preview
 some_variable = "This string is long but not so long that it needs to be split just yet"
 some_variable = 'This string is long but not so long that it needs to be split just yet'
 some_variable = "This string is long, just long enough that it needs to be split, u get?"

tests/data/cases/preview_long_strings__regression.py

@@ -1,3 +1,4 @@
+# flags: --preview
 class A:
     def foo():
         result = type(message)("")

tests/data/cases/preview_long_strings__type_annotations.py

@@ -1,3 +1,4 @@
+# flags: --preview
 def func(
     arg1,
     arg2,

tests/data/cases/preview_multiline_strings.py

@@ -1,3 +1,4 @@
+# flags: --preview
 """cow
 say""",
 call(3, "dogsay", textwrap.dedent("""dove

tests/data/cases/preview_no_blank_line_before_docstring.py

@@ -1,3 +1,4 @@
+# flags: --preview
 def line_before_docstring():
 
     """Please move me up"""

tests/data/cases/preview_pep_572.py

@@ -1,3 +1,4 @@
+# flags: --preview
 x[(a:=0):]
 x[:(a:=0)]
 

tests/data/cases/preview_percent_precedence.py

@@ -1,3 +1,4 @@
+# flags: --preview
 ("" % a) ** 2
 ("" % a)[0]
 ("" % a)()

tests/data/cases/preview_prefer_rhs_split.py

@@ -1,3 +1,4 @@
+# flags: --preview
 first_item, second_item = (
     some_looooooooong_module.some_looooooooooooooong_function_name(
         first_argument, second_argument, third_argument

tests/data/cases/preview_return_annotation_brackets_string.py

@@ -1,3 +1,4 @@
+# flags: --preview
 # Long string example
 def frobnicate() -> "ThisIsTrulyUnreasonablyExtremelyLongClassName | list[ThisIsTrulyUnreasonablyExtremelyLongClassName]":
     pass

tests/data/cases/preview_trailing_comma.py

@@ -1,3 +1,4 @@
+# flags: --preview
 e = {
     "a": fun(msg, "ts"),
     "longggggggggggggggid": ...,

tests/data/cases/py310_pep572.py

@@ -1,3 +1,4 @@
+# flags: --preview --minimum-version=3.10
 x[a:=0]
 x[a := 0]
 x[a := 0, b := 1]