Configuration.md

Configuration

Contents

• What is configurable?
  • Package Level Settings
• Alternative Base Directory for Output Files
• PackageLevelSettings
• Alternative source path discovery
  • Defining alternatives

What is configurable?

Configuration of ApprovalTests mainly occurs via @Annotations and PackageSettings. (the API is also extendible) Currently you can configure:

• Reporters (package/class/method)
• FrontLoadedReporters (package/class/method)
• ApprovalSubdirectories (package)
• How Approvals discovers your source path

Package Level Settings

The following options will be read by ApprovalTests:

public class PackageSettings {

    public static ApprovalFailureReporter FrontloadedReporter = new JunitReporter();
    public static ApprovalFailureReporter UseReporter = new ClipboardReporter();
    public static String UseApprovalSubdirectory = "approvals";
    public static String ApprovalBaseDirectory = "../resources";
}

^{snippet source | anchor}

The approved & received files will now be created in the subdirectory /approvals/ for any test in the same package as this file, or any test in any subpackage under this.

You can find out more about Package Level settings here

Alternative Base Directory for Output Files

Approved and received files can be stored in a different branch of the code base (for example, under the /resources/ folder).

To do so, write a class as follows:

public class PackageSettings
{
  public static String ApprovalBaseDirectory = "../resources";
}

^{snippet source | anchor}

The approved and received files will now be created in the directory /source/test/resources/ for any test in the same package as this file, or any test in any under this.

PackageLevelSettings

Package Level Settings allows for programmatic setting of configuration at the package level. It follows the principle of least surprise.

Your Package Leveling configuration must be in class called PackageSettings. The fields can be private, public and or static. They will be picked up regardless. All methods will be ignored.

For example if you had a class:

package org.packagesettings;

public class PackageSettings
{
  public String        name     = "Llewellyn";
  private int          rating   = 10;
  public static String lastName = "Falco";
}

^{snippet source | anchor}

If you where to call at the org.packagesettings level.

Map<String, Settings> settings = PackageLevelSettings.get();

^{snippet source | anchor}

Then you would get the following settings

lastName : Falco [from org.packagesettings.PackageSettings] 
name : Llewellyn [from org.packagesettings.PackageSettings] 
rating : 10 [from org.packagesettings.PackageSettings]

^{snippet source | anchor}

However, if you also had

package org.packagesettings.subpackage;

public class PackageSettings
{
  public String   name        = "Test Name";
  private boolean rating      = true;
  public String   ratingScale = "logarithmic";
}

^{snippet source | anchor}

and you ran the same code but from the org.packagesettings.subpackage
then you would get a blended view of the two classes where anything in the sub-package would override the parents.

lastName : Falco [from org.packagesettings.PackageSettings] 
name : Test Name [from org.packagesettings.subpackage.PackageSettings] 
rating : true [from org.packagesettings.subpackage.PackageSettings] 
ratingScale : logarithmic [from org.packagesettings.subpackage.PackageSettings]

^{snippet source | anchor}

Alternative source path discovery

Compiled class files do not contain information about the files they are compiled from. As such ApprovalTests has an algorithm to guess the source file's location. This works most of the time. In the off chance that it doesn't work for you, you can fix it manually using the following injection point.

Defining alternatives

Function2<Class, String, File> myFinder = new Function2<Class, String, File>()
{
  @Override
  public File call(Class clazz, String fileName)
  {
    return new File("src/test/java/" + clazz.getPackage().getName().replaceAll("\\.", "/"));
  }
};

^{snippet source | anchor}

Using alternatives

Thanks to the try block, the default is restored afterwards allowing tests to be independent. You might want to do this at a higher level.

try (SourceDirectoryRestorer sdr = TestUtils.registerSourceDirectoryFinder(myFinder))
{
  Approvals.verify("Ragunath");
}

^{snippet source | anchor}

---

Back to User Guide