scala-wrench

License	MIT
Categories	Scala Languages
GroupId	org.xmid
ArtifactId	scala-wrench_0.19
Last Version	0.0.4
Release Date	Oct 11, 2019
Type	jar
Description	scala-wrench scala-wrench
Project URL	https://github.com/liufengyun/scala-wrench
Project Organization	org.xmid
Source Code Management	https://github.com/liufengyun/scala-wrench

Download scala-wrench_0.19

Filename	Size
scala-wrench_0.19-0.0.4.pom
scala-wrench_0.19-0.0.4.jar	105 KB
scala-wrench_0.19-0.0.4-sources.jar	9 KB
scala-wrench_0.19-0.0.4-javadoc.jar	189 bytes

How to add to project

Apache Maven

<!-- https://jarcasting.com/artifacts/org.xmid/scala-wrench_0.19/ -->
<dependency>
    <groupId>org.xmid</groupId>
    <artifactId>scala-wrench_0.19</artifactId>
    <version>0.0.4</version>
</dependency>

Gradle Groovy

// https://jarcasting.com/artifacts/org.xmid/scala-wrench_0.19/
implementation 'org.xmid:scala-wrench_0.19:0.0.4'

Gradle Kotlin

// https://jarcasting.com/artifacts/org.xmid/scala-wrench_0.19/
implementation ("org.xmid:scala-wrench_0.19:0.0.4")

Apache Buildr

'org.xmid:scala-wrench_0.19:jar:0.0.4'

Apache Ivy

<dependency org="org.xmid" name="scala-wrench_0.19" rev="0.0.4">
  <artifact name="scala-wrench_0.19" type="jar" />
</dependency>

Groovy Grape

@Grapes(
@Grab(group='org.xmid', module='scala-wrench_0.19', version='0.0.4')
)

Scala SBT

libraryDependencies += "org.xmid" % "scala-wrench_0.19" % "0.0.4"

Leiningen

[org.xmid/scala-wrench_0.19 "0.0.4"]

Dependencies

compile (1)

Group / Artifact	Type	Version
ch.epfl.lamp : dotty-library_0.19	jar	0.19.0-RC1

test (2)

Group / Artifact	Type	Version
ch.epfl.lamp : dotty-compiler_0.19	jar	0.19.0-RC1
com.novocode : junit-interface	jar	0.11

Project Modules

There are no modules declared in this project.

🔧 Scala-Wrench

Wrench is a micro test framework for developing compiler plugins for Dotty.

It is supposed to make your life easier if

• you are a PL researcher and want to write a plugin to demonstrate research result
• you are a compiler hacker and want to write a solid plugin for production usage

Usage

SBT setting

Add Wrench as a test dependency in SBT:

libraryDependencies += "org.xmid" %% "scala-wrench" % "0.0.4" % "test"
// for Dotty 0.17, use 0.0.2

Also, set the option fork to true:

fork := true    // important

Writing tests

Now, you can specify the tests like the following:

class Tests {
    @Test def posTests = testsIn("tests/pos").shouldCompile

    @Test def negTests = testsIn("tests/neg").shouldNotCompile

    @Test def runTests = testsIn("tests/run").shouldRun

    @Test def pluginDivZeroTests = withPlugin("tests/plugins/divideZero") {
        testsIn("tests/plugins/divideZeroTests").shouldNotCompile
    }
}

Here is an example test file: Tests.scala

DSL

Test Cases

file("tests/pos/hello.scala")

Create a single file test case for the file tests/pos/hello.scala. You can optionally put a check file hello.check inside the same directory for run tests.

directory("tests/pos/lib")

Create a directory test case for the path tests/pos/lib. You can optionally put a check file lib.check inside the directory tests/pos/lib for run tests.

The source files in the directory may be compiled in groups. The groups are recognized and ordered by file name endings. For example, given the following files in the directory:

• A_1.scala
• B_1.scala
• C_2.scala
• D_2.scala

The files A_1.scala and B_1.scala will be compiled first, and the compiled class files will be used to compile C_2.scala and D_2.scala.

testsIn("tests/pos")

Create a list of test cases for each file or directory under test/pos. Non-Scala files are ignored. Each sub-directory will be a directory test, each Scala file will be a file test.

Assertions

checkCompile

Compilation of the test(s) should produce the same errors as specified in source code. The errors should match code line as well as the number of errors.

You can annotate the source code with // error to indicate that a compilation error is expected at the line. Multiple annotations at the same line is supported by repeating // error.

shouldCompile

The test(s) should compile without errors.

shouldRun

The test(s) should compile and run without errors. If a check file is provided, the output of the run should be exactly the same as the content of the check file.

Plugins

withPlugin(paths) { ... }

First compile the plugins in paths, then enable the plugins for all compilation in the body.

withPluginBin(paths) { ... }

Enable precompiled plugins in paths for all compilations in the body.

Parallelization

To run the tests sequentially, use the following TestContext:

 implicit val testCtx: TestContext = new DefaultContext

The ParallelContext supports running the tests in parallel:

  implicit val testCtx: TestContext = new ParallelContext

FAQ

How to make the plugin available in testing

Suppose that your plugin is an SBT project, given the following setting in SBT:

javaOptions in Test ++= {
  lazy val pluginJars = (Compile / packageBin / artifactPath).value

  List("-Dplugin=" + pluginJars)
}

You can use the plugin as follows in testing:

withPluginBin(sys.props("plugin")) { ... }

How to put tests under the project root directory

Suppose that your plugin project is located in a sub-directory plugin/ under the project root directory, you can use the following code to reset the default working directory:

baseDirectory in Test := baseDirectory.value / ".."

Then you can write testsIn("tests/pos/") instead of testsIn("../tests/pos/").

How to check compiler warnings

If you want to check that a warning (instead of an error) should happen at a line, enable the compiler option -Xfatal-warning.

implicit val flags: TestFlags = Defaults.defaultOptions.and("-Xfatal-warnings")

How to test my plugin on the compiler test set?

If you want your plugin to be used by the public, it is highly recommended to test it against the compiler test set.

First, clone the Dotty repo, then make the following changes in the source:

--- a/compiler/test/dotty/tools/vulpix/TestConfiguration.scala
+++ b/compiler/test/dotty/tools/vulpix/TestConfiguration.scala
@@ -8,7 +8,8 @@ object TestConfiguration {

   val noCheckOptions = Array(
     "-pagewidth", "120",
-    "-color:never"
+    "-color:never",
+    "-Xplugin:lib/my-plugin_0.19-0.0.1.jar"
   )

Now you can run the test set:

sbt dotty-bootstrapped/testCompilation

Credits

The code takes inspiration from the test framework for Dotty, and follows its convention on error annotations and ending-based test groups.

Versions

Version
0.0.4 Oct 11, 2019