Test iOS bitset serialization: bit order, padding and length limits

A team packs its “read items” into a bitset. Members in Asia-Pacific write the data, and colleagues in North America read it next. Local roundtrip tests always pass, but a different client version reveals that the first and eighth flags are swapped. The problem usually is not the network: it is an underspecified binary contract. A cloud Mac can turn these checks into a repeatable task, comparing every change against the same byte samples instead of merely checking whether the interface looks right.

Define the wire format, not the memory layout

This article implements a reference format independent of any application logic: the first four bytes hold an unsigned bit count in big-endian order, followed immediately by the bitset payload. Bit indices start at zero, with the least significant bit first within each byte. Index zero therefore maps to the least significant bit of the first byte, and index eight to the least significant bit of the second.

Calculate the payload size by dividing the bit count by eight and adding one if there is a remainder. A zero-bit value contains only the header. Unused high bits in the final byte must be zero, and extra bytes must be rejected. This format has no version field. When integrating it into an existing protocol, explicitly version it at the enclosing layer rather than replacing old data directly.

A successful roundtrip only proves that both sides agree. If the encoder and decoder both reverse the bit order, the test will still pass. You also need independently calculated byte vectors.

Do not serialize a struct’s memory, machine words, or native integer buffers directly. Doing so carries alignment, endianness, and implementation details into the persisted format.

Write a reference implementation with an input limit

Save the following as BitsetCheck.swift in a separate directory on the cloud Mac, and run it with Swift from the development toolchain. The limit here is one million bits: a defensive policy for this example, not a theoretical limit of the file format. The decoder checks the limit and the complete input length before allocating the result array, avoiding large allocations based on an untrusted header.

import Foundation

enum FormatError: Error {
    case invalid
}

let maxBits = 1_000_000

func encode(_ bits: [Bool]) throws -> [UInt8] {
    guard bits.count <= maxBits else {
        throw FormatError.invalid
    }
    let count = UInt32(bits.count)
    var bytes = [
        UInt8(truncatingIfNeeded: count >> 24),
        UInt8(truncatingIfNeeded: count >> 16),
        UInt8(truncatingIfNeeded: count >> 8),
        UInt8(truncatingIfNeeded: count)
    ]
    let size = bits.count / 8 + (bits.count % 8 == 0 ? 0 : 1)
    bytes += Array(repeating: UInt8(0), count: size)
    for index in bits.indices where bits[index] {
        bytes[4 + index / 8] |= UInt8(1) << (index % 8)
    }
    return bytes
}

func decode(_ bytes: [UInt8]) throws -> [Bool] {
    guard bytes.count >= 4 else {
        throw FormatError.invalid
    }
    let raw = bytes.prefix(4).reduce(UInt32(0)) {
        ($0 << 8) | UInt32($1)
    }
    guard raw <= UInt32(maxBits) else {
        throw FormatError.invalid
    }
    let count = Int(raw)
    let size = count / 8 + (count % 8 == 0 ? 0 : 1)
    guard bytes.count == 4 + size else {
        throw FormatError.invalid
    }
    let remainder = count % 8
    if remainder != 0 {
        let allowed = UInt8((1 << remainder) - 1)
        guard bytes[bytes.count - 1] & ~allowed == 0 else {
            throw FormatError.invalid
        }
    }
    return (0..<count).map {
        bytes[4 + $0 / 8] & (UInt8(1) << ($0 % 8)) != 0
    }
}

func require(_ condition: Bool) {
    if !condition {
        fatalError("Bitset check failed")
    }
}

func mustReject(_ bytes: [UInt8]) {
    do {
        _ = try decode(bytes)
    } catch {
        return
    }
    fatalError("Invalid input accepted")
}

let expected: [UInt8] = [0, 0, 0, 9, 0x81, 0x01]
var sample = Array(repeating: false, count: 9)
for index in [0, 7, 8] {
    sample[index] = true
}
require(try encode(sample) == expected)
require(try decode(expected) == sample)

for count in [0, 1, 7, 8, 9, 63, 64, 65] {
    let bits = (0..<count).map { $0 % 3 == 0 }
    let bytes = try encode(bits)
    require(try decode(bytes) == bits)
}

mustReject([])
mustReject([0, 0, 0, 9, 0x81])
mustReject(expected + [0])
mustReject([0, 0, 0, 1, 0x80])
mustReject([0xFF, 0xFF, 0xFF, 0xFF])

Run xcrun swift BitsetCheck.swift. A successful run exits silently; an assertion failure or unhandled error makes the process exit with a failure status. Once you move the tests into your project, replace the reference functions with the actual encoder and decoder entry points, keeping the vectors and rejection tests. Otherwise, you are still only validating the example.

Test encoding and decoding independently with golden vectors

For nine bits with indices zero, seven, and eight set, the payload must be hexadecimal 81 01. The first byte exercises both the least and most significant bits, the second checks the transition across a byte boundary, and the header makes clear that the logical bit count is not the payload length.

Also add four kinds of samples: all bits clear, all bits set, only the first bit set, and only the last bit set. Eight bits all set must produce FF; nine bits all set must produce FF 01, not FF FF. Unused bits are not scratch space that can be ignored simply because they are never read. A canonical representation is necessary for consistent byte comparisons, hash calculations, and cache keys.

Keep golden vectors in version control. When changing the protocol, review the expected bytes first, then update the implementation. Do not have the encoder under test automatically generate and overwrite the expected files: that amounts to letting the code under test supply its own answers.

Treat invalid input as a separate test surface

Truncation cases should cover both a header shorter than four bytes and a complete header with a payload one byte short. Reject extra bytes as well, or upstream framing errors will be silently accepted. For nonzero padding, pair a one-bit length with 80; this can expose both confused bit order and missing validation of the final byte.

Set the length limit according to the number of items the application allows, and cap the total byte count when receiving data at the application layer. The array passed to the example decoder already exists, so the decoder cannot prevent the network layer from first reading an oversized response into memory. Streaming receivers also need their own cumulative byte budget.

Do not allocate from the header length before checking the actual payload, and do not use “add seven, then divide by eight” on arbitrary externally supplied integers. Here, the length is bounded first, then division and remainder are used to calculate the size. The order of these checks is also part of the test contract.

Record comparable evidence in the regression gate

Put the script in the repository’s test directory and have it exercise the application implementation from the same commit. Record the commit identifier, the output of xcrun swift --version, and the names of failing vectors. Do not log users’ actual read states or entire application payloads.

Give each error category a stable name, such as truncation, invalid padding, or length limit exceeded, rather than collapsing every failure into a network error. The single error used above only keeps the reference code short; a production implementation should preserve categories that support diagnosis.

Finally, run a deliberate fault-injection check: reverse the bit order within each byte and confirm that the golden vectors fail; remove the final-byte check and confirm that the tests catch invalid padding. Only when these faults actually block the task does the cloud regression gate protect the format boundary, rather than merely repeat another successful roundtrip.

Frequently asked questions