In the first two weeks of July 2026, agent sessions on the Hello Weather iOS app produced 67 pull requests. Each one was a finished feature: watch detail views, Live Activities, a widget builder, CarPlay, a menu bar app, alert severity, per-location storage. Each one was behind a debug flag that was off by default, so the shipped app didn’t change. Each one built on all three targets. On July 15 the owner decided that none of them mattered more than the work already in line: accessibility, localization, the iOS 27 pass, and a featuring nomination. So we had sixty-odd finished features that wouldn’t ship for months, and we had to put them somewhere.
The usual answer is a branch per feature, and it’s the wrong one. A branch nobody is merging drifts away from main, conflicts pile up, and eventually someone has to rebase it, which means learning the code again. Sixty of those is a chore that never ends. A tracking issue that lists them goes stale the same way. We needed somewhere to put finished work that costs nothing while it waits and comes back intact when we want it.
Three weeks later we hit the opposite problem. A performance change touching 51 files had been through two rounds of review with seven reviewers, and every round found something new. The code was correct and tested, but it was too big for anyone to review with confidence in one go. This work needed to be broken up, not stored.
Two practices, and they’re the same move in opposite directions:
We call the first kind a banked PR and each of the small pieces a slice.
The alternative was to keep all 67 PRs open and mergeable. We had just done that once, merging main into every conflicting branch to get them all green at the same time. We didn’t want to do it again every time main moved.
This works because of a GitHub behavior most people never use. GitHub keeps every pull request’s last commit at refs/pull/<n>/head, permanently, whether the PR is open, merged, or closed, and whether or not the branch still exists. A closed PR whose branch was deleted also shows a Restore branch button. So a closed, unmerged PR is a safe place to keep code, and the description, review history, and QA notes stay with it. On July 15 we closed all 67 PRs with the same comment, deleted their branches, and added a link to each banked PR in the plans index, next to its plan, with the flag name beside it. The index is the ranking list from Plans Are Disposable, Skills Are Durable, and a banked PR is just one more thing it points at.
The closing comment says everything a future reader needs:
Closed unmerged as a banked reference implementation (2026-07-15
consolidation): this work ranks below the current localization /
featuring / iOS 27 sequence, so it is preserved here instead of being
kept mergeable. Its plans index entry links back to this PR. Restore
anytime via the Restore branch button or:
git fetch origin pull/<n>/head
And the index entry is one line, next to the plan it belongs to:
- **[Watch Feature Parity](plans/watch-parity.md)** - Location and source
switching, precip complications. Banked PR: #<n> (`watchExtrasEnabled`).
The index defines the term at the top, so nobody has to guess: a banked PR is “a complete, flag-gated, build-verified reference implementation preserved in a closed PR”. Those three adjectives are the entry requirements. If the work isn’t complete, it’s a draft. If it isn’t behind a flag, it can’t come back as a merge that changes nothing for users. If it was never built and tested, it’s a sketch.
Banking doesn’t keep the code mergeable. A banked PR is a patch against main as it was the day it closed. To bring one back, you pull its diff out and fix it up against current main by hand, which is the recipe in the next section. We accepted that because it’s paid once, when someone wants the feature, instead of a little every week forever.
Three weeks later the 51-file change arrived. It was a hoisting sweep across the app, watch, and widgets. A hoist moves a computation out of a loop so it runs once instead of on every pass, and this sweep pulled computed properties out of ForEach closures. We started it after measuring a watch view that rebuilt its body on every drag frame, with about 142 array allocations and 23 calendar constructions each time. The PR passed every check the repo had. The owner closed it anyway, because 51 files of “mechanical” change is more than a person can review with confidence. Every round had found new issues, and to the owner that meant the change was too big to reason about, not that it was finally clean.
We could have rewritten the work as small PRs from scratch, but that throws away two rounds of review. Instead the closed PR became the source, and a plan split it into eleven slices. Each slice is a list of files plus the notes an implementer needs: which slices change behavior on purpose, which files have to move together because they share a Swift extension, and which hoists have to stay behind the same condition as the original code.
Copying a slice out takes four lines:
git checkout -b <slice-branch> origin/main
git fetch origin refs/pull/<n>/head
git diff origin/main...FETCH_HEAD -- <slice files> | git apply
# slice-specific adjustments, then the full test gates, then the PR
The three-dot diff compares the closed PR’s final state with the point where it branched off main, so the fixes made during review come along. The plan says this outright: never cherry-pick the first commit alone for a file that the review commits touched. Each slice PR says where it came from, so the reviewer knows the code was already reviewed three times and can concentrate on where the slice boundary falls.
Some slices can’t be a straight copy. Two of the eleven were closed the same day they opened. On top of the hoists, they added range checks on values from our own server, and the owner rejected that as defending against a problem we control. Both were cut again with only the hoists. Those two are new code, not copies, and their PR descriptions say so. A copied slice is trustworthy because it came out of a reviewed PR. A new one has to be reviewed again.
The obvious way to land eleven slices from one source is a stack: slice two on top of slice one, and so on. We landed them one at a time on main instead. Each slice was cut in its own worktree off fresh main (the worktree rules are in Never Touch the Human’s Checkout) and copied out against main as it stood at that moment. We did it that way because it’s safer. If main has changed under a slice’s files, a stacked branch carries the stale base along without telling anyone, and the conflict shows up at the end in whichever slice is unlucky. A fresh copy fails at git apply with a conflict on the exact file. When that happens, the plan says to fix it by hand and say so in the PR description.
The per-location storage PR went the same way in August. It had been reviewed three times and bundled four separate changes: a split in reset semantics, a per-slot store, a batch fetch, and a preview swap. Small PRs review better, so we closed it as the source, and its plan lists four slices in landing order with the reason each file goes where it does. Slice A is one file, plus 26 and minus 22 lines. Its PR description says it was copied exactly from the closed PR minus one line that belongs to slice B, so the three review rounds carry over. It has been open since August 1, waiting for its turn. On August 13 we merged current main into it and ran both gates again. That’s what waiting costs when the code is 48 lines: one merge and one test run in twelve days.
Priority isn’t the only reason to bank work. The design queue’s policy is that merged doesn’t mean design-approved, so a contested piece of UI goes behind a flag from the start. If the verdict is “pull back”, a small PR removes the UI and the implementation stays, flagged or banked. That verdict is cheap to give because nothing is thrown away.
An agent switched branches while the human was testing in Xcode, and their next build failed on code they’d never written. Another agent left a half-finished edit behind, and nobody could tell from git status whose it was. A third ran xcodebuild while Xcode was building, and the human’s build died with “database is locked.” The only way back was Clean Build Folder and a full recompile, which is slow for an app with a watch target and a widget target.
All three happened in the same setup. Hello Weather is a one-person product, and that person builds it in Xcode with the repository open all day. Several coding agents work in the same repository at the same time, fixing bugs, editing plans, and updating skills. The human’s copy is never idle. Xcode has files open in it, an incremental build database sits on disk, and a branch is checked out mid-test.
The failures come in two kinds. The working tree has one checked-out branch and one set of files, so two actors writing to it collide. The build has one DerivedData folder, which holds the build database and the compiled output, and Xcode and command-line xcodebuild can’t share it. Neither problem is about the quality of what the agents write. Both are about an agent running next to a person’s live editor. A sibling post covers keeping parallel agents from colliding with each other when they merge. This one is about keeping every agent out of the human’s editor and build state.
Give every agent its own checkout and its own build folder, and make that the default rather than something to remember. Four rules:
“Be careful in the shared checkout” is not a rule an agent can follow. A git worktree is a second working directory attached to the same repository. It has its own branch and its own files, and it shares the one object store (the commit history). The human’s checkout and the agent’s worktree can be on different branches, with different uncommitted changes, and never touch each other’s files.
The rule has no exceptions on purpose. No edits in the main checkout at all, not even a one-line plan or doc change, because an agent will talk itself past a rule that allows small changes. The rule lives in AGENTS.md, which every session loads. It landed 2026-08-04 and replaced wording that had allowed branches in the main checkout:
The main checkout is the user’s (Xcode has it open). Never work in it — no edits, no branches, no uncommitted state left behind — unless the user explicitly authorizes it in the current session. All work, including one-line plan/doc edits, happens on a branch in a worktree under
.claude/worktrees/<name>(gitignored; never a sibling of the repo in~/Code/helloweather), created before the first change.
The same PR first tried a PreToolUse hook, a check that runs before each tool call, to block edits outside a worktree. Review dropped it, so instructions enforce the rule, not tooling. It holds because it has no exceptions and every session reads it first.
A worktree that only edits text costs nothing to create. A worktree that has to build needs one more step. Git only writes out tracked files, so the two secret files this project keeps out of git, an API-keys xcconfig and a crash-reporter config, are missing from a fresh worktree. Without them xcodebuild fails right away on the missing base configuration. One script creates the worktree, links the secrets, and sets the build-isolation variables:
#!/bin/bash
set -euo pipefail
REPO="$HOME/Code/app/ios" # the human's checkout (Xcode has this open)
NAME="fix-widget-crash" # short name for this unit of work
WORKTREE="$REPO/.claude/worktrees/$NAME"
# Gitignored secrets git will NOT copy into a fresh worktree. Link, don't copy,
# so a rotated key updates everywhere at once. Names are illustrative.
SECRETS=(
"app/Resources/Secrets.xcconfig"
".crashrc"
)
git -C "$REPO" fetch origin main
git -C "$REPO" worktree add -b "feature/$NAME" "$WORKTREE" origin/main
for rel in "${SECRETS[@]}"; do
mkdir -p "$WORKTREE/$(dirname "$rel")"
ln -sf "$REPO/$rel" "$WORKTREE/$rel"
done
# Build isolation: a private DerivedData so this never shares a build database
# with Xcode. Shared package + compile caches so isolation isn't re-cloning.
export HW_DERIVED_DATA="$HOME/Library/Developer/Xcode/DerivedData/app-agent"
export HW_SPM_CACHE="$HOME/Library/Caches/app-SPM"
export HW_CAS_PATH="$HOME/Library/Caches/app-CAS"
echo "Worktree ready: $WORKTREE"
The secrets are symlinked, not copied, so they stay gitignored and a rotated key updates every worktree at once. The next section covers the three exported variables. One more habit for agents working in a worktree: use absolute paths in every file operation. A relative path resolves against whatever directory the shell last landed in, and with sibling repos in the workspace that is rarely the worktree you meant.
The “database is locked” failure has a one-flag fix: -derivedDataPath, set from an environment variable. When the variable is unset, the human’s builds use Xcode’s usual location. When it’s set, the agent builds into a private folder.
Making everything private per worktree would be expensive. Each worktree would download every package again and recompile every file, and a day’s worth of worktrees would spend all day doing that. So we split by what conflicts. The build database is private: the agent’s folder when the variable is set, Xcode’s own per-workspace folder otherwise. The downloaded packages are shared, because they’re just source. The compile cache is shared too, because it’s content-addressed (each compiled file is stored under a hash of its inputs), so a later worktree reuses an earlier one’s compiles instead of redoing them. The cache sharing landed 2026-08-07 through 08. The build script passes all three to xcodebuild. This is the real script trimmed to the flags that matter, with one scheme instead of two:
#!/bin/bash
set -euo pipefail
# Private DerivedData when set (agents/CI); unset keeps Xcode's shared location.
DERIVED_DATA=()
if [ -n "${HW_DERIVED_DATA:-}" ]; then
DERIVED_DATA=(-derivedDataPath "$HW_DERIVED_DATA")
fi
# Shared across worktrees: downloaded packages, and the content-addressed
# compile cache (safe to share; it is not the build database).
SPM_CACHE="${HW_SPM_CACHE:-$HOME/Library/Caches/app-SPM}"
CAS_PATH="${HW_CAS_PATH:-$HOME/Library/Caches/app-CAS}"
xcodebuild build \
-workspace App.xcworkspace \
-scheme AppWidgets \
-destination 'generic/platform=iOS Simulator' \
"${DERIVED_DATA[@]}" \
-clonedSourcePackagesDirPath "$SPM_CACHE" \
-quiet \
COMPILATION_CACHE_ENABLE_CACHING=YES \
COMPILATION_CACHE_CAS_PATH="$CAS_PATH"
One rule the variables can’t enforce: never run two builds at once, even with private DerivedData folders. Two builds still share the downloaded packages and the compile cache, and we don’t want to find out what happens when both write to those together. So each agent has a private place to build, and builds run one at a time.
Every worktree that builds creates roughly 6 GB of DerivedData, and a full private agent cache runs about 8 GB. Ten pieces of work in a day is 60 GB or more of build cache, for changes that may already be merged. Left alone, the disk fills up and every build fails for a reason that has nothing to do with any agent’s code.
A worktree is done once its branch is squash-merged into main. The object store keeps the history, so from then on the working directory and its build cache are waste. The cleanup script prunes git’s records of worktrees that are gone, then deletes DerivedData for any workspace path that no longer exists. Those are the caches removed worktrees left behind, so the script is safe to run at the end of any session. It’s trimmed here; the real one also drops a simulator tool’s caches and unavailable simulators:
#!/bin/bash
set -euo pipefail
REPO="$HOME/Code/app/ios"
echo "Pruning stale worktree records..."
git -C "$REPO" worktree prune
echo "Deleting DerivedData for workspaces that no longer exist..."
for dir in "$HOME/Library/Developer/Xcode/DerivedData/"app-*/; do
[ -d "$dir" ] || continue
workspace="$(/usr/libexec/PlistBuddy -c "Print WorkspacePath" "$dir/info.plist" 2>/dev/null || true)"
if [ -n "$workspace" ] && [ ! -e "$workspace" ]; then
echo " removing $(basename "$dir") ($workspace)"
rm -rf "$dir"
fi
done
df -h / | tail -1 | awk '{print "Free space: " $4}'
The script doesn’t delete by age or by guess. It reads the WorkspacePath each DerivedData folder records and deletes the folder only when that path is gone. An active worktree’s cache stays, and a removed worktree’s cache goes.
Everything above keeps agents out of the human’s checkout. There is one moment the human wants a branch in it. When they say “let me test that branch,” they mean in Xcode, in the checkout they already have open, not in a worktree they’d have to go find. That’s the one allowed exception.
The handoff is one-way. Once the branch is in the human’s checkout, that checkout owns it. Follow-up commits happen there. No agent runs a command-line build against it, because that would wreck the live incremental build state in the middle of QA. The checklist, condensed from the pull-requests skill:
## QA handoff (worktree -> human's checkout)
Confirm the handoff with the human first, then:
1. Push the branch. Remove the worktree (the branch persists);
check the branch out in the human's checkout. Displacing whatever
it was on is expected — the human QAs one thing at a time.
2. Open the PR if it isn't already, so the human reviews code on
GitHub while building the branch locally.
3. One-way: from here the human's checkout owns this branch. Follow-up
commits happen there, not in a recreated worktree.
4. Never tell the human to `git pull` for follow-up commits made in
their own checkout — those commits are already in their working copy.
5. Iterate conversationally: propose each follow-up as a readable diff
in chat and get agreement before committing. Approved changes still
push promptly so the PR tracks the conversation.
6. Never run a CLI build (xcodebuild) in the human's checkout after
the handoff — it stomps their live incremental build state. Their
next Xcode build verifies the follow-up; for anything riskier than
a trivial change, say so, or verify in the worktree before handoff.
Item 4 looks trivial and isn’t. An agent once committed a fix in the human’s checkout and then told them to git pull to see it. The commit was already in their working copy, so there was nothing to pull, and the instruction confused them. After the handoff, the checkout is the working copy and the agent is a guest in it.
One smaller rule applies to any pushed branch, handoff or not: never force-push it. Review fixes are new commits, not a rebase that rewrites what someone may have already pulled.
git pull with nothing to pull was the symptom.The weekday rail under a chart holds seven ticks, and each tick holds three characters. Mon Tue Wed fits. So do 9am 10am under the bars of the hourly chart, Falling fast on a two-line stat card, and a bare hour on a watch complication. We drew every one of these slots in English, they look right in English, and none of them wraps or grows.
Then a model translates the strings into 26 more languages, and nothing in our tools knows how wide any of them will be. A German label one character too wide clips in the app, the widget, and the watch, because it’s the same string in the same slot. Some languages are worse: two weekdays shrink to the same three letters, so the axis shows two identical ticks. That’s a data bug, and nothing looks cut off. Six of our languages fail one of those two checks if we take the system calendar’s abbreviations as they come. Without a test, the first we’d hear of it is a screenshot or a customer, after shipping.
Hello Weather shows sentences where most weather apps show a number and an icon: pressure trends, when the rain starts, air-quality advice, in 27 languages. Most of that text sits in slots like these. One person runs it, with no localization agency, so the fix has to fail a build. Nobody is going to eyeball 27 screenshots. We use two measures. Dates count characters, because a weekday tick has a hard cap. Stat cards measure rendered width, because a card is a layout and what overflows it is the width of the glyphs.
Every date string goes through one rulebook, so we can list the slots that are tight and test each one against a character cap. Stat-card budgets come from the same grid formula the view uses, and tests measure rendered width against them. Neither number was picked by hand. Exceptions in both are written down as data with their exact value, so a string somebody decided to keep is flagged again the moment it changes.
Every date string goes through one enum of intents. Each case names a slot in the UI (hourlyChartWeekday, statsChartHour, complicationHour), not a format. The date rulebook post covers that enum. For this post, the enum matters because a test can loop over the cases drawn in a tight slot and check a hard cap on each of them, in all 27 languages.
The compact weekday rail has the tightest rule. Each label is at most three characters and three Unicode scalars, letters and digits only, and the seven labels in a week must all differ. Most languages pass with the system calendar’s abbreviated or short standalone symbols. For the six that don’t, the resolver returns a seven-symbol array we wrote by hand, with a comment saying why. Here’s the resolver and the test that checks it, self-contained:
import Foundation
import Testing
enum Language: String, CaseIterable {
case en, de, fr, ja, ko, da, nb, pt, ro, th
// one case per supported language
}
enum WeekdayStyle {
case abbreviated // system calendar "E" symbols
case standaloneShort // system calendar "cccccc" symbols
case declared([String]) // hand-chosen when the platform's break a rule
}
func weekdayStyle(for language: Language) -> WeekdayStyle {
switch language {
case .en, .ja, .ko: return .abbreviated
case .fr: return .standaloneShort
// Standard abbreviations blow the 3-char budget or collide, so declare them:
case .de: return .declared(["So", "Mo", "Di", "Mi", "Do", "Fr", "Sa"])
case .da, .nb: return .declared(["Sø", "Ma", "Ti", "On", "To", "Fr", "Lø"])
case .pt: return .declared(["Dom", "Seg", "Ter", "Qua", "Qui", "Sex", "Sáb"])
case .ro: return .declared(["Dum", "Lun", "Mar", "Mie", "Joi", "Vin", "Sâm"])
case .th: return .declared(["อา", "จ", "อ", "พ", "พฤ", "ศ", "ส"])
}
}
func compactWeekdays(for language: Language) -> [String] {
switch weekdayStyle(for: language) {
case .declared(let symbols):
return symbols
case .abbreviated, .standaloneShort:
// Simplified: the real rulebook formats dates with the "E" / "cccccc" patterns.
var cal = Calendar(identifier: .gregorian)
cal.locale = Locale(identifier: language.rawValue)
return cal.shortStandaloneWeekdaySymbols // Sun…Sat for the demo
}
}
@Test func compactWeekdaysStayCompactAndDistinct() {
for language in Language.allCases {
let labels = compactWeekdays(for: language)
for label in labels {
#expect(label.count <= 3 && label.unicodeScalars.count <= 3, "\(language.rawValue): \(label)")
#expect(label.unicodeScalars.allSatisfy { $0.properties.isAlphabetic || ("0"..."9").contains(Character($0)) },
"\(language.rawValue): \(label)")
}
#expect(Set(labels).count == 7, "\(language.rawValue): \(labels)")
}
}
The exception is data, not a code path. The array can be reviewed, the same test proves it fits, and the next person can see why German stopped reading its symbols from the calendar. Overriding the platform’s locale data feels wrong at first. But that data was chosen for reading in a paragraph, not for a three-character tick that has to look different from its six neighbors. When the platform was solving a different problem than yours, override it with your own data and write down the reason.
Hour labels get a cap of five characters, and English is pinned to 12am…11pm and 0:00…23:00. The standard locale data (CLDR) would give 4 PM or 4 p.m.. We write 4pm, because the labels sit under the bars of the hourly chart and can’t be wider than the bars. The rulebook gets that form by setting bare lowercase am/pm symbols when it builds the formatter, not by lowercasing the output afterwards. Chinese, Japanese, and Korean use their own hour counter (9時, 9시) instead of am/pm. That’s how those languages write a short clock hour, and a Latin am on a CJK digit is wrong and wider. The watch complication in 24-hour mode is tighter still: a bare 17, no colon, no am/pm. Each of these is pinned in a test. The English anchors were typed by a person and are never updated by a script, so a careless snapshot re-record can’t quietly approve a regression.
A weekday tick has a fixed character count, so counting characters is the right check. A stat card is a two-line cell in a grid that adapts to the screen, and what overflows it is the rendered width of the text. A Cyrillic string and a Latin string with the same character count are different widths. An 18-point bold subtitle and a 13-point regular description can’t share a budget either. So the stat tests measure each string on the real device font. The budget they measure against comes from the same grid arithmetic the SwiftUI view uses. Change the layout and the budget follows, in one line:
import UIKit
enum StatBudget {
static let deviceWidth: CGFloat = 390 // narrowest currently-sold iPhone
static let gridOuterPadding: CGFloat = 32
static let gridSpacing: CGFloat = 10
static let gridMinimumColumn: CGFloat = 165
static let cardPadding: CGFloat = 32
static let headroom: CGFloat = 0.95 // 5% safety band
static var descriptionBudget: CGFloat {
let available = deviceWidth - gridOuterPadding
let columns = floor((available + gridSpacing) / (gridMinimumColumn + gridSpacing))
let column = (available - (columns - 1) * gridSpacing) / columns
return column - cardPadding
}
static var passBar: CGFloat { descriptionBudget * headroom }
}
enum Verdict { case ok, margin, over }
/// Measures a string on the real iOS system font and grades it against the budget.
func grade(_ string: String, size: CGFloat = 13, weight: UIFont.Weight = .regular) -> Verdict {
let font = UIFont.systemFont(ofSize: size, weight: weight)
let width = ceil(NSAttributedString(string: string, attributes: [.font: font]).size().width)
if width > StatBudget.descriptionBudget { return .over }
if width > StatBudget.passBar { return .margin }
return .ok
}
The 390 is the narrowest iPhone still on sale. The file also keeps the older 375-point width, but only for information. The report shows what would clip on older phones, it never fails a test, and it’s never a reason to shorten copy. There’s no separate budget for English either. An English string wider than the grid is a finding, not a new budget invented so it passes. descriptionBudget here works out to 142 points, and the MARGIN band 5% under it means the string is worth a look on a device.
That helper runs at two levels. The always-on level is small and fast. It fails bin/unit-test if any of a hand-picked set of the tightest known lines goes over: the widest pressure trend per language, the timed precip strings, and a few fixed one-offs. It measures on the device font every run:
import Testing
struct StatWidthTests {
static let languages = ["cs", "da", "de", "el", "en", "es", "fi", "fr", "hi",
"hu", "id", "it", "ja", "ko", "nb", "nl", "pl", "pt",
"ro", "ru", "sv", "th", "tr", "uk", "vi", "zh-Hans", "zh-Hant"]
// "Falling fast" is the widest pressure trend; the full sweep pulls the live
// value per language, this pins the ones that were tightest against the floor.
static let fallingFast: [String: String] = [
"en": "Falling fast", "de": "Fällt schnell", "el": "Ταχεία πτώση",
"ru": "Резко падает", "pl": "Szybko spada", "ja": "急降下",
// …one row per language
]
private func resolved(_ resource: LocalizedStringResource, _ language: String) -> String {
var resource = resource
resource.locale = Locale(identifier: language)
return String(localized: resource)
}
@Test(arguments: languages)
func pressureLineFitsTheFloorGrid(language: String) {
let trend = Self.fallingFast[language] ?? "Falling fast"
for levelKey in ["Low pressure", "Normal pressure", "High pressure"] {
let level = resolved(LocalizedStringResource(String.LocalizationValue(levelKey), bundle: .main), language)
// The joiner is a catalog template too, so each language composes its own line.
let line = resolved(
LocalizedStringResource("%@ and %@.", defaultValue: "\(level) and \(trend.lowercased()).", bundle: .main),
language
)
#expect(grade(line) != .over, "\(language): \"\(line)\"")
}
}
}
The second level is a full sweep, turned on by an environment variable so it never runs in CI. It grades every stat-card slot in all 27 languages, against both the catalog values and the live strings from our server. Many of the widest strings are built on the server and come back already localized. A wrapper script converts the web repo’s locale files to JSON so the report can read them. The output is a markdown report that’s committed and reviewed on every change, like a copy edit. A row that’s over budget on purpose goes in an accepted map, pinned by its exact value, so an accepted string is flagged again the moment it changes. “This canonical term has no shorter natural form” is a fine reason to accept a row. “We stopped looking” is not. With the value pinned, an accepted string that changes has to be accepted again, with a reason.
A third test ties the two levels together. It fails the build when the set of stat cards changes, and names the files to update. Without it, someone could add a card that the always-on test keeps passing while the report quietly stops covering it.
Budgets and tests keep copy inside the slot when it’s written. The view still needs a safety net when it draws, for the string that slipped through or the accessibility text size that makes everything bigger. The policy is to scale the text down and never cut it off mid-word. Descriptions may shrink a little more than the bold, tighter subtitles, and both stay on one line so the grid’s row height never jumps:
import SwiftUI
struct StatCard: View {
let title: String // e.g. "Pressure"
let subtitle: String // 18pt bold, very tight — "1013 hPa"
let description: String // 13pt regular (.footnote) — "High pressure and falling fast."
var body: some View {
VStack(alignment: .leading, spacing: 4) {
Text(title)
.font(.caption2.weight(.semibold))
.lineLimit(1)
Text(subtitle)
.font(.system(size: 18).weight(.bold))
.lineLimit(1)
.minimumScaleFactor(0.8)
Text(description)
.font(.footnote)
.lineLimit(1)
.minimumScaleFactor(0.9)
}
.padding(.vertical, 18)
.padding(.horizontal, 16)
.frame(maxWidth: .infinity, alignment: .leading)
}
}
The OVER rows left in the full report are the ones this net catches. Each was looked at, judged covered by the scale factor, and recorded, so the next reader knows it was a decision. The scale factor is the last resort, not a reason to skip the budget. A card whose default text has to shrink on the narrowest phone is still a finding.
bin/unit-test instead of reaching a screenshot. The env-gated sweep covers server-owned strings too, at the cost of a committed report to re-approve on every copy change.minimumScaleFactor rather than shorter copy, and each one is recorded as a decision.A Turkish speed abbreviation we glued to the number on purpose and a Turkish speed abbreviation that’s wrong look the same in a diff. One person translated Hello Weather into 27 languages with a model and no agency. After that, our compact unit strings disagreed all over the place with CLDR, the Unicode locale data that says how each language writes units. Nobody could say which disagreements were our style and which were mistakes. Whether each upstream data source could serve those 27 languages was a separate fight, covered in Never Trust the Vendor’s Language List.
Our style is dense on purpose. A wind reading is 12km/h, with no space, where most languages’ CLDR form is 12 km/h. Pressure is 1013hPa, without the digit grouping CLDR adds (1,013hPa in English, 1.013 hPa in German). A temperature is 72° with no C or F, because the user already picked the unit in settings and repeating it on every reading is noise. We decided each of these string by string, to fit stat cards and a watch complication with room for a couple of characters.
Apple already ships a correct localizer. MeasurementFormatter and Duration.UnitsFormatStyle render units the way CLDR says each locale does. English gets 12mph, German 12 mi/h, Russian 12 ми/ч. German groups the thousands: 1.013 hPa. Finnish and French put a non-breaking space between the number and the unit. Finnish, Swedish, and Norwegian put the CLDR minus sign, U+2212, before a negative temperature. For most apps that’s what you want. Our compact style walks away from it in dozens of small ways across 27 languages, and once we walked away from the platform’s answer, nothing checked ours. We had taken over the localizer’s job without its tests.
The obvious fix is a test that asserts our string equals the CLDR string. It fails on the first row, because we differ on purpose. So we’d add an exception, then a hundred, and every time our style and CLDR disagree the build breaks and someone has to decide whether the app is wrong or the test is stale. Nobody trusts a test that fights the product on every run. The other obvious fix is no test at all: check English by eye and ship, which is how a wrong decimal separator reaches a Russian user.
We wanted a third thing: our form next to CLDR’s for every unit in every language, with a verdict on each row, that never blocks a build and never argues with a decision we already made.
We wrote a report, not a pass/fail test. CLDRConformanceTests writes one snapshot file per language, 27 files, and we commit them. Each row pairs one of our unit strings with what ICU/CLDR renders for the same unit and locale, and marks it MATCH or DIFFERS by exact string equality. It’s something to read, not something that fails.
The rows sit in seven sections, one per kind of thing the app shows: WIND, VISIBILITY, PRESSURE, PRECIP, TEMP, PERCENT, and DURATIONS. At the top of each file is a header listing the families of differences we chose on purpose; the file calls them dispositions. Here are that header and the first section of the German file, as committed (a short legend comes before the header):
Dispositions (Trevor, 2026-08-07) — deliberate DIFFERS families, all intended:
- glued number+symbol (compactness idiom); only pressure inHg/kPa keep a space.
- percent strips the whitespace CLDR inserts (toProbability).
- bare unit-agnostic degree (no °C/°F suffix).
- compact durations run tighter than CLDR's abbreviations.
- server numbers carry no digit grouping.
- negative temps keep the hyphen-minus (CLDR uses it in 24/27 of our languages;
the U+2212 adoption question is with design).
## WIND
| Label | Ours | CLDR | Verdict |
|----------------------------|------------|-----------------|---------|
| speed mph | 12mph | 12 mi/h | DIFFERS |
| speed km/h | 12km/h | 12 km/h | DIFFERS |
| speed m/s | 5m/s | 5 m/s | DIFFERS |
| gust range mph (endpoints) | 12-18mph | 12 mi/h–18 mi/h | DIFFERS |
Every DIFFERS there is intended, and the report’s job isn’t to turn them green. Its job is to make a row we didn’t mean to change show up in a diff when it flips from MATCH to DIFFERS, so a person asks why.
A gate answers “is this allowed?” A report answers “is this what you meant?” For deliberate style divergence, the second question is the only useful one, and only a human can answer it.
Three decisions make the report worth trusting.
The tempting shortcut is to call the app’s own formatting helpers inside the test and print what they return. Then you’re not comparing what production renders with CLDR. You’re comparing how the test host configured those helpers with CLDR, and the two drift as soon as a helper reads a setting the test host doesn’t have.
So the report rebuilds each string from the same source data production uses. In this app the server composes the unit strings: it glues a bare number to a localized unit symbol and a decimal separator, both read from the web repo’s locale files. The report does the same gluing, renders the CLDR side with Apple’s formatters, and returns one row per unit. Everything below compiles against Foundation alone:
import Foundation
struct ConformanceRow {
let label: String
let ours: String // reconstructed from source data, never read from the app
let cldr: String // what ICU/CLDR produces for the same unit + locale
}
func conformanceRows(language: String) -> [ConformanceRow] {
let locale = Locale(identifier: language)
func measured(_ value: Double, _ unit: Dimension,
_ style: MeasurementFormatter.UnitStyle) -> String {
let formatter = MeasurementFormatter()
formatter.locale = locale
formatter.unitStyle = style
formatter.unitOptions = .providedUnit
return formatter.string(from: Measurement(value: value, unit: unit))
}
func duration(_ seconds: Int, _ allowed: Set<Duration.UnitsFormatStyle.Unit>,
_ width: Duration.UnitsFormatStyle.UnitWidth) -> String {
Duration.seconds(seconds).formatted(.units(allowed: allowed, width: width).locale(locale))
}
// Stand-ins for the per-language source data the real report reads from the
// web locale JSON (unit symbols) and the string catalog (duration templates).
let speedSymbol = "km/h" // e.g. "км/ч" for ru
let milesLong = "10 miles" // plural form pulled from the locale file
let hourAbbrev = "%lldh" // catalog key "%lldh"; e.g. "3ч" for ru
return [
ConformanceRow(label: "speed km/h",
ours: "12" + speedSymbol, // glued, no space: the compact idiom
cldr: measured(12, UnitSpeed.kilometersPerHour, .short)),
ConformanceRow(label: "miles_long plural (10)",
ours: milesLong,
cldr: measured(10, UnitLength.miles, .long)),
ConformanceRow(label: "3h (abbrev)",
ours: hourAbbrev.replacingOccurrences(of: "%lld", with: "3"),
cldr: duration(3 * 3600, [.hours], .abbreviated)),
]
}
The ours cell comes from string gluing and the cldr cell from the real Apple formatters, so the row compares what production shows with the platform, not one helper with another. The row has no verdict yet. The report computes it after the step below, so hidden characters count.
The differences that hurt most are the ones you can’t see. A non-breaking space (U+00A0, or the narrow one, U+202F) looks like a regular space in any diff viewer. The CLDR minus sign (U+2212) looks like a hyphen. If the report printed those characters raw, a reviewer would see 45 % next to 45 %, read it as a match, and miss the hidden non-breaking space.
So every cell goes through a function that swaps those characters for visible marks, before the comparison and before printing. It needs nothing but the standard library:
func visualize(_ string: String) -> String {
string.unicodeScalars.map { scalar -> String in
switch scalar.value {
case 0x00A0, 0x202F: return "⍽" // NBSP and narrow NBSP
case 0x2212: return "\\u{2212}" // CLDR minus sign
default: return String(scalar)
}
}.joined()
}
Now the Russian percent row reads 45% next to 45⍽%, and the DIFFERS verdict is plainly about that ⍽. The Russian visibility row reads 5000м next to 5⍽000 м, which shows the grouping separator and the space at once. The verdict is computed after this swap, so it’s about the characters the reviewer can see.
A report full of DIFFERS is useless if a reviewer can’t tell an intended difference from a regression. The dispositions header at the top of every file, shown in the German excerpt above, is there for that: each family of deliberate difference, named, with its reason, signed and dated by the owner.
That list is the rule for review. A DIFFERS row under a listed family is expected and needs no thought. A row that flips and isn’t covered by the list is the signal. The list lives in the generated file, so it lands in every diff instead of in a wiki nobody opens. The last bullet is an open question, adopt U+2212 or keep the hyphen-minus, and it sits in the file where it stays visible.
The report is a snapshot test behind an environment variable, so it runs only when asked and never under CI. The snapshot helper compares the output with the committed file. If the file is missing, it writes one locally but refuses to under CI. With UPDATE_SNAPSHOTS=1 it rewrites the file. The person reading the diff is the check, not the assertion (the snapshot path is simplified here):
import Foundation
import Testing
enum Language: String, CaseIterable {
case en, de, ru, ja // one case per supported language
}
func assertMatchesSnapshot(_ value: String, named name: String,
filePath: String = #filePath,
sourceLocation: SourceLocation = #_sourceLocation) {
let environment = ProcessInfo.processInfo.environment
let updating = environment["UPDATE_SNAPSHOTS"] == "1"
let locked = environment["CI"] != nil
let url = URL(fileURLWithPath: filePath)
.deletingLastPathComponent()
.appendingPathComponent("snapshots/cldr_conformance_table__\(name).snap.txt")
if !updating, let recorded = try? String(contentsOf: url, encoding: .utf8) {
if recorded == value { return }
Issue.record("output drifted from \(name) — regenerate with --update-snapshots, then review every changed line",
sourceLocation: sourceLocation)
return
}
guard !locked else {
Issue.record("snapshot \(name) is missing, but snapshots are locked under CI — record locally and commit the file",
sourceLocation: sourceLocation)
return
}
try? FileManager.default.createDirectory(
at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
try? value.write(to: url, atomically: true, encoding: .utf8)
}
@MainActor
struct CLDRConformanceTests {
nonisolated static let reportsEnabled =
ProcessInfo.processInfo.environment["CLDR_REPORTS"] != nil
&& ProcessInfo.processInfo.environment["CI"] == nil
@Test(.enabled(if: CLDRConformanceTests.reportsEnabled))
func cldrConformanceTable() throws {
for language in Language.allCases {
let body = conformanceRows(language: language.rawValue).map { row -> String in
let ours = visualize(row.ours)
let cldr = visualize(row.cldr)
return "| \(row.label) | \(ours) | \(cldr) | \(ours == cldr ? "MATCH" : "DIFFERS") |"
}.joined(separator: "\n")
assertMatchesSnapshot(body, named: language.rawValue)
}
}
}
Notice the two guards on reportsEnabled: the report doesn’t run unless CLDR_REPORTS is set, and it stays off under CI so it can’t block a build. The verdict is computed on the swapped cells, so the invisible characters decide it. You regenerate the files with bin/cldr-report. That wrapper converts the web repo’s locale YAML to JSON in a temp directory, passes it along so the server-composed rows fill in, and hands off to the test runner. Without a web checkout those rows read (web checkout absent) instead of failing. To accept an intended change, you run bin/cldr-report --update-snapshots and review the regenerated diff for each language the way you’d review a copy change. It’s the same habit as our on-device width report in Measure the String Before You Translate It: the report isn’t the gate; the person reading the diff is.
DIFFERS is either fixed or listed in the header.km/h the day after the localization launch. The report agreed (km/sa) and showed the other four. A pass/fail test would have buried them under exceptions. Next to CLDR they read as errors, and we adopted CLDR’s abbreviations for all five.bin/cldr-report before any unit-string change counts as done.When a Japanese hour loses its counter symbol (the character that marks the number as an hour), nothing crashes. The app builds, the English screens look right, and the bug ships to a screen in a language nobody on the team reads. Localized date formatting fails like that: one language at a time, quietly. Hello Weather shows dates in 24 places, in 27 languages, on both 12- and 24-hour clocks. One person maintains it and a model does the translating.
The obvious test checks the English output and stops. It keeps passing while every other language drifts, because English is the one language that matches the source strings.
Going the other way fails too. If we snapshot every language, every intent, and both clocks together, we get one enormous file. A real change to one language gets buried when the whole file is regenerated. Nobody reads a seventy-thousand-line diff. They approve it and move on, and then the test isn’t protecting anything.
In our app, every date string a user sees goes through one enum of intents (what the date is for: a daily header, a sunrise time) and one exhaustive switch that maps each intent to a format. We call that the date rulebook, and its design is its own post. We can only trust the rulebook if a change to it produces a diff a person can read. This post is about the snapshot tests that make that true, and about a second, faster test run that checks the same files in six seconds but isn’t allowed to change them. It continues from porting the snapshot ergonomics: the same small file-snapshot helper, now pointed at the full language matrix and then made fast.
Two rules, one for each trap.
allCases. Every test that sweeps the languages writes one file per language, named by the language code, holding that language’s whole grid. A German change touches ..._blessed_snapshot__de.snap.txt and nothing else, so it gets a German-sized diff.allCasesWe split the files by language because that’s how rendering changes arrive: one language at a time. The matrix test loops over every language and every intent and checks one snapshot per language:
import Testing
import Foundation
enum Language: String, CaseIterable { case en, de, fr, ja /* one case per supported language */ }
enum TimeFormat { case ampm, twentyFourHour }
final class Settings { static let shared = Settings(); var language = Language.en; var timeFormat = TimeFormat.ampm }
enum DateFormatIntent: String, CaseIterable { case dailyHeader, sunEventTime, moonDate, complicationHour }
// Two fixed instants, built from components in the display time zone:
// Wed 2026-01-07 09:05 (AM, single-digit day and hour) and Sat 2026-08-15 17:39 (PM, double digits).
enum Samples {
static func date(year: Int, month: Int, day: Int, hour: Int, minute: Int) -> Date {
var calendar = Calendar(identifier: .gregorian)
calendar.timeZone = .current // real code uses the forecast's time zone
return calendar.date(from: DateComponents(year: year, month: month, day: day, hour: hour, minute: minute))!
}
static var morning: Date { date(year: 2026, month: 1, day: 7, hour: 9, minute: 5) }
static var evening: Date { date(year: 2026, month: 8, day: 15, hour: 17, minute: 39) }
}
// Set the app's language and clock, run the body, and restore both — always, via defer.
func withAppLanguage(_ language: Language, timeFormat: TimeFormat = .ampm, body: () -> Void) {
let originalLanguage = Settings.shared.language, originalTimeFormat = Settings.shared.timeFormat
defer { Settings.shared.language = originalLanguage; Settings.shared.timeFormat = originalTimeFormat }
Settings.shared.language = language
Settings.shared.timeFormat = timeFormat
body()
}
extension Date {
// Real code routes through the date rulebook: intent + current settings select the template.
func withFormat(_ intent: DateFormatIntent) -> String { /* ... */ }
}
// Escape quotes, backslashes, control characters, and non-ASCII whitespace or
// format scalars so invisible characters survive a diff while letters stay legible.
func escaped(_ value: String) -> String {
value.unicodeScalars.map { scalar in
switch scalar {
case "\"": return "\\\""
case "\\": return "\\\\"
default:
if scalar.isASCII {
return scalar.value < 0x20 ? String(format: "\\u{%04X}", scalar.value) : String(scalar)
}
if scalar.properties.isWhitespace || scalar.properties.generalCategory == .format {
return String(format: "\\u{%04X}", scalar.value) // narrow spaces, directional marks
}
return String(scalar)
}
}.joined()
}
@MainActor
@Suite("Date format snapshots", .serialized)
struct DateFormatSnapshotTests {
@Test func everyLanguageMatchesItsBlessedSnapshot() {
for language in Language.allCases {
var lines = ["intent | morning 12h | evening 12h | morning 24h | evening 24h"]
for intent in DateFormatIntent.allCases {
var cells: [String] = []
withAppLanguage(language) {
cells.append(Samples.morning.withFormat(intent))
cells.append(Samples.evening.withFormat(intent))
}
withAppLanguage(language, timeFormat: .twentyFourHour) {
cells.append(Samples.morning.withFormat(intent))
cells.append(Samples.evening.withFormat(intent))
}
#expect(!cells.contains(""), "\(language.rawValue) \(intent.rawValue) rendered empty — refusing to bless")
lines.append("\(intent.rawValue) | \(cells.map(escaped).joined(separator: " | "))")
}
assertMatchesSnapshot(lines.joined(separator: "\n") + "\n", named: language.rawValue)
}
}
}
The two allCases loops drive the whole matrix. Add a DateFormatIntent case and every language file grows a row the next time we record. Add a Language and a new file appears. There’s no separate list of things to test that can fall behind the feature. Rows are the intents and columns are the two sample instants crossed with the two clocks, so the German file reads like a table:
intent | morning 12h | evening 12h | morning 24h | evening 24h
dailyHeader | Mi., Jan. 7 | Sa., Aug. 15 | Mi., Jan. 7 | Sa., Aug. 15
sunEventTime | 9:05am | 5:39pm | 9:05 | 17:39
forecastUpdatedDateTime | Mi., Jan. 7 @ 9:05am | Sa., Aug. 15 @ 5:39pm | Mi., Jan. 7 @ 9:05 | Sa., Aug. 15 @ 17:39
complicationHour | 9am | 5pm | 9 | 17
Two details make the file safe to trust. The #expect(!cells.contains("")) check fails the run when a rendering path returns an empty string. A snapshot must never accept blank output, because it looks like success and usually means a missing symbol or a nil that fell through. The escaped helper handles the other quiet failure. Localized date strings carry characters you can’t see, like the narrow no-break space ICU puts between a number and its symbol. In a raw diff, a normal space turning into a narrow no-break space is invisible. Escaped, it shows up as \u{202F}, and the letters around it stay readable.
The test is only as trustworthy as the helper under it. The helper has to get two things right. Regenerating a golden must never feel like a rubber stamp, and CI must never record a golden it should only compare against. It’s small enough to read whole:
import Foundation
import Testing
enum Snapshots {
static let directory = URL(fileURLWithPath: #filePath)
.deletingLastPathComponent()
.appendingPathComponent("snapshots")
static var updating: Bool { ProcessInfo.processInfo.environment["UPDATE_SNAPSHOTS"] == "1" }
static var locked: Bool { ProcessInfo.processInfo.environment["CI"] != nil }
// camelCase -> snake_case, then anything else to underscores: DateFormatSnapshotTests -> date_format_snapshot_tests
static func sanitized(_ component: String) -> String {
component
.replacingOccurrences(of: "([a-z0-9])([A-Z])", with: "$1_$2", options: .regularExpression)
.replacingOccurrences(of: "([A-Z])([A-Z][a-z])", with: "$1_$2", options: .regularExpression)
.lowercased()
.replacingOccurrences(of: "[^a-z0-9]+", with: "_", options: .regularExpression)
.trimmingCharacters(in: CharacterSet(charactersIn: "_"))
}
// The first eight lines that differ — a short read, not the whole file.
static func firstDifferences(recorded: String, current: String) -> String {
let a = recorded.components(separatedBy: "\n"), b = current.components(separatedBy: "\n")
var diffs: [String] = []
for i in 0..<max(a.count, b.count) where diffs.count < 8 {
let left = i < a.count ? a[i] : "<missing>", right = i < b.count ? b[i] : "<missing>"
if left != right { diffs.append("line \(i + 1):\n recorded: \(left)\n current: \(right)") }
}
return diffs.joined(separator: "\n")
}
}
// Simplified: the real helper also auto-numbers snapshots when `named:` is omitted,
// so parameterized tests sharing one function name get distinct files.
func assertMatchesSnapshot(
_ value: String,
named name: String,
filePath: String = #filePath,
function: String = #function,
sourceLocation: SourceLocation = #_sourceLocation
) {
let suite = Snapshots.sanitized(URL(fileURLWithPath: filePath).deletingPathExtension().lastPathComponent)
let test = Snapshots.sanitized(function.replacingOccurrences(of: "()", with: ""))
let file = "\(test)__\(Snapshots.sanitized(name)).snap.txt"
let url = Snapshots.directory.appendingPathComponent(suite).appendingPathComponent(file)
let relativePath = "snapshots/\(suite)/\(file)"
// The common path: a committed golden exists and no update was requested. Compare and report.
if !Snapshots.updating, let recorded = try? String(contentsOf: url, encoding: .utf8) {
if recorded == value { return }
Issue.record(
"output drifted from \(relativePath) — regenerate with bin/unit-test --update-snapshots, then review every changed line. First differences:\n\(Snapshots.firstDifferences(recorded: recorded, current: value))",
sourceLocation: sourceLocation
)
return
}
// Otherwise we are about to write: the golden is missing, or an update was requested. Never under CI.
guard !Snapshots.locked else {
Issue.record(
"snapshot \(relativePath) is missing or an update was requested, but snapshots are locked under CI — record locally and commit the file",
sourceLocation: sourceLocation
)
return
}
do {
try FileManager.default.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
try value.write(to: url, atomically: true, encoding: .utf8)
} catch {
Issue.record("failed to write snapshot \(relativePath): \(error)", sourceLocation: sourceLocation)
}
}
The drift message does three things. It shows at most eight differing lines, not the whole file. It includes the exact regenerate command. And it says review every changed line rather than rerun to fix, because every changed line in a golden is a change to what users see, and someone has to sign off on it.
The locked guard is the other half. On a developer’s machine, a missing golden gets recorded on the first run, and UPDATE_SNAPSHOTS=1 rewrites it. When CI is set, both of those fail instead of writing. Without that guard, CI would quietly write a missing golden as correct, and a real regression would record itself as the new expected output.
Three other sweeps use the same one-file-per-language shape: the “x ago” relative-time strings, the CLDR unit-conformance tables, and the width probes. The width probes answer a pixel question, whether the widest rendering fits its slot, but they don’t store any pixel measurement. For each intent and clock, the test renders a set of candidate dates in the real device font, finds the widest one, and stores that string. It never stores the width. A width in points changes with OS versions, font revisions, and which machine is rendering, so a golden built on it would fail for reasons that have nothing to do with the app. The chosen string is stable. The German file records that the widest daily full header is Donnerstag, Sept. 24, and any test run on any machine can compare that.
The app-hosted run is the one that counts. It builds the app, signs it, boots a simulator, and measures text in the real device font. It also takes about forty seconds warm, which is too slow for iterating on a pure-logic file like the date rulebook. So we added a second run that compiles a subset of the sources, plus the logic and snapshot tests, into a macOS test bundle. No simulator, no app host, no signing, and it finishes in about six seconds.
Now two runs read the same goldens. If the fast one could write them, it could reset the source of truth to whatever macOS ICU renders, and macOS ICU differs from iOS ICU in a locale or two. The unsigned macOS run would be deciding what’s correct for the iOS one. So the fast script refuses the update flag and unsets the update variable before it runs anything:
#!/bin/bash
# Fast logic tier: macOS-hosted, no simulator, no app host, no signing.
# It READS the committed goldens and must match them; it may never WRITE them.
# Recording is iOS-authoritative: bless via bin/unit-test --update-snapshots. Refuse the flag here...
for arg in "$@"; do
if [ "$arg" = "--update-snapshots" ]; then
echo "❌ Recording from the macOS host is not allowed — the goldens are"
echo " iOS-authoritative (bless with bin/unit-test --update-snapshots)."
echo " A macOS parity failure is a stop-the-line finding, never a re-record."
exit 1
fi
done
# ...and strip the variable so nothing downstream can record either.
unset UPDATE_SNAPSHOTS
# Simplified: the real script also pins a shared DerivedData, SPM cache, and compilation cache.
xcodebuild test \
-workspace HelloWeather.xcworkspace \
-scheme HelloWeatherLogicTests \
-destination 'platform=macOS' \
-quiet \
CODE_SIGNING_ALLOWED=NO
When the fast run passes, it rendered the committed goldens the same way iOS did, and nothing gets rewritten. When it disagrees, we don’t fix that by recording on macOS. It means macOS and iOS ICU differ for some locale, and the fix is to drop that test from the macOS bundle and keep it on the app-hosted run only.
Treat a snapshot diff as a behavior change. It’s a copy edit, not a chore to get the build green. Have the failure message say “review every changed line,” include the regenerate command, and show only the first few differences.
Store what the measurement picked, not the measurement. When a number only chooses among candidates, commit the candidate. The chosen string is stable across machines and the width isn’t.
Escape the invisible characters. A raw diff hides a narrow space or a directional mark. Escape whitespace and format scalars to \u{...} and leave the letters readable.
Don’t stop a language-cycling run partway. The sweeps set the app language and restore it at the end. If you kill the run in the middle, the stored test settings stay on a foreign language, and later runs fail the formatting tests until you clear it.
The design wants “5pm”, not “5 PM”. So a screen writes "ha" and lowercases the result: formatter.string(from: date).lowercased(). That gives “5pm” in English and quietly breaks everywhere else. Hungarian’s meridiem, stripped and lowercased, becomes “de”, the word for “but”. Japanese, Korean, and Chinese don’t use a meridiem for short hours at all, and their dates want a year-month-day shape that no Western pattern produces. Vietnamese writes the weekday and the month as numbers, so a month-first header is three numbers in a row.
Another screen writes "EEE", a third copies the lowercasing line, and now the formatters disagree on capitalization and meridiem. What each screen should look like is spread across dozens of call sites. When a translator reports one of these breaks, there’s no one switch to fix. There’s a search-and-replace and a hope that you found them all.
The scale makes this expensive. Hello Weather shows dates in 24 distinct places: a sunrise time under an icon, a weekday rail under the hourly chart, a watch complication hour capped at five characters. It does that in 27 languages, with a user-selectable 12- or 24-hour clock. One person maintains it, with a model doing the translating and no agency behind it, so there’s no room for date code only one screen understands. This post is the date piece of that localization work. Rendered-width validation and vendor language probing guard the rest.
We treat date formatting as configuration, not as code each screen writes for itself. Every date string in the app, watch, and widgets goes through three stages:
sunEventTime, dailyHeader), not formats.plan(for:) switch that maps an intent plus a language to a render plan.switch over every language, so no language list sits inside an intent arm.The call site knows nothing. Text(sunset.withFormat(.sunEventTime)) carries no format string, no lowercasing, no locale plumbing. withFormat looks up the current language and time zone, asks the intent for its plan, and renders.
A reviewer fixing how sun times render in Finnish should have one place to look. Adding a dated screen should be impossible without deciding how it reads in every language. An exhaustive switch with no default gives us both. The block below shows the shape in miniature: the plan struct, a slice of the intent enum, three classifiers, and the switch that ties them together. It compiles as written.
import Foundation
enum Language: String, CaseIterable {
case en, de, fr, hu, ja, vi
// one case per supported language; ~two dozen more elided
}
enum Meridiem {
case localeDefault // keep CLDR's own am/pm symbols
case plainLower // bare lowercase: "5:39pm"
}
enum MeridiemForm { case nativePunctuated, plainLetters }
enum DateOrderGroup { case western, cjk }
enum HeaderDateOrder { case monthDay, dayMonth }
extension Language {
// Most languages take bare lowercase letters. Three keep the punctuated
// native form: stripped, the Czech and Finnish markers are not words, and
// Hungarian's "de" is the word for "but".
var meridiemForm: MeridiemForm {
switch self {
case .hu: return .nativePunctuated
case .en, .de, .fr, .ja, .vi: return .plainLetters
}
}
var standardMeridiem: Meridiem {
switch meridiemForm {
case .nativePunctuated: return .localeDefault
case .plainLetters: return .plainLower
}
}
// CJK renders native 年月日 via ICU templates; Western uses explicit patterns.
var dateOrderGroup: DateOrderGroup {
switch self {
case .ja: return .cjk
case .en, .de, .fr, .hu, .vi: return .western
}
}
// Exactly one language orders headers day-first: Vietnamese, whose numeric
// weekday and month collide with the day in month-first order.
var headerDateOrder: HeaderDateOrder {
switch self {
case .vi: return .dayMonth
case .en, .de, .fr, .hu, .ja: return .monthDay
}
}
}
struct DateRenderPlan {
enum Kind {
case pattern(String) // an explicit, ordered format
case template(String) // an ICU skeleton; ICU picks the order
}
let kind: Kind
let twentyFourHourVariant: String?
let context: Formatter.Context // .beginningOfSentence capitalizes the first word
let meridiem: Meridiem
static func pattern(_ p: String, capitalized: Bool) -> DateRenderPlan {
DateRenderPlan(kind: .pattern(p), twentyFourHourVariant: nil,
context: capitalized ? .beginningOfSentence : .unknown,
meridiem: .localeDefault)
}
static func time(_ p: String, or h24: String, meridiem: Meridiem) -> DateRenderPlan {
DateRenderPlan(kind: .pattern(p), twentyFourHourVariant: h24,
context: .unknown, meridiem: meridiem)
}
static func template(_ t: String, or h24: String? = nil) -> DateRenderPlan {
DateRenderPlan(kind: .template(t), twentyFourHourVariant: h24,
context: .unknown, meridiem: .localeDefault)
}
}
enum DateFormatIntent: String, CaseIterable {
case summaryWeekday, dailyHeader, sunEventTime, forecastUpdatedDateTime
// 24 cases total, one per UI surface; the rest elided
// Exhaustive, no default: a new case does not compile until it has an arm.
func plan(for language: Language) -> DateRenderPlan {
switch self {
case .summaryWeekday:
return .pattern("E", capitalized: false)
case .dailyHeader:
switch language.dateOrderGroup {
case .cjk: return .template("MMMdE")
case .western:
switch language.headerDateOrder {
case .monthDay: return .pattern("E, MMM d", capitalized: true)
case .dayMonth: return .pattern("E, d MMM", capitalized: true)
}
}
case .sunEventTime:
switch language.dateOrderGroup {
case .cjk: return .template("hmm", or: "Hmm")
case .western: return .time("h:mma", or: "H:mm", meridiem: language.standardMeridiem)
}
case .forecastUpdatedDateTime:
switch language.dateOrderGroup {
case .cjk: return .template("MMMdEhmm", or: "MMMdEHmm")
case .western:
switch language.headerDateOrder {
case .monthDay: return .time("E, MMM d @ h:mma", or: "E, MMM d @ H:mm",
meridiem: language.standardMeridiem)
case .dayMonth: return .time("E, d MMM @ h:mma", or: "E, d MMM @ H:mm",
meridiem: language.standardMeridiem)
}
}
}
}
}
The intent arms hold no list of languages. dailyHeader asks language.dateOrderGroup and language.headerDateOrder and branches on the answers. The intent knows the shape of a header, and the classifier knows which languages deviate from it.
Once a switch self { case .fi, .hu: … } shows up inside a formatting rule, the reason for the exception is lost, and the next language that needs the same treatment gets added somewhere else. A named classifier keeps the quirk and its reason together, so every exception in the app is one arm you can point at.
Each classifier exists because a real language broke a naive rule. meridiemForm records that Hungarian keeps its punctuated form. The locale test that pins that rendering carries the reason, “Adjudicated: keep the period — bare ‘de’ is the Hungarian word for ‘but’”, which nobody would think to write from first principles. dateOrderGroup is why the CJK languages (Chinese, Japanese, Korean) get ICU templates, where the system picks the field order, instead of a hardcoded Western order. A sibling classifier, compactHourStyle, is why their short hours render as “9時”/”9时”/”9시” rather than “9pm”. headerDateOrder is a single arm for Vietnamese. We didn’t make a vague “some languages are day-first” category, because it would pull in languages that don’t want it.
The house voice wants “5:39pm”: lowercase, no space, no periods. Lowercasing the rendered string is wrong twice over. It lowercases any weekday or month name that should stay capitalized, and unless you pass a locale it uses ASCII casing rules, which mangles languages like Turkish. The right moment to decide the meridiem is when the formatter is built, by changing its AM/PM symbols before it renders anything. This function does that, and it runs as written. In the app it’s a private method on the formatter cache.
import Foundation
enum Meridiem { case localeDefault, plainLower }
/// Shapes AM/PM symbols at construction so the formatter emits the house voice
/// directly. Never a `.lowercased()` on the formatter's output.
func applyMeridiem(_ meridiem: Meridiem, to formatter: DateFormatter,
dateFormat: String, locale: Locale) {
guard dateFormat.contains("a") else { return } // no meridiem to shape
switch meridiem {
case .localeDefault:
return
case .plainLower:
let bareLowercase: (String) -> String = { symbol in
let letters = symbol.unicodeScalars.filter {
CharacterSet.letters.contains($0) || CharacterSet.decimalDigits.contains($0)
}
return String(letters).lowercased(with: locale)
}
if let am = formatter.amSymbol { formatter.amSymbol = bareLowercase(am) }
if let pm = formatter.pmSymbol { formatter.pmSymbol = bareLowercase(pm) }
}
}
It keeps only the letters and decimal digits from the locale’s own symbol and lowercases them with that locale’s casing rules. “5:39 p. m.” becomes “5:39pm”, and Turkish “ÖS” becomes “ös” under Turkish casing, not ASCII. The guard on the a pattern character lets formatters with no meridiem skip the work. When a call site really needs a different case, it passes a declared case: parameter, and the formatting layer applies it once, with the locale. A handful of alternate styles do that, to set a rail in caps. The rest never do, because the voice they want is already in the symbols.
“Never lowercase a rendered date” only holds if nobody can quietly bring it back, and the compiler can’t see a .lowercased() habit the way it sees a missing switch arm. So a test reads every Swift file in the app, runs a regex over each one, and fails with the matches it found. This is the complete check, under Swift Testing, as written.
import Testing
import Foundation
@Suite struct DateFormatCallsiteTests {
static let sourceRoot = URL(fileURLWithPath: #filePath)
.deletingLastPathComponent()
.deletingLastPathComponent()
.appendingPathComponent("App") // your source tree
static func swiftSources() -> [String] {
guard let files = FileManager.default.enumerator(
at: sourceRoot, includingPropertiesForKeys: nil) else { return [] }
return files.compactMap { item in
guard let url = item as? URL, url.pathExtension == "swift" else { return nil }
return try? String(contentsOf: url, encoding: .utf8)
}
}
@Test func caseMethodsNeverChainOnFormattedDates() throws {
let sources = Self.swiftSources()
try #require(sources.count > 100, "source scan found too few files")
let chain = try NSRegularExpression(pattern:
#"withFormat(?:ForDeviceTimeZone)?\([^()]*\)\.(?:lowercased|uppercased|capitalized)"#
+ #"|withRelativeFormat\(\)\.(?:lowercased|uppercased|capitalized)"#)
var offenders: [String] = []
for source in sources {
let range = NSRange(source.startIndex..<source.endIndex, in: source)
for match in chain.matches(in: source, range: range) {
if let r = Range(match.range, in: source) {
offenders.append(String(source[r]))
}
}
}
#expect(offenders.isEmpty,
"case methods chained on rendered date strings: \(offenders). Use withFormat's "
+ "`case:` parameter (.lower/.upper) so the formatting layer applies the transform "
+ "once, locale-aware. (Scan catches case chained directly on a withFormat(...) call "
+ "only; case reached through an intermediate variable or wrapper must be caught in review.)")
}
}
The failure message admits the scan’s limit. It catches a case method chained directly on the call, and a transform reached through a wrapper or an intermediate variable is left to review. Two sibling tests round out the bans. One fails if any intent case has no call site, because an intent with no UI is either dead code or a wiring bug, and either way the test forces the question. The other freezes the small set of raw format strings the frozen alternate-style catalog may still use, so new UI can’t slip in a raw dateFormat and has to add an intent instead. Two more exhaustive switches classify every intent by width budget and by worst-case sample, so adding a case fails three separate compiles until it’s classified three ways.
Every intent’s rendering in every language is captured in committed golden files, which a machine records and a machine updates. A companion post covers that matrix and the fast macOS test tier. The risk is that a careless record run could bless a regression into the English golden, and the diff would look like every other regeneration. So a handful of English outputs are also pinned by hand, in a table a person edits and a record run never rewrites.
@Test func englishAnchorsHoldAtTheEveningInstant() {
// A hand-picked instant (2026-08-15, 17:39 local), not a machine sample.
// withFormat / withAppLanguage / DateFormatSamples are the test harness.
// Three of the eight 12-hour anchors; the real table also pins the 24-hour clock.
let anchors: [(DateFormatIntent, String)] = [
(.dailyHeader, "Sat, Aug 15"),
(.sunEventTime, "5:39pm"),
(.forecastUpdatedDateTime, "Sat, Aug 15 @ 5:39pm"),
]
withAppLanguage(.en) {
for (intent, expected) in anchors {
#expect(DateFormatSamples.evening.withFormat(intent) == expected,
intent.rawValue)
}
}
}
These overlap the English rows in the golden table on purpose. The golden records what the code produces today, and the anchors record what a person decided it should produce. If a record run ever drifts the English output, the goldens follow it silently and the anchors go red.
plan(for:) switch. A rendering fix for any language is a one-arm edit instead of a codebase-wide hunt. Each per-language exception, from the Hungarian meridiem and the Vietnamese day-first header to the CJK hour counters and the six declared weekday arrays, is one classifier arm that carries its reason.Someone who reads their phone in German but wants their weather in Japanese should get Japanese in the app, in the home-screen widget, and on the watch face, from one tap in one settings row. That’s the requirement. The language is chosen once inside the app, it applies everywhere text appears, it changes without a relaunch, and it never comes from the phone’s language.
Hello Weather makes that harder than it sounds because it isn’t one program. The app draws text, and so do its widgets, its watch app, and its notifications. Each one runs as its own process, and nothing the app sets up at launch carries over to the others.
Apple offers two obvious ways to do this, and both fail.
The first is AppleLanguages, an array in UserDefaults that iOS reads to pick a process’s language. Writing to it fails the goal three ways. iOS reads the value at launch and caches it, so a change needs a relaunch. It persists across app updates in a way you don’t control. And it’s the same key that iOS’s own per-app language row writes, so setting it from inside the app fights the system row instead of replacing it.
The second is plain String(localized:). It looks strings up in Bundle.main, which uses the device language. Every string localized that way skips the in-app picker. The user picks Japanese and half the UI stays in German because it went through the wrong API.
Under both is the fact that “the language” isn’t one thing in SwiftUI. A Text("...") literal gets its language from the locale in the environment. A plain String built for a notification or an accessibility label gets its language from whichever API you call. Fix one path and the device language leaks in through the other. So before any translation, we had an architecture question: where does the app’s language live, and how does every string on screen get its language from there?
One setting owns the language, and everything that renders text reads it through one of two paths, which we call gates. The setting is a plain string in shared storage, backed by an enum:
import Foundation
enum Language: String, CaseIterable, Identifiable {
case cs, da, de, el, en, es, fi, fr, hi, hu, id, it
case ja, ko, nb, nl, pl, pt, ro, ru, sv, th, tr, uk, vi
case zhHans = "zh-Hans"
case zhHant = "zh-Hant"
var id: String { rawValue }
var locale: Locale { Locale(identifier: rawValue) }
}
Twenty-seven cases, backed by strings, so the raw value is both the locale identifier and the value we store. The two Chinese cases carry explicit raw values because their identifiers aren’t bare language codes. In the app each case also carries a displayName, the language’s native name (“Deutsch”, “日本語”, “简体中文”). The picker lists each language by its name in the current app language, with the native name as a subtitle, so a user scanning the list can find their own script.
The default is English on purpose. The app soft-launched, so it stays in English until a user opts in:
func languageDefault() -> String {
// TODO: detect the device locale and return the matching Language, if supported.
return Language.en.rawValue
}
Adopting the device language on first launch is a product decision with support consequences. It’s easy to turn on later by returning the matching device code instead of a hard en. Starting with English means nobody gets a language they didn’t pick.
SwiftUI localizes Text("...") literals using the locale in the environment. Set that locale from the language setting and every literal in the view tree follows it, with no wrapper and no helper at the call site. The catch is that you can’t set it once. A widget is a different process and inherits nothing from the app, so the locale has to be set again, which we call pinning, at the root of every process that renders text. In the app that root is the scene:
import SwiftUI
// An app-group suite, so the widget and watch processes read the same value.
let sharedStore = UserDefaults(suiteName: "group.example.weather")!
final class SettingsManager: ObservableObject {
static let shared = SettingsManager()
var language: String {
get { sharedStore.string(forKey: "language") ?? languageDefault() }
set {
sharedStore.set(newValue, forKey: "language")
objectWillChange.send()
}
}
var languageLocale: Locale {
Language(rawValue: language)?.locale ?? Locale(identifier: "en")
}
}
@main
struct WeatherApp: App {
@ObservedObject private var settingsManager = SettingsManager.shared
var body: some Scene {
WindowGroup {
ContentView()
.environment(\.locale, settingsManager.languageLocale)
}
}
}
The widget is its own target and starts cold, so it pins the same locale again inside its configuration’s content closure:
import SwiftUI
import WidgetKit
struct SmallCurrentWidget: Widget {
let kind = "SmallCurrent"
var body: some WidgetConfiguration {
AppIntentConfiguration(kind: kind, intent: Configuration.self, provider: Provider()) { entry in
SmallCurrentView(configuration: entry.configuration, viewModel: entry)
.environment(\.locale, SettingsManager.shared.languageLocale)
}
.configurationDisplayName("Small Current")
.supportedFamilies([.systemSmall])
}
}
The pin is one line in each block, and each one reads from the same SettingsManager.shared. Our repo has 35 of them: the app root, every widget entry view, the watch root, and each complication view. That repetition looks like a smell until you see what it prevents. A widget that forgets the pin renders in the device language. It looks right in a simulator running in English, so the bug ships.
localized(_:) Helper for String-Typed CopyViews are only half the strings. Notifications, accessibility labels, dictionary values in a manager, and chart-unit suffixes need a real String, and a String has no environment to read. We don’t allow String(localized: "…") because it uses the device language. Instead, every one of those strings goes through one helper, built on the Language enum above:
private let languageLocales: [String: Locale] = Dictionary(
uniqueKeysWithValues: Language.allCases.map { ($0.rawValue, Locale(identifier: $0.rawValue)) }
)
// Resolves in the app language, not the device language.
func localized(_ resource: LocalizedStringResource) -> String {
var resource = resource
let language = sharedStore.string(forKey: "language") ?? Language.en.rawValue
resource.locale = languageLocales[language] ?? Locale(identifier: language)
return String(localized: resource)
}
Two choices make it work. First, the parameter is a LocalizedStringResource, not a String. When you write localized("Ranges") the compiler sees a resource literal and pulls "Ranges" into the catalog, the same as it would for a Text. With a String parameter the compiler would extract nothing. Second, the helper reads the language from the same shared key the setting writes, defaults to English, sets resource.locale, and only then calls String(localized:). That one assignment is the gate. The languageLocales dictionary is built once so we don’t construct a Locale on every call.
At the call site it looks ordinary: localized("Ranges"), or localized("\(minutes) minutes") to fill in a plural key. Every String a user can see goes through it. Between the environment pins for Text and this helper for String, there’s no third path, and neither path can reach the device language.
Each thing we wanted maps to one of the levers we rejected. Switching is live because the environment locale is read on every render and the helper reads the setting on every call. Change the setting and the next render is in the new language. AppleLanguages can’t do that, because it’s cached until restart. There’s no fight with iOS because we never touch AppleLanguages, so the app’s language and the system’s per-app row never overwrite each other. The limit is that the per-app language row iOS shows for the app in Settings is still there but does nothing, because nothing in the app reads Bundle.main’s language. A user who changes it there sees nothing happen. Anyone copying this pattern should decide whether to explain that in the app.
The two gates send every string to the right language. What shows up on screen comes from the String Catalog (Localizable.xcstrings), and its sharpest edge is this: a key with no row for the current language renders the raw key, not the English source value. People assume localization falls back to the source language. It doesn’t. If the Japanese table is missing "Air Quality", a Japanese user sees Air Quality only because that key happens to read like English. A key named "aqi.title" would put aqi.title on screen.
That makes the catalog all-or-nothing. A key is either translated in every shipped language or it’s a bug waiting for one user in one language. We enforce that with a test that reads the catalog file directly, so it catches a gap before a build can repackage it:
import Testing
import Foundation
@testable import HelloWeather
@Suite("String catalog completeness")
struct XcstringsCompletenessTests {
// Every Language case except the source language.
private static let requiredLanguages = Set(
Language.allCases.map(\.rawValue)
).subtracting(["en"])
// Key -> the set of language codes that have a row. Values are discarded.
private func loadCatalog(_ name: String) throws -> [String: Set<String>] {
let url = URL(fileURLWithPath: #filePath)
.deletingLastPathComponent()
.deletingLastPathComponent()
.appendingPathComponent("HelloWeather/HelloWeather/Resources/\(name).xcstrings")
let data = try Data(contentsOf: url)
let json = try #require(try JSONSerialization.jsonObject(with: data) as? [String: Any])
let strings = try #require(json["strings"] as? [String: Any])
return strings.mapValues { entry in
let localizations = (entry as? [String: Any])?["localizations"] as? [String: Any] ?? [:]
return Set(localizations.keys)
}
}
@Test("Localizable keys are fully translated or fully untranslated")
func localizableKeysAreAllOrNothing() throws {
let catalog = try loadCatalog("Localizable")
for (key, languages) in catalog {
let missing = Self.requiredLanguages.subtracting(languages)
#expect(missing.isEmpty || missing == Self.requiredLanguages,
"\"\(key)\" is partially translated; missing: \(missing.sorted())")
}
}
}
A key must appear in all 26 non-English languages or in none of them. The “none” case is for copy we’ve deliberately held back behind a flag. Any partial set fails. The required set is the Language enum minus en, so adding a language to the enum adds it to the test. The loader keeps only the set of language codes under each key and drops the values, because the test asks which languages are present, not what they say.
The nastiest hazard is in the tooling, because it deletes work silently. A command-line build can regenerate the catalog and remove any key it doesn’t see referenced, along with that key’s translations. We’ve watched a key like "1 min", used in a view but referenced in a way the command-line pass didn’t catch, lose all 26 of its translations in one regenerated file.
The defense has two layers. First, a mechanical check before committing the catalog after a build:
git diff -- HelloWeather/HelloWeather/Resources/Localizable.xcstrings \
| grep -c '^-.*"value"'
A non-zero count means translated values are being deleted. The fix is to restore the file, not commit it. Second, a test checks a fixed list of the keys that prune easily, so a regression fails loudly instead of shipping:
@Test("Keys with few referents stay translated across catalog regeneration")
func sentinelKeysStayTranslated() throws {
let catalog = try loadCatalog("Localizable")
let sentinels = [
"1 min", "5 min",
"Rename", "Custom Name", "Favorite", "Unfavorite",
"Customize locations",
"Tap a location's name to rename it, or tap a star to fave. Drag to reorder.",
"Reset Locations Tip",
]
for key in sentinels {
let languages = try #require(catalog[key], "\"\(key)\" pruned from the catalog")
#expect(Self.requiredLanguages.subtracting(languages).isEmpty)
}
}
The keys in the list have few references in code, which is why they prune easily. The test fails if any of them is missing from the catalog or has lost a language.
AppleLanguages. The downside we accepted is that the iOS per-app language row for the app does nothing, which the localization plan flags as a support-confusion risk.It started with a screenshot of Hello Weather. The hourly strip showed a row of 20-25% rain-chance labels, and the “precip later” pill, the small button that announces rain coming later, was nowhere on the screen. Two parts of one screen disagreed about whether it was going to rain.
Neither one was broken. Each was following its own rule for “is this probability worth showing?”, and the codebase had four rules:
(The numbers here, a 5% rounding step and a 20% floor, are ours. Nothing below depends on them.)
None of these were careless. The pill’s higher floor was a deliberate choice to stop advertising marginal rain. The detail card’s cutoff was older than the rounding helper. The push code compared the value it had in hand. The four drifted apart because each one changed on its own and nothing tied them together. Two real bugs had already shipped from this group of thresholds before the screenshot: the raw-vs-rounded mismatch in the suppression clause, and a pill that stopped staying clear of rendered bars after one floor moved and the other didn’t.
We could have set the four constants to the same number. That would fix the screenshot and leave the four sites free to drift again the next time one of them changed. Instead we made one place that answers the question:
enum PrecipDisplay {
static func showPrecip(val: Float) -> Bool {
val.toRoundedPrecip >= 0.2
}
}
extension BinaryFloatingPoint {
var toRoundedPrecip: Self {
self.rounded(to: 0.05)
}
}
The function is pure, lives in a shared extensions file, and compiles into all four targets (app, widgets, watch app, watch extension). It’s called from the hourly and daily labels, bar colors, the pill’s trigger and its headline scan, VoiceOver’s per-hour precipitation clause, push copy, the stat cards’ on/off states and icons, the detail charts’ point icons, and both lock-screen slots. Forty-four call sites, by the PR’s count.
Two choices in that small function do most of the work.
First, every caller passes the raw value and the function rounds it. Callers don’t choose which version to compare, so the raw-vs-rounded bug can’t happen. Rounding an already-rounded value gives the same value back, so it doesn’t matter if a caller’s number has already been through the display formatter. A test checks that instead of assuming it:
@Test func agreesForRawAndPreRoundedInputs() {
for raw in stride(from: Float(0), through: 1, by: 0.001) {
#expect(PrecipDisplay.showPrecip(val: raw) ==
PrecipDisplay.showPrecip(val: raw.toRoundedPrecip))
}
}
Boundary tests next to it pin the rounding cliff (0.174 hides, 0.175 shows). The sweep test matters more, because it’s the proof that “pass whatever you have” is safe.
Second, the threshold belongs to a named type instead of being a loose constant. PrecipDisplay is an enum with no cases. It’s only a namespace. That looks like ceremony until you read the rule that shipped with it:
Any future second threshold must land as a named
PrecipDisplaymember, never an inline constant at a call site.
The rule keeps the four from drifting apart again. The drift didn’t start as four thresholds. It started as one threshold and a reasonable-looking inline 0.3 at one call site. The rule allows a second threshold, because the product may need one. It doesn’t allow an anonymous one. A named member sits next to its sibling, gets reviewed as a deliberate fork, and can be found by anyone auditing the group. An inline constant at a call site is invisible until it shows up in a screenshot.
A rule that only lives in a commit message lasts until the commit scrolls off the first page of git log. This one went into the code-review skill, the checklist the review agent walks on every PR, as two rewritten bullets. Here they are as of September 2026, sanitized and trimmed of PR numbers and the geometry caveats. The significantPrecip clauses were added later; more on that below.
Precip display gates (hourly/daily labels and bar colors, the precip-later button, VoiceOver per-hour precip clauses, push-copy precip lines, precip stat card/detail on-off states and icons) route through
PrecipDisplay.showPrecip(rounded ≥ 0.2) - new or modified display gates must call it, never hardcode a literal - and hourly-strip window decisions (lane, bars, pill) route throughPrecipDisplay.significantPrecip. Deliberate exceptions (relevance thresholds, the chart-summary> 0accessibility gates, and the frozen style catalogs in all three targets) are inventoried in the unification plan.The button must never cover a rendered precip bar. Since the unification, bars, labels, and the button share one per-hour floor:
PrecipDisplay.showPrecip(rounded ≥ 20%). One window-significance predicate sits above it,PrecipDisplay.significantPrecip, so lane, bars, and button live or die together. Within a significant window the single per-hour floor means “firstshowPrecipindex ≥ visible-column threshold” alone guarantees no rendered bar sits under the button; in an insignificant window nothing renders at all - there is deliberately no separate suppression clause. If the per-hour floors ever diverge (the significance rule is a window shape test, not a second per-hour floor), the divergence must land as a namedPrecipDisplaymember and the explicit suppression clause - rounded on BOTH sides; the raw/rounded split shipped a bug once - becomes load-bearing again.
The second bullet says what has to come back if the floors ever split again. With one floor, the pill’s old suppression clause was redundant. “The first qualifying hour is past the visible window” and “no rendered bar in the visible window” mean the same thing when bars and pill use the same test. So we deleted the clause and sketched the proof in the PR. That only holds while there’s one floor. The checklist doesn’t just say we deleted it. It says the clause comes back, rounded on both sides, the day the floors split, so the next person doesn’t ship the old bug again.
We did the same for a decision that got overruled along the way. The designer had proposed two thresholds: forgiving display gates, and a stricter pill that only fires when rain is worth interrupting for. We shipped one uniform floor instead, because it was the simpler rule and we could adjust once we had field evidence. The designer’s version wasn’t thrown away. It’s in the plan doc as the ready alternative, built on a branch, with instructions that bringing it back means a named member and the restored suppression clause. Neither side had field evidence, so the plan lists the two options as equals rather than as default and exception. If we hadn’t written it down, we’d have had the same debate again from scratch in six months.
The evidence arrived at the end of August. A single 20% hour with no icon rendered one bar and a pill, and the owner and designer agreed that was misleading. The problem was the shape of the window, one weak hour on its own, not the floor. The fix landed on 2026-08-31 the way the rule requires, as a named member, PrecipDisplay.significantPrecip. It’s a window-level test that hides the hourly strip’s lane, bars, and pill when the only qualifying hour in a window of 12 hours or more rounds below 30%. The per-hour floor didn’t change. The labels and cards still gate per hour, and the short lock-screen strips stay on showPrecip on purpose, with that listed in the plan.
Routing every comparison through one function means reading every comparison, and one of them didn’t make sense.
The rectangular lock-screen widget and the matching watch complication have a slot where, on rainy hours, the precip percentage replaces the temperature. The check for it compared the probability, a fraction from 0 to 1, against a whole-number percent:
// before: precipProbabilityValue is the rounded 0.0-1.0 probability
if precipProbabilityValue >= 20 { ... }
A fraction is never ≥ 20. The check was always false, so the slot had never shown for anyone since the day it shipped. Nobody noticed, because a check that’s always false looks the same as “it hasn’t rained lately.” Routing the site through the chokepoint fixed it, because the chokepoint takes fractions, and the slot rendered for the first time. That turned up one more problem. Localized percent strings like “100 %” overflow a 31-point slot, so the label got a minimumScaleFactor. A feature that has never rendered has never been through layout QA either.
This is the best practical argument for the chokepoint. A function with one signature also fixes the units. Four scattered comparisons can each pick their own units and each be wrong. Forty-four call sites passing a Float to one function can’t.
A sweep like this can fail two ways: missing a site, or pulling in a site that only looks like the same question. The second is harder to spot. Not every comparison against a probability is a display gate:
> 0, which is wider than the display floor on purpose. A VoiceOver description of a whole chart (“up to N percent”) should describe what the chart plots, and the detail charts plot values below the floor.Leaving them out is the easy part. Each one is also listed in the plan doc the checklist bullet points at, with the reason it’s a different question. Without that list, a reader can’t tell an exemption from a site the sweep missed.
“We routed everything through one function” is a claim, and the session that did the routing can’t see its own blind spots. So before merge, the change went through our adversarial review process: four independent, read-only reviewers, none of them with the session’s reasoning.
One reviewer’s job wasn’t “review this diff.” It was “prove or refute the claim that this is complete”: find every comparison against a probability in the codebase and account for each one. It found four outside the frozen style catalog, the chokepoint plus the three relevance-scoring exemptions from the plan, and nothing else. That’s a list checked against the inventory, not “the diff looks complete.”
That’s a different kind of assurance, and it’s cheap to ask for. The main claim of a unification PR is that no other site answers this question. A diff review can’t check that, because any site that breaks the claim isn’t in the diff. So give one reviewer the whole codebase and that claim as its job.
The other reviewers found real things too. One traced boundary values through every screen and confirmed with predicate math that deleting the suppression clause was safe. It found two bugs, and both were fixed before merge: a gap in how the pill’s headline scan picked its anchor hour, and an off-by-one where the “starting soon” copy named the precip type of the hour after the match (“rain possible in 3h” for what was actually snow). One known gap stayed open. The column counts for wide layouts on tablets and landscape phones are hand-maintained estimates, not measured, and the plans record that as deferred, with measuring them named as the real fix.
The Hello Weather watch app has an hourly strip: 24 columns, one per hour, that you drag sideways. On a real watch the drag was choppy. While you drag, SwiftUI re-runs the view’s body every frame, and the work inside our body was repeated for every one of the 24 columns. The same thing can happen in almost any SwiftUI list.
The drag is a @GestureState that feeds an .offset through a computed property, so every touch event re-runs the whole body. A computed property in Swift is a function that looks like a variable: it runs its code every time you read it. Inside the body is a ForEach over the 24 hours, and inside the ForEach are reads of computed properties whose values never change during the loop:
// In a shared extension - every one of these is a computed property.
extension HourlyView {
var hourlyData: [Forecast.Hourly.Hour] {
viewModel.weather?.forecast?.hourly?.data ?? Forecast.Fallback.hourlyData
}
var hourly: [Forecast.Hourly.Hour] {
let safeCount = min(hourCount, hourlyData.count)
return Array(hourlyData.prefix(safeCount))
}
var maxHourlyTemp: Int {
let safeCount = min(hourCount + 2, hourlyData.count)
if SettingsManager.shared.feelsLikeMode {
return (hourlyData.prefix(safeCount).map { $0.apparentTemperature ?? $0.temperature ?? 0 }.max() ?? 0).toInt
} else {
return (hourlyData.prefix(safeCount).map { $0.temperature ?? 0 }.max() ?? 0).toInt
}
}
// ...minHourlyTemp, same shape
var showHourlyPrecips: Bool {
hourly.contains { showPrecip(val: $0.precipProbability ?? 0) }
}
}
Each one looks harmless on its own, but they add up. hourly[index] builds a fresh array for every subscript. Each hour column reads maxHourlyTemp, minHourlyTemp, and showHourlyPrecips, and each of those takes a prefix of the data and maps over it. The check for a day boundary between two neighboring hours built a new Calendar for each comparison, 23 of them for 24 hours. That comes to roughly 142 array allocations and 23 Calendar constructions per body evaluation. During a drag, that means per frame, on a watch.
That’s four years of “add a computed var to the shared extension” being the easiest way to add a value. Nobody notices until a gesture makes the body run constantly.
letSwiftUI doesn’t cache a computed property. It runs the property’s code every time it’s read. A let at the top of a @ViewBuilder runs once per body pass. So the fix is to read each unchanging value once, above the loop, into a let. Moving work out of a loop like this is called hoisting, and that’s the word the rest of this post uses.
private var hourlyChart: some View {
let hours = hourly
let maxTemp = maxHourlyTemp
let minTemp = minHourlyTemp
let showPrecips = showHourlyPrecips
let dayCalendar = settingsManager.hourlyIsGrouped ? viewModel.weather?.forecast?.currentCalendar : nil
return HStack(spacing: 2) {
ForEach(hours.indices, id: \.self) { index in
let hour = hours[index]
if index > 0,
let calendar = dayCalendar,
let currentTime = hour.time,
let previousTime = hours[index - 1].time,
calendar.startOfDay(for: currentTime) != calendar.startOfDay(for: previousTime) {
// Simplified: the real separator sits in a GeometryReader that pins it mid-glide.
HourlyDaySeparatorView(day: currentTime)
}
Hour(max: maxTemp, min: minTemp, bar: hour, showPrecips: showPrecips)
}
}
}
Now each body pass does one array, one max, one min, one precipitation scan, and one calendar. Two details caught us:
hours = hourly), not Swift’s shorthand for reusing a name. let x = x compiles inside if let, but not at declaration scope. Use a distinct name or self.x.@ObservedObject, @EnvironmentObject), not when an individual property changes. When the view model changes, the body re-runs and takes fresh snapshots.That was one ForEach and one afternoon. Then three agents audited the app, watch, and widget targets for the same pattern and found it in 51 files. It looked the same everywhere: settings pickers rebuilding a dictionary of localized names for every option, a radar legend measuring label widths for every label on every animation frame, a locations list decoding JSON three times per row, stats charts recomputing their ranges for every data point.
The sweep that fixed all 51 files went through two review rounds with seven independent reviewers, following /adversarial-review-rounds/. Their confirmed findings turned “hoist the invariants” from an instinct into rules. Each rule below exists because the obvious hoist was wrong somewhere.
Hoist only what never changes in the loop AND is always evaluated. Those are two separate tests. A sparkline view read its precipitation range only behind if showsCurve. Hoisting that read above the guard made it run for every daily row, including rows where the server’s min...max bounds could be backwards, and a backwards ClosedRange crashes when it’s built. If the original read sat behind a condition, the hoist keeps that condition, with placeholder values for the other branch, or it doesn’t happen.
Hoist INTO deferred builders, never out of them. The content closures of Menu and Picker don’t run when the body runs. They run when the menu opens. A names dictionary hoisted from inside a Menu builder up to body scope changes what the user sees: they now get a snapshot from whenever the body last ran, not from when they opened the menu. The second review round moved one of ours back inside each menu builder for this reason. The other direction is safe. Work already inside a deferred builder that runs once per option can move to the top of that builder, and it still costs nothing until the menu opens.
Leave onAppear and action-closure reads alone. Same rule, other direction. Those closures run after the body, so they need to see the world as it is when they fire, not a snapshot from body time.
Pass optionals through. Don’t replace them with ?? "". Several hoists turned force-unwraps and dictionary lookups into parameters. Where the receiving view’s parameter is Optional, pass the optional. With nil, SwiftUI skips the subview entirely. With "", it renders an empty view that still takes up layout space. Those are different view trees, so a diff that “just adds a fallback” changes what’s on screen.
Harden server-fed ranges while you’re there. Any min...max built from network data gets clamped (lower...max(lower, upper)), and any stride gets a > 0 step guard. Review found a real stride-by-zero crash sitting next to one of the hoists.
So the “mechanical” sweep wasn’t mechanical. Every one of those findings came from a reviewer who had no reason to want it to be simple.
By every check we had, the sweep was done. Build and unit tests were green at every commit. It had been through two review rounds, and every finding was settled and fixed. It was 51 files applying one pattern. We closed it anyway.
Nothing was wrong with it. But 51 files is more than a person can review with confidence. Each review round had found new issues, which is good evidence that another round would too. “All checks passed” only measures what the checks measure. What matters at merge time is whether a human can vouch for the diff. For 51 files that are 90% mechanical and 10% judgment, we couldn’t, because the 10% hides in the 90%.
So the sweep became a patch source instead of a merge candidate. We closed it, kept its branch on origin under a stable name, and wrote a plan that split it into 11 slices. Most slices were one to four files. The stats-chart and settings slices ran to eight and twelve. The slices were ordered, and each came with notes for whoever implements it. Two slices change behavior on purpose: the range clamping above, and a rewrite that stops force-unwrapping a nullable timestamp, so a missing time skips a separator instead of crashing. Both are flagged in the plan and must say so in their PR descriptions. Each slice either changes no behavior or says exactly what it changes.
The command that pulls a slice out matters more than it looks:
git diff origin/main...origin/fix/foreach-hoisting -- <this slice's paths>
That takes the latest state of each file from the banked branch, never the original sweep commit alone. The review-fix commits sit on top of the sweep, so the first commit by itself still has the bugs the reviewers caught. And because main keeps moving while slices land one at a time, each slice re-checks its files against fresh main before applying. Each slice PR cites the banked branch and the reviews it already passed, so reviewing a slice is cheap: the reviewer checks that the copy is faithful and the slice stands on its own, and doesn’t re-argue the pattern.
The watch strip went first, pulled out of the slice order because it blocked a release. One file, copied unchanged from the banked branch; we checked the branch history to make sure the review-fix commits never touched it. Its PR states the expectation up front: dragging with a finger improves a lot, but the momentum glide after you let go stays juddery. The deceleration loop updates state from a Task.sleep(16ms) loop, and watchOS has no display link to line those ticks up with the screen refresh, so cheaper frames can’t fix uneven presentation. The teammate who reported the choppiness wrote that expectation down before the hands-on device check. The check decides whether a separate paged-navigation rewrite (also built, also banked) ships or closes.
The widget strips went second: pure hoists in the hourly and minutely widget views, where body cost matters most because widgets render under a time limit. A read-only mini-review returned zero findings and one good nit. With the hoists, an empty data array now evaluates the three getters once instead of zero times. That’s safe, and it’s exactly the kind of edge case a per-slice review can hold in its head.
Since then (as of September 2026). Slice 3 landed the night before this post. The remaining slices (a twelfth was added when an audit of the banked diff found two minutely views unassigned) all landed the next day, each with a read-only mini-review posted to its PR description. We deleted the plan once the last slice merged. The paged-navigation rewrite was closed after a bake-off on real hardware. Instead, we replaced the momentum loop with a single spring retarget, the smallest change we could make on top of shipped code, and the strip shipped after hardware QA on TestFlight builds.
The same audit produced a Phase-2 list that the sweep leaves out on purpose, because these need design work rather than a let:
Calendar constructions and 72 linear scans per strip body evaluation, in every target that shares the row view. The fix is a calendar and a sun-event map computed once by the parent and passed down, which touches shared view APIs.allHoursInDay.map { first(where:) }, a linear search per hour. It needs a dictionary keyed by Date.UserDefaults(suiteName:) and Locale on every string lookup. Every “rebuilds the names dictionary per row” finding in the sweep was this cost times N. The plan flagged it as needing a cache that clears when the language changes, in its own careful PR.Two of the three shipped the afternoon this post went up. The lookup became a Date-keyed dictionary with a contract test. The localization fix skipped cache invalidation entirely: it reads the language setting through a store that’s already shared on every call, and caches only the table from identifier to Locale, which never changes. We parked the calendar chains. A re-check found that the app’s hourly views re-run body about a dozen times per fling, not once per frame, so that cost is about a millisecond, and not often. It now waits for a profile trace or a user report rather than a count of operations from reading the code.
The sweep fixed the call sites, and the audit found the systems behind them. Hoisting removes repeated work at each site. The bigger win is making the expensive thing cheap once, so every call site gets it.
let at the top of the builder is the cache, and it’s refreshed on every body pass.A snapshot test records a piece of output the first time it runs and fails whenever that output changes. The Hello Weather iOS repo had two systems that worked this way, both hand-built for one job. One was a golden-table recorder: it rewrites a committed Swift file with every language x date-format combination. The other compared reports and printed a diff on failure, on a refactor branch. Each one is its own recorder plus its own tests. If we wanted to snapshot something new, a sync payload or a widget timeline, we’d have to build a third.
Our Ruby web repo has had the opposite experience for years. A ~170-line gem (minitest-snapshots) plus a few house conventions produced about 90 committed snapshot files across nine test suites. Most of them cover things nobody would have built a recorder for. When asserting “this output stays exactly like this” takes one line, people snapshot everything worth snapshotting. When it takes a recorder class, a file-naming decision, and a regeneration flag, they write the one snapshot test that’s clearly worth the trouble and skip the rest.
So we designed a port. Not the gem, not a Swift package, and not a dependency on the well-known Swift snapshot-testing library. We wrote one ~100-line helper file in the test target, because everything risky already worked somewhere in the repo and the only missing piece was the convenience layer.
One caveat up front: this post was written as a design record, not a shipping report. The decision and the full design landed as a plans-only PR (iOS #1484, 2026-08-04). We queued the implementation behind a refactor that was already in flight, so it wouldn’t add moving parts to work that was blocking a release. The queue was short. The helper shipped two days later (iOS #1514, 2026-08-06) with its first adopter, and as of 2026-09-01 it holds 111 snapshot files across six suites. The code below is the helper as it landed, which is the plan’s code with two Verify: flags resolved. The decision is still the part you can reuse.
The gem is simple. assert_matches_snapshot value compares the value against test/snapshots/<suite>/<test>__<n>.snap.yaml. The file is created on the first run, and the number goes up with each call inside a test. rails test --update-snapshots overwrites everything. Under ENV["CI"] a missing snapshot is a failure, not a new file, so CI can’t quietly bless one.
Three things fall out of that, and they’re why the tool gets used:
Everything else in the web repo is convention built on top of that. Two of those conventions carry over on their own.
The most common way to misuse snapshot testing is to freeze a raw payload. That gives you a wall of JSON nobody can review, and every diff is noise. The web repo does the opposite. What it snapshots is usually a readable summary, built to be diffed.
The best example is the weather-data adapters. Each adapter’s output is snapshotted as a table that compares it, field by field, against a reference adapter:
+-------------------------------+----------------------+----------------------+
| | Adapter Under Test | Reference |
+-------------------------------+----------------------+----------------------+
| timezone | America/Chicago | America/Chicago |
| currently.temperature | 50.95 | 47.0 |
| currently.icon | cloudy | cloudy |
| currently.humidity | 0.5 | 0.61 |
| currently.windBearing | 120 | 90 |
A reviewer scanning that diff can see whether a parser change moved a field, dropped one, or drifted from the reference. A diff of raw vendor JSON tells you none of that.
The same idea shows up at other layers. SQL behavior is snapshotted as the list of statements the block ran, with numbers replaced by ? and comments stripped. The snapshot captures the shape and count of the queries, not values that change from run to run:
def assert_sql(&block)
sql = []
subscriber = ->(_name, _start, _finish, _id, payload) do
sql << payload[:sql].split("/*").first.gsub(/\d+/, "?")
end
ActiveSupport::Notifications.subscribed(subscriber, "sql.active_record", &block)
assert_matches_snapshot sql.join("\n") + "\n"
end
HTTP concurrency is snapshotted as two numbers: how many requests ran serially and how many in parallel, counted by a spy and saved as a two-key YAML hash. A request counts as serial if it finished on the same fiber as the one before it. A change that accidentally makes a parallel fetch serial fails a test with a two-line diff.
In each case the work goes into the code that builds the summary, and assert_matches_snapshot costs nothing. The split only works because the assertion is cheap.
Because the assertion is one line, generating tests in a loop is cheap. The source smoke suite loops over every active data source and every unit system it supports, and defines a snapshot test for each combination:
Api::Weather::ACTIVE_SOURCES.excluding(REFERENCE_SOURCE).each do |source|
define_method "test_compare_#{source}_to_reference" do
vcr_use_cassette("smoke_test_#{source}_us_forecast") do
table = Api::Table.new(sources: [source, REFERENCE_SOURCE])
assert_matches_snapshot table.pack.to_s
end
end
end
Api::Weather::ACTIVE_SOURCES.each do |source|
Api::Weather.source_class(source).supported_source_units.each do |units|
define_method("test_#{source}_#{units}") do
# ...build the output table for this source + units...
assert_matches_snapshot table.pack.to_s
end
end
end
Adding a new data source adds its comparison test, its per-unit-system output tests, and its request-count tests. The loop picks it up and the first run records the snapshots. Nobody writes tests for a new source. They review what the loop recorded.
Snapshot suites go wrong in two ways over time, and the web repo has a written rule for each:
en keeps passing while every other language regresses. When you snapshot localized content, assert a non-English language too.The obvious move was to adopt the well-known Swift snapshot-testing library. We decided against it. Nothing is wrong with it, but when we audited the repo, every risky mechanic already worked somewhere in-house. The library does a lot we don’t need for text snapshots, like image strategies and a trait system. It would also have been the first package ever linked into the test target, and one more entry in the monthly dependency-update cycle. If we ever want image or SwiftUI-view snapshots, the library’s core module is the upgrade path.
The audit is the part to copy, because “can our simulator tests even do this?” is the question that usually pushes a team toward a dependency. Three mechanics, and three places they were already proven:
URL(fileURLWithPath: #filePath) and rewrites a committed Swift file in place, from a simulator test hosted in the app. The simulator shares the Mac’s filesystem, so #filePath in a test file is a real, writable path into the repo.xcodebuild doesn’t forward arbitrary environment variables to tests. It forwards only the ones prefixed TEST_RUNNER_, and strips the prefix. The repo’s bin/unit-test already passes the golden-record flag through this way.Issue.record, named the file, and gave the regenerate command. We lifted it.With all three proven, the only thing missing was the convenience layer, which is ~100 lines. We ported the three things that make the tool get used instead of importing a library for mechanics we already had.
The new names match the Ruby ones: --update-snapshots for the flag, UPDATE_SNAPSHOTS for the env var, assertMatchesSnapshot for the helper, and a snapshots/ directory like the web repo’s test/snapshots/. The repo’s existing env flags carry an app-specific prefix, and we decided not to put that prefix on the new names just to match. When two codebases share a convention, a person or an agent moving between them should find the same words.
The whole helper is one file in the test target. Here it is as it landed, lightly trimmed:
import Testing
import Foundation
enum Snapshots {
static let directory = URL(fileURLWithPath: #filePath)
.deletingLastPathComponent()
.appendingPathComponent("snapshots")
nonisolated(unsafe) static var environment = ProcessInfo.processInfo.environment
static var updating: Bool {
environment["UPDATE_SNAPSHOTS"] == "1"
}
static var locked: Bool {
environment["CI"] != nil
}
private static let lock = NSLock()
nonisolated(unsafe) private static var counters: [String: Int] = [:]
static func nextIndex(forKey key: String) -> Int {
lock.lock()
defer { lock.unlock() }
let next = (counters[key] ?? 0) + 1
counters[key] = next
return next
}
// Ruby-style snake_case: "DateFormatSnapshotTests" -> "date_format_snapshot_tests"
static func sanitized(_ component: String) -> String {
component
.replacingOccurrences(of: "([a-z0-9])([A-Z])", with: "$1_$2", options: .regularExpression)
.replacingOccurrences(of: "([A-Z])([A-Z][a-z])", with: "$1_$2", options: .regularExpression)
.lowercased()
.replacingOccurrences(of: "[^a-z0-9]+", with: "_", options: .regularExpression)
.trimmingCharacters(in: CharacterSet(charactersIn: "_"))
}
static func firstDifferences(recorded: String, current: String) -> String {
let recordedLines = recorded.components(separatedBy: "\n")
let currentLines = current.components(separatedBy: "\n")
var differences: [String] = []
for index in 0..<max(recordedLines.count, currentLines.count) where differences.count < 8 {
let recordedLine = index < recordedLines.count ? recordedLines[index] : "<missing>"
let currentLine = index < currentLines.count ? currentLines[index] : "<missing>"
if recordedLine != currentLine {
differences.append("line \(index + 1):\n recorded: \(recordedLine)\n current: \(currentLine)")
}
}
return differences.joined(separator: "\n")
}
}
// Parameterized tests (@Test(arguments:)) share one function name — pass named:.
func assertMatchesSnapshot(
_ value: String,
named name: String? = nil,
filePath: String = #filePath,
function: String = #function,
sourceLocation: SourceLocation = #_sourceLocation
) {
let suite = Snapshots.sanitized(URL(fileURLWithPath: filePath).deletingPathExtension().lastPathComponent)
let test = Snapshots.sanitized(function.replacingOccurrences(of: "()", with: ""))
let suffix = name.map(Snapshots.sanitized) ?? String(Snapshots.nextIndex(forKey: "\(suite)/\(test)"))
let snapshotURL = Snapshots.directory
.appendingPathComponent(suite)
.appendingPathComponent("\(test)__\(suffix).snap.txt")
let relativePath = "Tests/snapshots/\(suite)/\(test)__\(suffix).snap.txt"
if !Snapshots.updating, let recorded = try? String(contentsOf: snapshotURL, encoding: .utf8) {
if recorded == value { return }
Issue.record(
"output drifted from \(relativePath) — regenerate with bin/unit-test --update-snapshots, then review every changed line. First differences:\n\(Snapshots.firstDifferences(recorded: recorded, current: value))",
sourceLocation: sourceLocation
)
return
}
guard !Snapshots.locked else {
Issue.record(
"snapshot \(relativePath) is missing or an update was requested, but snapshots are locked under CI — record locally and commit the file",
sourceLocation: sourceLocation
)
return
}
do {
try FileManager.default.createDirectory(at: snapshotURL.deletingLastPathComponent(), withIntermediateDirectories: true)
try value.write(to: snapshotURL, atomically: true, encoding: .utf8)
} catch {
Issue.record("failed to write snapshot \(relativePath): \(error)", sourceLocation: sourceLocation)
}
}
The line to notice is the guard !Snapshots.locked after the comparison. Under CI, a missing file and an explicit update both fail instead of writing, which is the same lock the gem calls lock_snapshots. The environment variable is there so the helper’s own tests can exercise the lock without a real CI variable. Values are plain strings in .snap.txt files rather than the gem’s .snap.yaml, because we chose not to port the YAML serializer. Callers turn their value into a string first, and overloads for structured values can wait until someone needs one.
The flag side is a few lines in the existing test runner script, using the same TEST_RUNNER_ mechanism the golden recorder already used:
# Snapshot update mode: bin/unit-test --update-snapshots (or UPDATE_SNAPSHOTS=1)
# rewrites every snapshot the run touches (Snapshots.swift); review the
# Tests/snapshots/ diff before committing. CI is forwarded so the
# helper can lock snapshots (missing files fail instead of auto-recording).
for arg in "$@"; do
if [ "$arg" = "--update-snapshots" ]; then
UPDATE_SNAPSHOTS=1
fi
done
if [ "$UPDATE_SNAPSHOTS" = "1" ]; then
export TEST_RUNNER_UPDATE_SNAPSHOTS=1
echo "Updating snapshots (review the Tests/snapshots/ diff)"
fi
if [ -n "$CI" ]; then
export TEST_RUNNER_CI="$CI"
fi
The last block isn’t optional. GitHub Actions sets CI in the runner shell, but only TEST_RUNNER_-prefixed variables cross into the test process, so plain CI never arrives unless the script forwards it. Miss that and the lock never turns on, and nothing tells you.
A port isn’t a word-for-word copy. Swift Testing changes three details:
__N counter has to be a dictionary keyed by suite and test, with a lock around it. Calls inside one test still run in order, so the numbering is stable per test. The lock only protects the dictionary from two tests touching it at once.@Test(arguments:) runs one function many times, and every run has the same #function string. Auto-numbering across those runs would depend on which one ran first. So parameterized tests have to pass an explicit named: argument. That’s a rule written on the helper, not something the helper enforces at runtime.sourceLocation: SourceLocation = #_sourceLocation default argument makes a failure point at the caller’s line instead of the helper’s. It’s the documented pattern for custom assertion helpers. The plan marked it Verify: against the toolchain’s Swift Testing version, and it compiled as written when the helper landed. A design record should say what it isn’t sure of. An agent that hit a compile error on that line would find the plan had already warned about it.The plan said the golden-table system would stay. Its value was that the compiler checked coverage: the table was generated Swift covering allCases of language x format intent, so a newly added case couldn’t go missing without a compile error. The plan recorded keeping it as a decision, not an oversight, and left the golden’s future as an open question. The landing PR answered it the other way. The date matrix became the helper’s first adopter, rendered from the same allCases loops into one snapshot file per language (27 files, the same bytes the golden had asserted). The golden recorder, its generated file, and its flag were deleted. Coverage now comes from the loops in the test plus exhaustive switches in the date-format contract tests. The plan’s other targets are still the helper’s to-do list: sync payload shapes, widget timeline dumps, notification content, and turning a couple of standalone validator tools into report-generating tests that run behind an env flag. The report-generating tests are the part that has happened.
xcodebuild, a readable failure message: all three were already proven in-repo. The library would only have added convenience, which is the cheap part.xcodebuild the CI variable doesn’t reach the test process unless the script forwards it as TEST_RUNNER_CI. A lock that never turns on looks the same as one that works.Verify: flags resolved.