From 4c10c31be339ef3082f142061d83149af2a30ec8 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Wed, 10 Jan 2018 21:58:38 +0300 Subject: D: start documenting stuff --- docs/TESTS.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 docs/TESTS.md (limited to 'docs/TESTS.md') diff --git a/docs/TESTS.md b/docs/TESTS.md new file mode 100644 index 000000000..8005ec9da --- /dev/null +++ b/docs/TESTS.md @@ -0,0 +1,30 @@ +# libsyntax2.0 testing infrastructure + +Libsyntax2.0 tests are in the `tests/data` directory. Each test is a +pair of files, an `.rs` file with Rust code and a `.txt` file with a +human-readable representation of syntax tree. + +The test suite is intended to be independent from a particular parser: +that's why it is just a list of files. + +The test suite is intended to be progressive: that is, if you want to +write a Rust parser, you can TDD it by working through the test in +order. That's why each test file begins with the number. Generally, +tests should be added in order of the appearance of corresponding +functionality in libsytnax2.0. If a bug in parser is uncovered, a +**new** test should be created instead of modifying an existing one: +it is preferable to have a gazillion of small isolated test files, +rather than a single file which covers all edge cases. It's okay for +files to have the same name except for the leading number. In general, +test suite should be append-only: old tests should not be modified, +new tests should be created instead. + + +Note that only `ok` tests are normative: `err` tests test error +recovery and it is totally ok for a parser to not implement any error +recovery at all. However, for libsyntax2.0 we do care about error +recovery, and we do care about precise and useful error messages. + + +Contribution opportunity: design and implement testing infrastructure +for validators. -- cgit v1.2.3