The entry point to ApprovalTests is almost always some variation of a Verify method.
These helper methods make it easy to test many common scenarios.
This method will:
- Serialize the object passed to it to the
.received.file - Compare it to the
.approved.file - Launch a DiffTool on failure
Let's take the example:
[Test]
public void Text() =>
Approvals.Verify("should be approved");This call brings together 3 things + default Approver to produce a .received. file which is compared to an .approved. file.
Note: This is a simplified version of what ApprovalTests does. You can see a full picture here
You will be using a Verify calls all the time with the ApprovalTests. The more complicated the object you are trying to test, the more you will want to use a Verify.
It is fairly common to make a custom Verify call. Anytime you find a repeated block
// Do something to an Object
// Print an Object ToString
// Verify the ToStringYou will want to extract a custom Verify helper method
public static void VerifyMyObject(MyObject o)
{
// Do something to an Object
// Print an Object ToString
// Verify the ToString
} Note: Because ApprovalTests allow testing of whole objects, you will often find this type of duplication showing more often than a traditional Unit Testing. This is because developers usually add extra complexity to their test scenarios to make results easier to test with a assert. This traditional complexity makes the duplication hard to see. All of the Verify methods were created by following the above pattern.
Writers are responsible for writing the .received. file to the disk.
They also determine the extension for both .received. and .approved. files.
Eventually, all Verify methods call:
public static void Verify(IApprovalWriter writer, IApprovalNamer namer, IApprovalFailureReporter reporter)Most of the time this is hidden in an underlying a Verify call.
The vast majority of the time you will not interact directly with the Writers.
If you want it to approve something that writes to a new type of a binary file, you would create a custom Writer.
If you simply wanted to format text this is usually done in a separate step before calling:
public static void VerifyWithExtension(string text, string fileExtensionWithDot, Func<string, string> scrubber = null)Namers are responsible for figuring out what the .approved. and .received. files should be called and where they are located.
This is primarily done by inspecting a stack trace to detect your test framework's attributes.
The naming pattern is: {ClassName}.{MethodName}.{AdditionalInformation(optional)}.approved.{Extension}
The vast majority of the time you will not interact directly with the Namers.
To support a new testing framework is a main reason you would create your own Namer.
Reporters are called only on failure. They are responsible for things such as opening Diff tools, copying commands to your clipboard or anything else that can help you determine what went wrong and so you can fix it.
Reporters are very simple. They are called with a received and approved file names on failure. Usually, they make a call to a command line using these filenames as parameters.
For example: YourDiffTool filename1 filename2
It is very common to switch between Reporters for both personal preferences (a preferred Diff tool) and contextual preferences (at this moment I want to...).
Because using the right Reporter at the right time is so important, there are multiple places they can be configured, including which Reporter is the default Reporter.
There are two reasons you want to write your custom Reporter:
- To support a tool you like that is not currently supported
- To change the order in which Diff tools are selected
The core of Approvals is that your result and expectations are saved in output files. These files allow us to verify expectations in future runs as well as use external tools.
Approvals create two files:
- Actual:
ClassName.TestMethodName.received.txt - Expected:
ClassName.TestMethodName.approved.txt
The actual files (.received.) are deleted on success and should never be checked on your source control.
The expected files (.approved.) need to be checked into your source control.
Every ApprovalTest will be generating these files.
The two main ways of customizing the output files are:
- To store all the output files in the subdirectory
- Adding additional information for Data Driven Tests or machine specific tests