docs

docs/contributing/the_basics.md

@@ -58,7 +58,27 @@ 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. 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. 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`.