Getting Started
Tutorials & Guides
Reference
Concepts & Explanations
Design Partners
Recipe Testing
OpenRewrite provides infrastructure that allows developers to quickly build tests to exercise their recipe and then assert that the recipe has made the correct changes. To leverage Rewrite's testing facilities, you can add the following dependencies to your project's build file:
Maven
Gradle
pom.xml
1
<project>
2
<properties>
3
<junit.version>5.8.2</junit.version>
4
<kotlin.version>1.5.31</kotlin.version>
5
<assertj.version>3.23.1</assertj.version>
6
</properties>
7
...
8
<dependencyManagement>
9
<dependencies>
10
<dependency>
11
<groupId>org.openrewrite.recipe</groupId>
12
<artifactId>rewrite-recipe-bom</artifactId>
13
<version>1.3.0</version>
14
<type>pom</type>
15
<scope>import</scope>
16
</dependency>
17
</dependencies>
18
</dependencyManagement>
19
...
20
<dependencies>
21
<dependency>
22
<groupId>org.openrewrite</groupId>
23
<artifactId>rewrite-test</artifactId>
24
<scope>test</scope>
25
</dependency>
26
<dependency>
27
<groupId>org.junit.jupiter</groupId>
28
<artifactId>junit-jupiter-api</artifactId>
29
<version>${junit.version}</version>
30
<scope>test<scope>
31
</dependency>
32
<dependency>
33
<groupId>org.junit.jupiter</groupId>
34
<artifactId>junit-jupiter-engine</artifactId>
35
<version>${junit.version}</version>
36
<scope>test<scope>
37
</dependency>
38
<!-- Optional dependencies and only needed if writing tests in Kotlin. -->
39
<dependency>
40
<groupId>org.jetbrains.kotlin</groupId>
41
<artifactId>kotlin-reflect</artifactId>
42
<version>${kotlin.version}</version>
43
<scope>test<scope>
44
</dependency>
45
<dependency>
46
<groupId>org.jetbrains.kotlin</groupId>
47
<artifactId>kotlin-stdlib-jdk8</artifactId>
48
<version>${kotlin.version}</version>
49
<scope>test<scope>
50
</dependency>
51
<!-- Optional dependency on assertJ to provide fluent assertions. -->
52
<dependency>
53
<groupId>org.assertj</groupId>
54
<artifactId>assertj-core</artifactId>
55
<version>${assertj.version}</version>
56
<scope>test<scope>
57
</dependency>
58
</dependencies>
59
</project>
Copied!
​
1
plugins {
2
`java-library`
3
​
4
id("org.jetbrains.kotlin.jvm") version "1.5.21"
5
}
6
​
7
val rewriteBomVersion = "1.3.0"
8
...
9
dependencies {
10
implementation(platform("org.openrewrite.recipe:rewrite-recipe-bom:${rewriteBomVersion}"))
11
​
12
testImplementation("org.openrewrite:rewrite-test")
13
testImplementation("org.junit.jupiter:junit-jupiter-api:latest.release")
14
testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:latest.release")
15
​
16
// Optional dependencies and only needed if writing tests in Kotlin.
17
testImplementation("org.jetbrains.kotlin:kotlin-reflect")
18
testImplementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8")
19
​
20
// Optional dependency on assertJ to provide fluent assertions.
21
testImplementation("org.assertj:assertj-core:latest.release")
22
}
23
​
Copied!
The tests in this guide are written in Kotlin to take advantage of multi-line strings. This is completely optional but makes it easier to express source code (as strings) when providing the before/after state that is processed by a recipe.
RewriteTest Interface
RewriteTest InterfaceOpenRewrite provides a convenient interface that acts as both an entry point in which to exercise recipes in tests and also provides a fluent API for expressing recipe and source file configuration. For the sake of this guide, let's assume we have the following recipe that ensures a class's package declaration is all lowercase:
1
package org.openrewrite.java.cleanup;
2
​
3
import org.openrewrite.ExecutionContext;
4
import org.openrewrite.Recipe;
5
import org.openrewrite.internal.lang.Nullable;
6
import org.openrewrite.java.ChangePackage;
7
import org.openrewrite.java.JavaIsoVisitor;
8
import org.openrewrite.java.tree.J;
9
​
10
import java.time.Duration;
11
import java.util.Collections;
12
import java.util.Set;
13
​
14
public class LowercasePackage extends Recipe {
15
@Override
16
public String getDisplayName() {
17
return "Rename packages to lowercase";
18
}
19
​
20
@Override
21
public String getDescription() {
22
return "By convention, all Java package names should contain only lowercase letters, numbers, and dashes. " +
23
"This recipe converts any uppercase letters in package names to be lowercase.";
24
}
25
​
26
@Override
27
public Set<String> getTags() {
28
return Collections.singleton("RSPEC-120");
29
}
30
​
31
@Override
32
public @Nullable Duration getEstimatedEffortPerOccurrence() {
33
return Duration.ofMinutes(5);
34
}
35
​
36
@Override
37
protected JavaIsoVisitor<ExecutionContext> getVisitor() {
38
return new JavaIsoVisitor<ExecutionContext>() {
39
@Override
40
public J.Package visitPackage(J.Package pkg, ExecutionContext executionContext) {
41
String packageText = pkg.getExpression().print(getCursor()).replaceAll("\\s", "");
42
String lowerCase = packageText.toLowerCase();
43
if(!packageText.equals(lowerCase)) {
44
doNext(new ChangePackage(packageText, lowerCase, true));
45
}
46
return pkg;
47
}
48
};
49
}
50
}
Copied!
In order to test this recipe, at a minimum the testing class will implement
RewriteTest , define recipe/parser configuration via RecipeSpec, and define one or more source file assertions using the fluent API provided by the interface. As an example, the following test class overrides the defaults(RecipeSpec)method to define which recipe will be used by all tests defined in the class. Each of the three tests demonstrates how the fluent API is used to create source files and then assert the recipe has made the correct transformations to those files.1
package org.openrewrite.java.cleanup
2
​
3
import org.assertj.core.api.Assertions.assertThat
4
import org.junit.jupiter.api.Test
5
import org.openrewrite.PathUtils
6
import org.openrewrite.java.JavaParser
7
import org.openrewrite.test.RecipeSpec
8
import org.openrewrite.test.RewriteTest
9
import java.nio.file.Paths
10
​
11
interface LowercasePackageTest : RewriteTest {
12
​
13
// Note, you can define defaults for the RecipeSpec and these defaults will be
14
// used for all tests.
15
override fun defaults(spec: RecipeSpec) {
16
spec
17
.recipe(LowercasePackage()) // Which recipe each test should run
18
}
19
​
20
// A java source file that already has a lowercase package name should be left
21
// unchanged.
22
@Test
23
fun packageIsAlreadyLowercase() = rewriteRun(
24
java("""
25
package com.lowercase;
26
class A {}
27
"""),
28
)
29
​
30
// Assert that a java source file with uppercase letters in its package name
31
// is correctly transformed by the recipe.
32
@Test
33
fun lowerCasePackage() = rewriteRun(
34
// Each test can customize the RecipeSpec prior to execution of the test.
35
// In this case, the recipe has already been defined in defaults(), and
36
// this test will use a parser that logs warnings and errors
37
{ spec -> spec
38
.parser(JavaParser.fromJavaVersion()
39
.logCompilationWarningsAndErrors(false)
40
.build())
41
},
42
java(
43
// The Java source file before transformation:
44
"""
45
package com.UPPERCASE.CamelCase;
46
class A {}
47
""",
48
// The expected Java source file after transformation.
49
"""
50
package com.uppercase.camelcase;
51
class A {}
52
""")
53
// An optional callback that can be used after the recipe has been
54
// executed to assert additional conditions on the resulting source file.
55
{ spec ->
56
spec.afterRecipe { cu ->
57
assertThat(PathUtils.equalIgnoringSeparators(cu.sourcePath, Paths.get("com/uppercase/camelcase/A.java"))).isTrue
58
}
59
}
60
)
61
62
// This test defines both source files and asserts that each file is correctly
63
// handled by the recipe.
64
@Test
65
fun combinedExample() = rewriteRun(
66
// Assert the first source file is not modified.
67
java("""
68
package com.lowercase;
69
class A {}
70
"""),
71
//Assert the second source file is modified.
72
java(
73
"""
74
package com.UPPERCASE.CamelCase;
75
class A {}
76
""",
77
"""
78
package com.uppercase.camelcase;
79
class A {}
80
""")
81
}
82
)
83
}
84
​
Copied!
RecipeSpec
RecipeSpecThe
RecipeSpec class drives which recipe will be executed for a given test and allows a developer to customize aspects of the environment in which the recipe runs. The RecipeSpec can be used to customize the parser(s) that will be used to compile source files, manipulate the `ExecutionContext`, and provides convinient callbacks that can be used to execute code before/after the test.The
RewriteTest.defaults() method can be used to define common RecipeSpec customizations that should be applied for all tests in the testing class. Additionally, there are overloaded versions of RewriteTest.runRecipe that allow the RecipeSpec to be further customized for that specific test.SourceSpecs
A
SourceSpec is used to define a source file that will be parsed during a test and then processed within the environment defined by the RecipeSpec. At a bare minimum a SourceSpec will define the type of source file and its initial ("before") contents. The testing infrastructure will select the appropriate parser based on the source file type and parser the contents into a SourceFile. In a majority of cases, a SourceSpec will also define an "after" state which defines what the source file contents will look like after it has been processed by the given recipe environment. The testing framework will automatically fail a given test if the source file has not been transformed into its "after" state. Any SourceSpec that does not define an "after" state is implicitly saying "the recipe should not make any changes to this source file.
A developer can assert additional conditions on a source file by using the
afterRecipe callback that is defined on the SourceSpec. This can be convenient when asserting conditions on the resulting semantic model that are not represented in the rendering of the source code after the recipe has transformed the source file.The
RewriteTest interface provides fluent entry points to create the various types of source specs.Advanced Recipe Testing
Customizing Source File Paths and Markers
Occasionally, it is desirable to modify a specific source file prior to being processed through the Recipe testing environment. This type of customization can be achieved by using the callback method provided as an optional parameter on the fluent API. As an example, let us assume a recipe has been built to manipulate properties within an "application.properties" source file but only when its path is "main/resources/application.properties". To correctly define the path for the source file, a developer can leverage the callback:
1
fun propertiesChangeTest() = rewriteRun(
2
properties(
3
// Before
4
"""
5
server.port=8080
6
""",
7
// After
8
"""
9
server.port=80
10
"""
11
) {p -> p.path(Paths.get("main/resources/application.properties")
12
)
Copied!
Export as PDF
Copy link