Swift Render Tests in Practice — Part III

// Same as before:
func assert(
    image imageProducer: @autoclosure () -> UIImage,
    matches reference: UIImage,
    requiredAccuracy: Double,
    comparisonName: String,
    file: StaticString = #file,
    line: UInt = #line) {
    let image = imageProducer()
    do {
        try image.ensureMatches(reference: reference, requiredAccuracy: requiredAccuracy)
    } catch let ImageComparisonError.imageMismatch(
        pixelCount: totalPixels,
        acceptableMismatchCount: acceptable,
        actualMismatchCount: actual
    ) {
        XCTContext.runActivity(named: comparisonName) { activity in
            let imageAttachment = XCTAttachment(image: image)
            imageAttachment.name = "Actual render"
            activity.add(imageAttachment)

            let referenceAttachment = XCTAttachment(image: reference)
            referenceAttachment.name = "Reference image"
            activity.add(referenceAttachment)

            // New: Generate the difference image and attach it.
            let fullFrame = CGRect(origin: .zero, size: reference.size)
            let renderer = UIGraphicsImageRenderer(size: fullFrame.size)
            let difference = renderer.image { context in
                // Produce black pixels wherever things are the same.
                reference.draw(in: fullFrame)
                image.draw(in: fullFrame, blendMode: .difference, alpha: 1)

                // Highlight everything not black — aka the differences — in red.
                // This step is optional, but I’ve found it to be helpful in some cases,
                // e.g. where the differences are subtle and tinted themselves.
                UIColor.red.withAlphaComponent(0.5).setFill()
                context.fill(fullFrame, blendMode: .colorDodge)
            }

            let differenceAttachment = XCTAttachment(image: difference)
            differenceAttachment.name = "Diff image"
            activity.add(differenceAttachment)
            // That’s it.

            XCTFail(
                "Image with \(totalPixels) pixels differed from reference by \(actual) pixels (allowed: \(acceptable)",
                file: file,
                line: line
            )
        }
    }
}

#import <XCTest/XCTest.h>

NS_ASSUME_NONNULL_BEGIN
@interface PSPDFTestImageCoordinator : NSObject <XCTestObservation>

/// The singleton instance of this class for use in other parts of the code.
@property (nonatomic, class, readonly) PSPDFTestImageCoordinator *sharedCoordinator NS_SWIFT_NAME(shared);

/// Whether we should be storing new reference images.
@property (nonatomic, readonly) BOOL shouldStoreNewImages;

/// Stores an image under the given name in a subdirectory of the generated assets directory.
- (void)saveReferenceImage:(UIImage *)image withName:(NSString *)assetName inSubdirectory:(NSString *)subdirectory;

/// Retrieves a previously stored reference image for a given name from a subdirectory of the test asset directory.
- (nullable UIImage *)referenceImageForName:(NSString *)imageName inSubdirectory:(NSString *)subdirectory error:(NSError **)error;

@end
NS_ASSUME_NONNULL_END

func assert(
    image imageProducer: @autoclosure () -> UIImage,
    matchesAssetNamed assetName: String,
    fromDirectory directory: String,
    requiredAccuracy: Double,
    comparisonName: String,
    file: StaticString = #file,
    line: UInt = #line) throws {
    let coordinator = PSPDFTestImageCoordinator.shared
    if coordinator.shouldStoreNewImages {
        return coordinator.saveReferenceImage(
             imageProducer(),
             withName: assetName,
             inSubdirectory: directory
        )
    }

    let reference = try coordinator.referenceImage(forName: assetName, inSubdirectory: directory
    assert(
        image: imageProducer,
        matches: reference,
        requiredAccuracy: requiredAccuracy,
        comparisonName: comparisonName,
        file: file,
        line: line
    )
}

@implementation PSPDFTestImageCoordinator

static PSPDFTestImageCoordinator *sharedInstance;
static NSURL *generatedAssetsDirectory;
static NSBundle *testsBundle;
+ (void)load {
    static dispatch_once_t onceToken;
    dispatch_once(&onceToken, ^{
        sharedInstance = [self new];
        NSURL *temporaryDirectory = [NSURL fileURLWithPath:NSTemporaryDirectory() isDirectory:YES];
        NSString *uniqueString = NSProcessInfo.processInfo.globallyUniqueString;
        generatedAssetsDirectory = [temporaryDirectory URLByAppendingPathComponent:uniqueString isDirectory:YES];
        [XCTestObservationCenter.sharedTestObservationCenter addTestObserver:sharedInstance];
        testsBundle = [NSBundle bundleForClass:self];
    });
}

+ (PSPDFTestImageCoordinator *)sharedCoordinator {
    return sharedInstance;
}

- (BOOL)shouldStoreNewImages {
#if defined(PSPDF_IMAGE_GENERATION_MODE) && PSPDF_IMAGE_GENERATION_MODE > 0
    return YES;
#else
    return NO;
#endif
}

// More to come …

- (void)testSuiteWillStart:(XCTestSuite *)testSuite {
    static BOOL didAddAssetGrabber = NO;
    if (didAddAssetGrabber || self.shouldStoreNewImages == NO) {
        return;
    }

    // Create a directory that generated images can be written into.
    NSError *error;
    didAddAssetGrabber = [NSFileManager.defaultManager createDirectoryAtURL:generatedAssetsDirectory withIntermediateDirectories:YES attributes:nil error:&error];
    if (didAddAssetGrabber == NO) {
        NSLog(@"Failed to create asset directory: %@", error);

        return;
    }

    // Dynamically add a test case that runs after all other tests have executed to
    // zip the generated images directory.
    // Careful: The invocation will be called with the test instance as the target!
    // We therefore have to use a method that already exists in `XCTestCase`.
    // `addTeardownBlock:` allows running arbitrary code _after_ the test body
    // finished, so we use that, and we set a block as the argument to be passed. This
    // is a tad less hacky than creating a subclass at runtime.
    SEL addTeardownBlock = @selector(addTeardownBlock:);
    NSInvocation *invocation = [NSInvocation invocationWithMethodSignature:[XCTestCase instanceMethodSignatureForSelector:addTeardownBlock]];
    invocation.selector = addTeardownBlock;
    __block XCTestCase *pseudoTest = [XCTestCase testCaseWithInvocation:invocation];
    dispatch_block_t storeAssets = ^{
        [PSPDFTestImageCoordinator.sharedCoordinator attachGeneratedAssetsToTest:pseudoTest];
        // Break the strong reference cycle between the test and its teardown block.
        pseudoTest = nil;
    };
    // Because an invocation needs to be able to store any type of parameter — object types
    // as well as primitives — you cannot pass the value directly, but you can pass a pointer
    // to that value. Because the invocation was instantiated with a method signature, which
    // includes the type encoding, it knows how to properly dereference the pointer and how
    // to treat the value behind it.
    // In Objective-C, the first two arguments of any method call are `self` and `_cmd` (the
    // method name). So the block is the third argument to `-addTeardownBlock:`.
    [invocation setArgument:(void *)&storeAssets atIndex:2];
    // Because invocations can be extremely short lived, they don't strongly reference
    // (or "retain") object-type arguments by default. Instead, the caller has to explicitly
    // opt in to this behavior if the invocation is supposed to be long lived.
    // Blocks are objects, so we need to retain the block we want to execute to still be
    // valid at the time the test has finished running.
    [invocation retainArguments];

    // Now that we’ve set up the test invocation, we can instantiate and add the test case
    // for it.
    [testSuite addTest:pseudoTest];
}

// More to come.

- (void)attachGeneratedAssetsToTest:(XCTestCase *)pseudoTest {
    NSLog(@"Bundling up generated assets in %@ …", generatedAssetsDirectory);
    NSFileManager *defaultManager = NSFileManager.defaultManager;
    NSURL *zipURL = [generatedAssetsDirectory URLByAppendingPathExtension:@"zip"];

    // Make sure there's nothing where we want to create our archive:
    [defaultManager removeItemAtURL:zipURL error:NULL];

    // Use `NSFileCoordinator` to compress the test assets.
    // Courtesy of https://stackoverflow.com/a/32723162/3318984
    NSError *compressingError;
    NSfileCoordinator *fileCoordinator = [[NSFileCoordinator alloc] init];
    __block BOOL didCopy = NO;
    __block BOOL didFailToRun = YES;
    [fileCoordinator coordinateReadingItemAtURL:generatedAssetsDirectory options:NSFileCoordinatorReadingForUploading error:&compressingError byAccessor:^(NSURL *assetURL) {
        didFailToRun = NO;
        NSError *copyError;
        didCopy = [defaultManager copyItemAtURL:assetURL toURL:zipURL error:&copyError];
        if (!didCopy) {
            NSLog(@"Failed to copy the assets for compressing. Error: %@", copyError.localizedDescription ?: @"N/A");
        }
    }];
    if (didFailToRun) {
        NSLog(@"Failed to zip contents of %@: %@", generatedAssetsDirectory, compressingError);
    }
    if (didCopy == NO) {
        return;
    }

    XCTAttachment *generatedAsset = [XCTAttachment attachmentWithContentsOfFileAtURL:zipURL];
    generatedAsset.name = @"Generated Images";
    // The pseudo test consists of only adding this block as a teardown block —
    // so it’s going to succeed! Because, by default, attachments are only
    // preserved for failed tests, we need to adjust the lifetime.
    generatedAsset.lifetime = XCTAttachmentLifetimeKeepAlways;
    NSLog(@"Attaching %@ to test %@", generatedAsset, pseudoTest);
    [pseudoTest addAttachment:generatedAsset];

    // As a final step, we can now remove the directory, which is no longer needed.
    [fileCoordinator coordinateWritingItemAtURL:generatedAssetsDirectory options:NSFileCoordinatorWritingForDeleting error:NULL byAccessor:^(NSURL *directoryURL) {
        [defaultManager removeItemAtURL:directoryURL error:NULL];
    }];
}

/// More to come.

- (void)saveReferenceImage:(UIImage *)image withName:(NSString *)assetName inSubdirectory:(NSString *)subdirectory {
    // Don't do anything if we're not supposed to save images.
    if (self.shouldStoreNewImages == NO) {
        return;
    }

    // JPEG has compression artifacts, so we only allow PNGs here.
    NSAssert([assetName.pathExtension.lowercaseString isEqualToString:@"png", @"Only PNGs are supported.");
    NSData *pngData = UIImagePNGRepresentation(image);
    NSAssert(pngData != nil, @"Failed to obtain PNG data for %@", image);

    // Ensure we have a directory to write into.
    NSURL *destinationDirectory = [generatedAssetsDirectory URLByAppendingPathComponent:subdirectory isDirectory:YES];
    NSError *error;
    BOOL didCreateDestinationDirectory = [NSFileManager.defaultManager createDirectoryAtURL:destinationDirectory withIntermediateDirectories:YES attributes:nil error:error];
    // If the destination directory already exists, `NSFileManager` will not complain: It achieved
    // the desired outcome, so all failure cases mean something in our setup is horribly broken.
    NSAssert(didCreateDestinationDirectory, @"Could not create directory: %@", error);

    NSURL *destinationFile = [destinationDirectory URLByAppendingPathComponent:assetName isDirectory:NO];
    BOOL didWritePNG = [pngData writeToURL:destinationFile options:0 error:&error];
    NSAssert(didWritePNG, @"Could not store image data: %@", error);
}

- (nullable UIImage *)referenceImageForName:(NSString *)imageName inSubDirectory:(NSString *)subdirectory error:(NSError *__autoreleasing*)error {
    NSString *imagePath = [testsBundle pathForResource:imageName.stringByDeletingPathExtension withExtension:image.pathExtension subdirectory:subdirectory];
    if (imagePath == nil) {
        // Providing an appropriate error is left to the reader as an exercise.
        return nil;
    }

    UIImage *image = [UIImage imageWithContentsOfFile:imagePath];
    if (image == nil) {
        // Providing an appropriate error is left to the reader as an exercise.
        return nil;
    }

    return image;
}

@end

ditto -x -k zip-file-1 zip-file-2 … destination_directory