Core Classes

Note

All classes and symbols listed here are in the ApprovalTests namespace.

ApprovalComparator

ApprovalComparator is an interface that determines if received and approved files are equivalent.

For more information, see Custom Comparators.

class ApprovalComparator

Subclassed by TextFileComparator

Public Functions

virtual ~ApprovalComparator() = default

virtual bool contentsAreEquivalent(std::string receivedPath, std::string approvedPath) const = 0

ApprovalException and subclasses

ApprovalException is the base class for ApprovalTest-specific exceptions.

class ApprovalException : public exception

Subclassed by ApprovalMismatchException, ApprovalMissingException

Public Functions

explicit ApprovalException(const std::string &msg)

virtual const char *what() const noexcept override

ApprovalMismatchException

ApprovalMismatchException is thrown if received and approved files differ.

class ApprovalMismatchException : public ApprovalException

Public Functions

ApprovalMismatchException(const std::string &received, const std::string &approved)

ApprovalMissingException

ApprovalMissingException is thrown if the approved file is missing - typically on first run of a new test.

class ApprovalMissingException : public ApprovalException

Public Functions

ApprovalMissingException(const std::string&, const std::string &approved)

ApprovalNamer

ApprovalNamer is the interface that controls how approved and received files are named.

For more information, see Namers.

class ApprovalNamer

Subclassed by ApprovalTestNamer, ExistingFileNamer, TemplatedCustomNamer

Public Functions

virtual ~ApprovalNamer() = default

virtual std::string getApprovedFile(std::string extensionWithDot) const = 0

virtual std::string getReceivedFile(std::string extensionWithDot) const = 0

ApprovalWriter

ApprovalWriter is the interface that controls how objects being verified are written to disk.

For more information, see Writers.

class ApprovalWriter

Subclassed by ExistingFile, StringWriter

Public Functions

virtual ~ApprovalWriter() = default

virtual std::string getFileExtensionWithDot() const = 0

virtual void write(std::string path) const = 0

virtual void cleanUpReceived(std::string receivedPath) const = 0

FileApprover

Low-level methods for approving files.

class FileApprover

Public Types

using TestPassedNotification = std::function<void()>

Public Functions

FileApprover() = default

~FileApprover() = default

Public Static Functions

static ComparatorDisposer registerComparatorForExtension(const std::string &extensionWithDot, std::shared_ptr<ApprovalComparator> comparator)

Register a custom comparater, which will be used to compare approved and received files with the given extension.

See also

For more information, see Custom Comparators in the User Guide on GitHub.

Parameters

• extensionWithDot – A file extention, such as “.jpg”

• comparator – std::shared_ptr to a ApprovalTests::ApprovalComparator instance

Returns

A “Disposable” object. The caller should hold on to this object. When it is destroyed, the customisation will be reversed.

static void verify(const std::string &receivedPath, const std::string &approvedPath, const ApprovalComparator &comparator)

This overload is an implementation detail. To add a new comparator, use registerComparatorForExtension().

static void verify(const std::string &receivedPath, const std::string &approvedPath)

static void verify(const ApprovalNamer &n, const ApprovalWriter &s, const Reporter &r)

static void reportAfterTryingFrontLoadedReporter(const std::string &receivedPath, const std::string &approvedPath, const Reporter &r)

static void setTestPassedNotification(TestPassedNotification notification)

static void notifyTestPassed()

Options

Easy control of various customization points in Approvals::verify() and similar methods

For more information, see Options.

class Options

Public Functions

Options() = default

explicit Options(Scrubber scrubber)

explicit Options(const Reporter &reporter)

FileOptions fileOptions() const

Scrubber getScrubber() const

bool isUsingDefaultScrubber() const

std::string scrub(const std::string &input) const

const Reporter &getReporter() const

Options withReporter(const Reporter &reporter) const

Options withScrubber(Scrubber scrubber) const

std::shared_ptr<ApprovalNamer> getNamer() const

Options withNamer(std::shared_ptr<ApprovalNamer> namer)

class FileOptions

Public Functions

const std::string &getFileExtension() const

Options withFileExtension(const std::string &fileExtensionWithDot) const

Reporter and subclasses

Reporters are called on test failure, typically to show differences.

Most reporters launch an external diffing tool, allowing programmers to understand the difference(s) between approved and received files. They also typically allow the output to be “approved”.

For a demonstration of this, see the Tutorial.

For more information, see Reporters.

class Reporter

Subclassed by AutoApproveIfMissingReporter, AutoApproveReporter, BlockingReporter, CIBuildOnlyReporter, ClipboardReporter, CombinationReporter, CommandReporter, DefaultReporter, EnvironmentVariableReporter, FirstWorkingReporter, QuietReporter, TextDiffReporter

Public Functions

virtual ~Reporter() = default

virtual bool report(std::string received, std::string approved) const = 0

Linux Reporters

namespace Linux

class SublimeMergeSnapReporter : public GenericDiffReporter

#include <LinuxReporters.h>

class SublimeMergeFlatpakReporter : public GenericDiffReporter

#include <LinuxReporters.h>

class SublimeMergeRepositoryPackageReporter : public GenericDiffReporter

#include <LinuxReporters.h>

class SublimeMergeDirectDownloadReporter : public GenericDiffReporter

#include <LinuxReporters.h>

class SublimeMergeReporter : public FirstWorkingReporter

#include <LinuxReporters.h>

class KDiff3Reporter : public GenericDiffReporter

#include <LinuxReporters.h>

class MeldReporter : public GenericDiffReporter

#include <LinuxReporters.h>

class BeyondCompareReporter : public GenericDiffReporter

#include <LinuxReporters.h>

class LinuxDiffReporter : public FirstWorkingReporter

#include <LinuxReporters.h>

macOS Reporters

namespace Mac

class DiffMergeReporter : public GenericDiffReporter

#include <MacReporters.h>

class AraxisMergeReporter : public GenericDiffReporter

#include <MacReporters.h>

class VisualStudioCodeReporter : public GenericDiffReporter

#include <MacReporters.h>

class BeyondCompareReporter : public GenericDiffReporter

#include <MacReporters.h>

class KaleidoscopeReporter : public GenericDiffReporter

#include <MacReporters.h>

class SublimeMergeReporter : public GenericDiffReporter

#include <MacReporters.h>

class KDiff3Reporter : public GenericDiffReporter

#include <MacReporters.h>

class P4MergeReporter : public GenericDiffReporter

#include <MacReporters.h>

class TkDiffReporter : public GenericDiffReporter

#include <MacReporters.h>

class CLionDiffReporter : public GenericDiffReporter

#include <MacReporters.h>

class MacDiffReporter : public FirstWorkingReporter

#include <MacReporters.h>

Windows Reporters

namespace Windows

class VisualStudioCodeReporter : public GenericDiffReporter

#include <WindowsReporters.h>

class BeyondCompare3Reporter : public GenericDiffReporter

#include <WindowsReporters.h>

class BeyondCompare4Reporter : public GenericDiffReporter

#include <WindowsReporters.h>

class BeyondCompareReporter : public FirstWorkingReporter

#include <WindowsReporters.h>

class TortoiseImageDiffReporter : public GenericDiffReporter

#include <WindowsReporters.h>

class TortoiseTextDiffReporter : public GenericDiffReporter

#include <WindowsReporters.h>

class TortoiseDiffReporter : public FirstWorkingReporter

#include <WindowsReporters.h>

class TortoiseGitTextDiffReporter : public GenericDiffReporter

#include <WindowsReporters.h>

class TortoiseGitImageDiffReporter : public GenericDiffReporter

#include <WindowsReporters.h>

class TortoiseGitDiffReporter : public FirstWorkingReporter

#include <WindowsReporters.h>

class WinMergeReporter : public GenericDiffReporter

#include <WindowsReporters.h>

class AraxisMergeReporter : public GenericDiffReporter

#include <WindowsReporters.h>

class CodeCompareReporter : public GenericDiffReporter

#include <WindowsReporters.h>

class SublimeMergeReporter : public GenericDiffReporter

#include <WindowsReporters.h>

class KDiff3Reporter : public GenericDiffReporter

#include <WindowsReporters.h>

class WindowsDiffReporter : public FirstWorkingReporter

#include <WindowsReporters.h>