Skip to main content

Module 5: Preconditions

Preconditions are recipes that run before other recipes to limit which source files the recipe will run on. Preconditions are often used to ensure a recipe only runs against certain files or directories – but any recipe which is not a ScanningRecipe can technically be used as a precondition.

When a recipe is used as a precondition, any file it would make a change to is considered to meet the precondition. When more than one recipe is used, all of them must make a change to the file for it to be considered to "meet the precondition".

One substantial benefit of preconditions is that other recipes don't need to individually support options to limit themselves to a particular path.

Exercise 5: Adding preconditions to a recipe​

Let's update the stringutils.yml recipe to only run on sources that are likely tests, by adding a precondition that uses the org.openrewrite.java.search.IsLikelyTest recipe.

Goals for this exercise​

  • Discover common preconditions, and learn how to combine those with recipes.

Steps​

  1. Open the UseApacheStringUtils YAML file (src/main/resources/META-INF/rewrite/stringutils.yml) once again.
  2. Add a preconditions field to the recipe between the description and recipeList fields.
  3. Open the unit test src/test/java/com/yourorg/UseApacheStringUtilsTest.java.
    • Run the tests – they should fail and not make any changes. This is because the precondition has not been met since the sources are not identified as tests. We can fix that with the following steps:
      • Add a static import on org.openrewrite.java.Assertions.srcTestJava.
      • Wrap the java(String, String) methods with srcTestJava() to indicate that the sources are tests. Make sure to do this in all three tests.
    • Here's an example of what this should look like.
    • Run the tests again, and verify that they now pass.
  4. You may be interested in exploring other Find recipes in the OpenRewrite recipe catalog. These are often used as preconditions for recipes:

Takeaways​

  • Preconditions are used to limit which source files a recipe is run on.
  • Common preconditions can be used to target specific files or directories.
  • When a recipe is used as a precondition, any file it would make a change to is considered to "meet the precondition" – which means the main recipe will run against it.
  • Preconditions themselves do not make changes to the source code, but are used to limit which files a recipe is run on.