From 29ff5ad791a19632a22eb8f4d520277fbbef3bfb Mon Sep 17 00:00:00 2001 From: Felix Mulder Date: Thu, 30 Mar 2017 15:52:17 +0200 Subject: Add documentation for new parallel testing suite --- docs/docs/contributing/testing.md | 89 +++++++++++++++++++++++++++++++++ docs/docs/contributing/workflow.md | 16 ++++-- docs/docs/internals/higher-kinded-v2.md | 9 ++-- docs/sidebar.yml | 2 + 4 files changed, 109 insertions(+), 7 deletions(-) create mode 100644 docs/docs/contributing/testing.md (limited to 'docs') 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 +--- + + + +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 `/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. diff --git a/docs/docs/contributing/workflow.md b/docs/docs/contributing/workflow.md index 6e7f5b9a0..3c654e8f6 100644 --- a/docs/docs/contributing/workflow.md +++ b/docs/docs/contributing/workflow.md @@ -57,11 +57,21 @@ $ sbt To test a specific test tests/x/y.scala (for example tests/pos/t210.scala): ```bash -> partest-only-no-bootstrap --show-diff --verbose tests/partest-generated/x/y.scala +> filterTest .*pos/t210.scala ``` -Currently this will re-run some unit tests and do some preprocessing because of -the way partest has been set up. +The filterTest task takes a regular expression as its argument. For example, +you could run a negative and a positive test with: + +```bash +> filterTest (.*pos/t697.scala)|(.*neg/i2101.scala) +``` + +or if they have the same name, the equivalent can be achieved with: + +```bash +> filterTest .*/i2101.scala +``` ## Inspecting Trees with Type Stealer ## diff --git a/docs/docs/internals/higher-kinded-v2.md b/docs/docs/internals/higher-kinded-v2.md index 4676d3ebd..3c857d4d5 100644 --- a/docs/docs/internals/higher-kinded-v2.md +++ b/docs/docs/internals/higher-kinded-v2.md @@ -3,10 +3,11 @@ layout: doc-page title: "Higher-Kinded Types in Dotty" --- -**This page is out of date and preserved for posterity. Please see [Implementing -Higher-Kinded Types in -Dotty](http://guillaume.martres.me/publications/dotty-hk.pdf) for a more up to -date version** + Higher-Kinded Types in Dotty V2 =============================== diff --git a/docs/sidebar.yml b/docs/sidebar.yml index 7ffa1f5b7..4065cff20 100644 --- a/docs/sidebar.yml +++ b/docs/sidebar.yml @@ -23,6 +23,8 @@ sidebar: url: docs/contributing/intellij-idea.html - title: Workflow url: docs/contributing/workflow.html + - title: Testing + url: docs/contributing/testing.html - title: Internals subsection: - title: Backend -- cgit v1.2.3