Skip to content

Latest commit

 

History

History
109 lines (78 loc) · 4.7 KB

Writers.md

File metadata and controls

109 lines (78 loc) · 4.7 KB
Raw

Writers

Contents

Default Behaviour

By default, when Approval Tests verifies an object, it uses the StringWriter class to write out the string representation of the object.

And by default, StringWriter gives the saved file the extension .txt.

StringWriter implements the ApprovalWriter interface.

Using custom writers

Suppose that you are serialising an object that cannot easily be represented in a text file, such as an image. In this case, the built-in StringWriter is not suitable, and you will need to write and use a custom implementation of ApprovalWriter.

Here is a simple example of using a custom writer to produce an HTML file.

HtmlWriter writer("<h1>hello world</h1>", ".html");
ApprovalTests::Approvals::verify(writer);

snippet source | anchor

Using custom filename extensions

Suppose that you are serializing an object in some text format like JSON or CSV. By writing to this file extension, different tools will render it appropriately.

If all you want to do is change the file extension, here is how:

ApprovalTests::Approvals::verify(
    "<h1>hello world</h1>",
    ApprovalTests::Options().fileOptions().withFileExtension(".html"));

snippet source | anchor

Empty Files

Most reporters will create a .approved. file if one does not exist, as most diff tools do not handle a missing file well. By default, these empty files are empty text files with an empty string "".

If the file extension is not a text file (for example, a PNG), you will still get this behaviour, which can result in some diff tools saying 'this is not a valid file'.

ApprovalTests allows for you to customize this behaviour.

For a tool which will help you with this, see EmptyFiles.

Customizing by File Extension

To add new behaviour for a specific file extension, you can register customizations as follows:

ApprovalTests::EmptyFileCreator htmlCreator = [](std::string fileName) {
    ApprovalTests::StringWriter s("<!doctype html><title>TITLE</title>");
    s.write(fileName);
};
ApprovalTests::EmptyFileCreatorByType::registerCreator(".html", htmlCreator);

snippet source | anchor

This will leave the creation of files with all other extensions alone, and will last for the remainder of program execution, or until a new creator for this file extension is registered.

Full Customization

Here is an example of replacing the entire empty file creation code, for the lifetime of the disposer.

New .approved. files will be created with minimal, valid HTML content, and everything else will be empty.

ApprovalTests::EmptyFileCreator htmlCreator = [](std::string fileName) {
    std::string contents = "";
    if (ApprovalTests::StringUtils::endsWith(fileName, ".html"))
    {
        contents = "<!doctype html><title>TITLE</title>";
    }
    ApprovalTests::StringWriter s(contents);
    s.write(fileName);
};
auto disposer = ApprovalTests::FileUtils::useEmptyFileCreator(htmlCreator);

snippet source | anchor

Back to User Guide