Testing Scala Projects
This page will discuss common topics around working with test suites using the Mill build tool
Defining Unit Test Suites
package build
import mill._, scalalib._
object foo extends ScalaModule {
def scalaVersion = "2.13.8"
object test extends ScalaTests {
def ivyDeps = Agg(ivy"com.lihaoyi::utest:0.8.4")
def testFramework = "utest.runner.Framework"
}
}
This build defines a single module with a test suite, configured to use
"uTest" as the testing framework. Test suites are themselves ScalaModule
s,
nested within the enclosing module,
and have all the normal tasks like
foo.test.compile
available to run, but with an additional .test
task
that runs the tests. You can also run the test suite directly, in which case
it will run the .test
task as the default task for that module.
> mill foo.compile
compiling 1 ... source...
> mill foo.test.compile
compiling 1 ... source...
> mill foo.test.test
...foo.FooTests...hello ...
...foo.FooTests...world ...
> mill foo.test # same as above, `.test` is the default task for the `test` module
...foo.FooTests...hello ...
...foo.FooTests...world ...
> mill foo.test.testOnly foo.FooTests # explicitly select the test class you wish to run
...foo.FooTests...hello ...
...foo.FooTests...world ...
For convenience, you can also use one of the predefined test frameworks:
-
TestModule.Junit4
, using sbt/junit-interface -
TestModule.Junit5
, using sbt/sbt-jupiter-interface -
TestModule.TestNg
, using TestNg -
TestModule.Munit
, using munit -
TestModule.ScalaTest
, using ScalaTest -
TestModule.Specs2
, using Specs2 -
TestModule.Utest
, using uTest -
TestModule.ZioTest
, using ZioTest
Each testing framework has their own flags and configuration options that are documented on their respective websites, so please see the links above for more details on how to use each one from the command line.
object bar extends ScalaModule {
def scalaVersion = "2.13.8"
object test extends ScalaTests with TestModule.Utest {
def ivyDeps = Agg(ivy"com.lihaoyi::utest:0.8.4")
}
}
> mill bar.test
...bar.BarTests...hello ...
...bar.BarTests...world ...
You can also select multiple test suites in one command using Mill’s Task Query Syntax
> mill __.test
...bar.BarTests...hello ...
...bar.BarTests...world ...
...foo.FooTests...hello ...
...foo.FooTests...world ...
...
Mill provides three ways of running tests
> mill foo.test
-
foo.test
: runs tests in a subprocess in an emptysandbox/
folder. This is short forfoo.test.test
, astest
is the default task forTestModule
s.
> mill foo.test.testCached
-
foo.test.testCached
: runs the tests in an emptysandbox/
folder and caches the results if successful. This can be handy if you are you working on some upstream modules and only want to run downstream tests which are affected: usingtestCached
, downstream tests which are not affected will be cached after the first run and not re-run unless you change some file upstream of them.
> mill foo.test.testLocal
-
foo.test.testLocal
: runs tests in an isolated classloader as part of the main Mill process. This can be faster than.test
, but is less flexible (e.g. you cannot passforkEnv
) and more prone to interference (testLocal
runs do not run in sandbox folders)
It is common to run tests with -w/--watch enabled, so that once you save a file to disk the selected tests get re-run.
Mill runs tests with the working directory set to an empty
sandbox/ folder by default.
Tests can access files from their resource directory via the environment variable
MILL_TEST_RESOURCE_DIR which provides the path to the resource folder, and additional
paths can be provided to test via forkEnv . See
Classpath and Filesystem Resources
for more details.
|
If you want to pass any arguments to the test framework, you can pass them after
foo.test
in the command line. e.g. uTest
lets you pass in a selector to decide which test to run, which in Mill would be:
> mill bar.test bar.BarTests.hello
...bar.BarTests...hello ...
This command only runs the hello
test case in the bar.BarTests
test suite class.
Test Dependencies
Mill has no |
You might be used to test-scoped dependencies from other build tools like
Maven, Gradle or sbt. As test modules in Mill are just regular modules,
there is no special need for a dedicated test-scope. You can use ivyDeps
and runIvyDeps
to declare dependencies in test modules, and test modules
can use their moduleDeps
to also depend on each other
package build
import mill._, scalalib._
object qux extends ScalaModule {
def scalaVersion = "2.13.8"
def moduleDeps = Seq(baz)
object test extends ScalaTests {
def ivyDeps = Agg(ivy"com.lihaoyi::utest:0.8.4")
def testFramework = "utest.runner.Framework"
def moduleDeps = super.moduleDeps ++ Seq(baz.test)
}
}
object baz extends ScalaModule {
def scalaVersion = "2.13.8"
object test extends ScalaTests {
def ivyDeps = Agg(ivy"com.lihaoyi::utest:0.8.4")
def testFramework = "utest.runner.Framework"
}
}
In this example, not only does qux
depend on baz
, but we also make
qux.test
depend on baz.test
.
That lets qux.test
make use of the
BazTestUtils
class that baz.test
defines, allowing us to re-use this
test helper throughout multiple modules' test suites
> ./mill qux.test
Using BazTestUtils.bazAssertEquals
... qux.QuxTests...simple ...
...
> ./mill baz.test
Using BazTestUtils.bazAssertEquals
... baz.BazTests...simple ...
...
Defining Integration Test Suites
You can also define test suites with different names other than test
. For example,
the build below defines a test suite with the name integration
, in addition
to that named test
.
package build
import mill._, scalalib._
object qux extends ScalaModule {
def scalaVersion = "2.13.8"
object test extends ScalaTests with TestModule.Utest {
def ivyDeps = Agg(ivy"com.lihaoyi::utest:0.8.4")
}
object integration extends ScalaTests with TestModule.Utest {
def ivyDeps = Agg(ivy"com.lihaoyi::utest:0.8.4")
}
}
These two test modules will expect their sources to be in their respective qux/test
and
qux/integration
folder respectively
> mill 'qux.{test,integration}' # run both test suites
...qux.QuxTests...hello...
...qux.QuxTests...world...
...qux.QuxIntegrationTests...helloworld...
> mill __.integration.testCached # run all integration test suites
Test Grouping
Test Grouping is an opt-in feature that allows you to take a single
test module and group the test classes such that each group will
execute in parallel when you call test
. Test grouping is enabled
by overriding def testForkGrouping
, as shown below:
package build
import mill._, scalalib._
object foo extends ScalaModule {
def scalaVersion = "2.13.8"
object test extends ScalaTests {
def ivyDeps = Agg(ivy"com.lihaoyi::utest:0.8.4")
def testFramework = "utest.runner.Framework"
def testForkGrouping = discoveredTestClasses().grouped(1).toSeq
}
}
package foo
import utest._
object HelloTests extends TestSuite {
def tests = Tests {
test("hello") {
println("Testing Hello")
val result = Foo.hello()
assert(result.startsWith("Hello"))
Thread.sleep(1000)
println("Testing Hello Completed")
result
}
}
}
package foo
import utest._
object WorldTests extends TestSuite {
def tests = Tests {
test("world") {
println("Testing World")
val result = Foo.hello()
assert(result.endsWith("World"))
Thread.sleep(1000)
println("Testing World Completed")
result
}
}
}
In this example, we have one test module foo.test
, and two test classes
HelloTests
and WorldTests
. By default, all test classes in the same
module run sequentially in the same JVM, but with testForkGrouping
we can break up the
module and run each test class in parallel in separate JVMs, each with their own
separate sandbox
folder and .log
file:
> mill foo.test
> find out/foo/test/test.dest
...
out/foo/test/test.dest/foo.HelloTests.log
out/foo/test/test.dest/foo.HelloTests/sandbox
out/foo/test/test.dest/foo.WorldTests.log
out/foo/test/test.dest/foo.WorldTests/sandbox
out/foo/test/test.dest/test-report.xml
Test grouping allows you to run tests in parallel while keeping things deterministic and debuggable: parallel test groups will not write over each others files in their sandbox, and each one will have a separate set of logs that can be easily read without the others mixed in
In this example, def testForkGrouping = discoveredTestClasses().grouped(1).toSeq
assigns
each test class to its own group, running in its own JVM. This comes with some overhead
on a per-JVM basis, so if your test classes are numerous and small you may want to assign
multiple test classes per group. You can also configure testForkGrouping
to choose which
test classes you want to run together and which to run alone:
-
If some test classes are much slower than others, you may want to put the slow test classes each in its own group to reduce latency, while grouping multiple fast test classes together to reduce the per-group overhead of spinning up a separate JVM.
-
Some test classes may have global JVM-wide or filesystem side effects that means they have to run alone, while other test classes may be better-behaved and OK to run in a group
In general, testForkGrouping
leaves it up to you how you want to group your tests for
execution, based on the unique constraints of your test suite.