docs/TESTS.md

   1 # libsyntax2.0 testing infrastructure
   2
   3 Libsyntax2.0 tests are in the `tests/data` directory. Each test is a
   4 pair of files, an `.rs` file with Rust code and a `.txt` file with a
   5 human-readable representation of syntax tree.
   6
   7 The test suite is intended to be independent from a particular parser:
   8 that's why it is just a list of files.
   9
  10 The test suite is intended to be progressive: that is, if you want to
  11 write a Rust parser, you can TDD it by working through the test in
  12 order. That's why each test file begins with the number. Generally,
  13 tests should be added in order of the appearance of corresponding
  14 functionality in libsytnax2.0. If a bug in parser is uncovered, a
  15 **new** test should be created instead of modifying an existing one:
  16 it is preferable to have a gazillion of small isolated test files,
  17 rather than a single file which covers all edge cases. It's okay for
  18 files to have the same name except for the leading number. In general,
  19 test suite should be append-only: old tests should not be modified,
  20 new tests should be created instead.
  21
  22 Note that only `ok` tests are normative: `err` tests test error
  23 recovery and it is totally ok for a parser to not implement any error
  24 recovery at all. However, for libsyntax2.0 we do care about error
  25 recovery, and we do care about precise and useful error messages.
  26
  27 There are also so-called "inline tests". They appear as the comments
  28 with a `test` header in the source code, like this:
  29
  30 ```rust
  31 // test fn_basic
  32 // fn foo() {}
  33 fn function(p: &mut Parser) {
  34     // ...
  35 }
  36 ```
  37
  38 You can run `cargo collect-tests` command to collect all inline tests
  39 into `tests/data/inline` directory. The main advantage of inline tests
  40 is that they help to illustrate what the relevant code is doing.
  41
  42
  43 Contribution opportunity: design and implement testing infrastructure
  44 for validators.