Test iOS JPEG export byte budgets on a cloud Mac

An avatar looks fine in the local preview, but the server rejects the upload. The problem is often not the file extension: the encoded JPEG exceeds the API’s byte limit. Setting a fixed quality value may help with some images, but it provides no guarantee. On a cloud Mac, you can first build a standalone acceptance script for the export logic, then bring the same contracts into your iOS test target.

Define the byte budget, not a quality percentage

If the API imposes a byte limit, store that limit as an integer on the client too, so decimal and binary units do not get mixed up. Quality is an input to the encoder, not a percentage of the output file size. Even at identical pixel dimensions, a solid background and a finely textured image can compress very differently.

For this article, the input has already been normalized for orientation, transparency has been handled, and a color space has been selected. The export stage does not change pixel dimensions. It tries a finite set of quality levels from highest to lowest and returns the first result that meets the budget. This is only the highest-priority passing candidate in that set, not a claim to have found the optimal quality across a continuous range.

File size is an output condition that must be checked; visual quality is a separate acceptance criterion. Meeting the byte limit does not mean text edges, skin tones, or gradients are acceptable.

Use a bounded search instead of endlessly lowering quality

In a remote macOS terminal, save the following as jpeg-budget.swift. A working Swift toolchain must already be configured. The script uses only system frameworks, does not read private photos, and does not change machine settings.

import Foundation
import CoreGraphics
import ImageIO
import UniformTypeIdentifiers

enum ExportError: Error {
    case invalidBudget
    case encoding
    case budgetUnreachable
    case decoding
}

func encodeJPEG(_ image: CGImage, quality: Double) throws -> Data {
    let buffer = NSMutableData()
    guard let destination = CGImageDestinationCreateWithData(
        buffer as CFMutableData,
        UTType.jpeg.identifier as CFString,
        1,
        nil
    ) else {
        throw ExportError.encoding
    }
    let properties = [
        kCGImageDestinationLossyCompressionQuality: quality
    ] as CFDictionary
    CGImageDestinationAddImage(destination, image, properties)
    guard CGImageDestinationFinalize(destination) else {
        throw ExportError.encoding
    }
    return buffer as Data
}

func exportJPEG(
    _ image: CGImage,
    maxBytes: Int
) throws -> (data: Data, quality: Double) {
    guard maxBytes > 0 else {
        throw ExportError.invalidBudget
    }
    let levels = [0.9, 0.8, 0.7, 0.6, 0.5]
    for quality in levels {
        let data = try encodeJPEG(image, quality: quality)
        if data.count <= maxBytes {
            return (data, quality)
        }
    }
    throw ExportError.budgetUnreachable
}

func verify(_ data: Data, width: Int, height: Int) throws {
    guard let source = CGImageSourceCreateWithData(
        data as CFData, nil
    ),
    CGImageSourceGetType(source) == UTType.jpeg.identifier as CFString,
    let decoded = CGImageSourceCreateImageAtIndex(source, 0, nil),
    decoded.width == width,
    decoded.height == height else {
        throw ExportError.decoding
    }
}

let space = CGColorSpace(name: CGColorSpace.sRGB)!
let context = CGContext(
    data: nil,
    width: 320,
    height: 240,
    bitsPerComponent: 8,
    bytesPerRow: 0,
    space: space,
    bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
)!
context.setFillColor(
    CGColor(red: 0.2, green: 0.4, blue: 0.6, alpha: 1)
)
context.fill(CGRect(x: 0, y: 0, width: 320, height: 240))
let image = context.makeImage()!

let result = try exportJPEG(image, maxBytes: 1_000_000)
precondition(result.data.count <= 1_000_000)
try verify(result.data, width: 320, height: 240)

do {
    _ = try exportJPEG(image, maxBytes: 1)
    preconditionFailure("Expected budget rejection")
} catch ExportError.budgetUnreachable {
}

Run xcrun swift jpeg-budget.swift. Success produces no output; failure exits with a nonzero status. The solid-color image checks the workflow, not real-world compression performance. Force unwrapping is used here only for a fixed test fixture. Application code that accepts external images should return explicit errors.

Test failure paths, not just successful files

The script distinguishes an invalid budget, an encoding failure, and an unreachable budget. These must not all be reduced to an empty file: an invalid budget is a caller error, an encoding failure requires investigation of the input or encoder, and an unreachable budget needs to be handled by product policy.

Additional tests should cover at least zero and negative budgets, a budget exactly equal to the output byte count, and a case where every quality level fails. Equality must pass. Do not assume that a budget one byte smaller than the highest-quality output must fail, because a later quality level may still meet it.

Test the search branches separately

Extract the actual encoding operation into an injectable function, then return data of predetermined lengths to test the search logic. If the first level passes, the function should be called only once. If an intermediate level passes, encoding should stop there. If every result exceeds the budget, the number of attempts should equal the number of candidates. This verifies that early exit works without relying on a particular image to produce an exact file size.

Avoiding an unverified binary search also avoids making strict monotonicity of file size a hidden assumption. A finite traversal has a clear cost, but it still encodes large images repeatedly. Set an input pixel limit and avoid processing too many images concurrently.

Build image fixtures that expose problems

The test set should include solid colors, text with fine strokes, gradients, and highly detailed textures. Generate them programmatically or use fixed samples that the team is authorized to retain. Record the dimensions and a content summary for each sample. Do not generate random fixtures on every run without preserving the seed.

Besides checking Data.count, decode the output to confirm its format and pixel dimensions. A corrupt file may be small, but it is not a valid result. JPEG is lossy, so do not assert pixel-for-pixel equality after decoding. If the project needs automated visual-error evaluation, fix the calculation color space and tolerance, and retain samples for manual review.

The same image does not need to produce an identical hash across system versions. More robust assertions are that the format is correct, dimensions are unchanged, the byte budget is met, and the number of search attempts is bounded. Record the selected quality level for investigation.

Integrate with iOS export and ongoing acceptance checks

Once the Mac script passes, move the functions into a reusable application module and run the same fixtures in the target iOS runtime environment. Encoding results from system frameworks can vary, so success on macOS is not proof of success on iOS.

If every quality level fails, the interface should clearly explain that the image cannot be exported under the current constraints. If resizing is allowed, define a separate sequence of dimensions and a minimum side length, and make that behavior clear to the user. Do not silently change dimensions inside the quality search. If the image will be wrapped in a request before upload, check the image file limit and the total request body limit separately.

For the final records, retain only the input fixture identifier, system version, candidate quality levels, selected quality, and output byte count. There is no need to log original private images. Give byte-budget constraints, visual requirements, and failure behavior their own explicit handling, so export problems are not hidden behind an ever-decreasing quality value.

Frequently asked questions