diff options
Diffstat (limited to 'docs/docs/contributing/testing.md')
-rw-r--r-- | docs/docs/contributing/testing.md | 89 |
1 files changed, 89 insertions, 0 deletions
diff --git a/docs/docs/contributing/testing.md b/docs/docs/contributing/testing.md new file mode 100644 index 000000000..07aab1918 --- /dev/null +++ b/docs/docs/contributing/testing.md @@ -0,0 +1,89 @@ +--- +layout: doc-page +title: Testing in Dotty +--- + +<aside class="warning"> +This page should be updated as soon as scala-partest is removed +</aside> + +Running all tests in Dotty is as simple as: + +```bash +$ sbt test +``` + +There are currently several forms of tests in Dotty. These can be split into +two categories: + +## Unit tests +These tests can be found in `<sub-project>/test` and are used to check +functionality of specific parts of the codebase in isolation e.g: parsing, +scanning and message errors. + +Running a single unit test class from sbt is as simple as: + +```bash +> testOnly absolute.path.to.TestClass +``` + +You can further restrict the executed tests to a subset of `TestClass` methods +as follows: + +```bash +> testOnly absolute.path.to.TestClass -- *methodName +``` + +## Integration tests +These tests are Scala source files expected to compile with Dotty (pos tests), +along with their expected output (run tests) or errors (neg tests). + +All of these tests are contained in the `./tests/*` directories. + +## scala-partest +Historically these tests needed a structure which was generated by running the +unit tests, and then that structure was in turn used by +[scala-partest](http://github.com/scala/scala-partest) to run compilation tests +in parallel. + +This test suite can still be used (and is currently a part of the CI to check +that it has the same outcome as the new test suite). It is invoked from sbt by +running one of the following commands: + +```bash +> partest-only-no-bootstrap +> partest-only +> partest +``` + +- `partest-only-no-bootstrap` will only run the integration tests +- `partest-only` will bootstrap the compiler and run the integration tests +- `partest` will bootstrap the compiler, run the unit tests and then the + integration tests + +## dotty parallel test suite +The new test suite will soon become the standard integration test runner. It +has several advantages over the old implementation: + +- integrates with JUnit, without the need for setup +- reuses the same VM for compilation +- allows filtering of tests +- runs much faster (almost 2x) + +Currently to run these tests you need to invoke from sbt: + +```bash +> testOnly dotty.tools.dotc.CompilationTests +``` + +This might be aliased in the future. It is also possible to run tests filtered +by using: + +```bash +> filterTest .*i2147.scala +``` + +This will run both the test `./tests/pos/i2147.scala` and +`./tests/partest-test/i2147.scala` since both of these match the given regular +expression. This also means that you could run `filterTest .*` to run all +integration tests. |