buildanything 1.7.1 → 2.0.0

package/skills/ios/swift-testing-expert/references/parallelization-and-isolation.md

@@ -0,0 +1,95 @@
+# Parallelization and Isolation
+
+## When to use this reference
+
+Use this file when tests are flaky in CI, have hidden ordering dependencies, or need to scale execution speed safely.
+
+## Default execution model
+
+- Swift Testing runs test functions in parallel by default.
+- Execution order is randomized to expose hidden test dependencies.
+- Parallelization applies to synchronous and asynchronous tests.
+
+## Example: hidden dependency exposed by parallel execution
+
+```swift
+import Testing
+
+enum SharedStore {
+ static var counter = 0
+}
+
+@Test func incrementsCounter() {
+ SharedStore.counter += 1
+ #expect(SharedStore.counter >= 1)
+}
+
+@Test func expectsFreshCounter() {
+ // Flaky if tests run in parallel or random order.
+ #expect(SharedStore.counter == 0)
+}
+```
+
+## Why this matters
+
+- Faster CI feedback and shorter local iteration loops.
+- Better detection of shared-state coupling and flaky behavior.
+- More realistic stress on concurrency-sensitive code paths.
+
+## Isolation strategy first
+
+- Make tests independent by default.
+- Avoid shared mutable globals and singleton mutation across tests.
+- Isolate state per test invocation (fresh suite instance helps).
+- Prefer deterministic test data setup over implicit ordering assumptions.
+
+### Better pattern: isolate per test
+
+```swift
+import Testing
+
+struct CounterStore {
+ var counter = 0
+ mutating func increment() { counter += 1 }
+}
+
+@Test func isolatedCounter() {
+ var store = CounterStore()
+ store.increment()
+ #expect(store.counter == 1)
+}
+```
+
+## `.serialized` as a targeted tool
+
+- Apply `.serialized` to suites when tests must run one-at-a-time.
+- Use it as a transitional safety measure during migration from serial XCTest suites.
+- Refactor toward parallel-safe tests before normalizing serialization everywhere.
+- Serialized suites can still run alongside unrelated suites in parallel.
+
+### Transitional serialization example
+
+```swift
+import Testing
+
+@Suite(.serialized)
+struct LegacyDatabaseTests {
+ @Test func migrationStepA() { #expect(true) }
+ @Test func migrationStepB() { #expect(true) }
+}
+```
+
+## Shared resource scenarios
+
+- If tests hit a shared DB/file/service, choose one:
+  - isolate backing state per test
+  - use in-memory substitutes
+  - create separate serial test plan for integration path
+- Prefer architecture that supports both fast in-memory tests and selective real integration tests.
+
+## Do / Don't
+
+- Do fix shared-state coupling before adding broad serialization.
+- Do use in-memory fakes for the fast path.
+- Don't rely on execution order.
+- Don't mutate singletons across tests without reset/isolation.

package/skills/ios/swift-testing-expert/references/parameterized-testing.md

@@ -0,0 +1,284 @@
+# Parameterized Testing
+
+## When to use this reference
+
+Use this file when you have repeated tests with identical logic and only input changes.
+
+## When to parameterize
+
+- Use one parameterized test when behavior is identical and only input changes.
+- Replace copy-pasted tests and in-test `for` loops with `@Test(arguments: ...)`.
+- Keep one responsibility per parameterized test to preserve clarity.
+
+### Before -> after
+
+```swift
+// Before: multiple near-duplicate tests.
+// @Test func freeFeatureA() { ... }
+// @Test func freeFeatureB() { ... }
+
+import Testing
+
+enum Feature: CaseIterable {
+ case recording, darkMode, networkMonitor
+ var isPremium: Bool { self == .networkMonitor }
+}
+
+@Test("Free features are not premium", arguments: [Feature.recording, .darkMode])
+func freeFeatures(_ feature: Feature) {
+ #expect(feature.isPremium == false)
+}
+```
+
+## Single input collection
+
+- Pass any sendable collection (arrays, ranges, dictionaries, etc.) as arguments.
+- Each argument becomes its own independent test case with separate diagnostics.
+- Individual failing arguments can be rerun without rerunning all inputs.
+
+### Range-based arguments example
+
+```swift
+import Testing
+
+func isValidAge(_ value: Int) -> Bool { (18...120).contains(value) }
+
+@Test(arguments: 18...21)
+func validAges(_ age: Int) {
+ #expect(isValidAge(age))
+}
+```
+
+## Multiple inputs
+
+- Swift Testing supports up to two argument collections directly.
+- Two collections generate all combinations (cartesian product).
+- Control explosion by:
+  - reducing argument sets
+  - splitting tests by concern
+  - pairing related values via `zip(...)`
+
+### Cartesian product example
+
+```swift
+import Testing
+
+enum Region { case eu, us }
+enum Plan { case free, pro }
+
+func canUseVATInvoice(region: Region, plan: Plan) -> Bool {
+ region == .eu && plan == .pro
+}
+
+@Test(arguments: [Region.eu, .us], [Plan.free, .pro])
+func vatInvoiceAccess(region: Region, plan: Plan) {
+ let allowed = canUseVATInvoice(region: region, plan: plan)
+ #expect((region == .eu && plan == .pro) == allowed)
+}
+```
+
+## `zip` for paired scenarios
+
+- Use `zip` when input A must pair with a corresponding input B.
+- Prefer `zip` over full combinations when you need aligned tuples only.
+- Keep tuples readable and intentional.
+
+### `zip` example
+
+```swift
+import Testing
+
+enum Tier { case basic, premium }
+func freeTries(for tier: Tier) -> Int { tier == .basic ? 3 : 10 }
+
+@Test(arguments: zip([Tier.basic, .premium], [3, 10]))
+func freeTryLimits(_ tier: Tier, expected: Int) {
+ #expect(freeTries(for: tier) == expected)
+}
+```
+
+### `zip` pitfalls to avoid
+
+**Silent truncation**: `zip` stops at the shorter collection. If the two arrays differ in length, the extra elements are silently dropped — no compiler error, no test failure, just missing coverage.
+
+```swift
+// ❌ Silent gap: the fifth input is never tested
+@Test(arguments: zip(
+  [Status.active, .inactive, .pending, .banned, .suspended],
+  ["Active", "Inactive", "Pending", "Banned"]  // one short
+))
+func statusLabel(_ status: Status, expected: String) {
+ #expect(label(for: status) == expected)
+}
+```
+
+**Case-order fragility with `CaseIterable`**: pairing two `allCases` arrays with `zip` breaks silently if enum cases are ever reordered (e.g., by alphabetizing).
+
+```swift
+// ❌ Fragile: reordering either enum misaligns all pairs
+enum Ingredient: CaseIterable { case rice, potato, egg }
+enum Dish: CaseIterable { case onigiri, fries, omelette }
+
+@Test(arguments: zip(Ingredient.allCases, Dish.allCases))
+func cook(_ ingredient: Ingredient, into dish: Dish) {
+ #expect(cook(ingredient) == dish)
+}
+```
+
+Prefer explicit array literals or one of the alternatives below.
+
+## Paired input alternatives
+
+When inputs and expected outputs must be paired, prefer these over `zip` to avoid the silent-truncation and case-ordering problems.
+
+### Array of tuples (recommended)
+
+Pairs are co-located and impossible to misalign. Adding a new case forces a matching output to be written at the same time.
+
+```swift
+import Testing
+
+@Test(arguments: [
+ (Ingredient.rice, Dish.onigiri),
+ (.potato, .fries),
+ (.egg, .omelette)
+])
+func cook(_ ingredient: Ingredient, into dish: Dish) {
+ #expect(cook(ingredient) == dish)
+}
+```
+
+### Dictionary arguments
+
+Expresses a clear mapping; each entry is self-documenting. Requires `Hashable` keys.
+
+```swift
+import Testing
+
+@Test(arguments: [
+ Ingredient.rice: Dish.onigiri,
+ .potato: .fries,
+ .egg: .omelette
+])
+func cook(_ ingredient: Ingredient, into dish: Dish) {
+ #expect(cook(ingredient) == dish)
+}
+```
+
+### Fixed-size `zip` with `InlineArray` (Swift 6.2+)
+
+A custom `zip` overload for `InlineArray` enforces equal-length arrays at compile time via a generic length parameter. This is not part of the standard library — you must define the helper yourself.
+
+```swift
+import Testing
+
+// Custom helper: `zip` for two `InlineArray` values of the same length.
+func zip<let N: Int, A, B>(
+  _ a: InlineArray<N, A>,
+  _ b: InlineArray<N, B>
+) -> Zip2Sequence<[A], [B]> {
+  zip(Array(a), Array(b))
+}
+
+// ✅ Compile error if lengths differ — enforced at compile time
+@Test(arguments: zip(
+  InlineArray<2, Ingredient>(.rice, .potato),
+  InlineArray<2, Dish>(.onigiri, .curry)
+))
+func cook(_ ingredient: Ingredient, into dish: Dish) {
+  #expect(cook(ingredient) == dish)
+}
+```
+
+## Naming and output quality
+
+- Use meaningful parameter labels and display names.
+- Ensure argument types are readable in output; provide custom test description if noisy.
+- Keep argument lists easy to scan (multi-line formatting is recommended).
+
+## When `CaseIterable.allCases` is appropriate
+
+Using `allCases` as arguments is a valid pattern for **property-based tests** — tests that verify a universal property holds for every member of a type. The key distinction: the expected result is derived from the *property being tested*, not from a hard-coded mapping.
+
+```swift
+import Testing
+
+// ✅ Valid: verifying a mathematical property holds for all orientations.
+@Test(
+  "Rotating clockwise four times returns to the original orientation",
+  arguments: Orientation.allCases
+)
+func fullRotation(orientation: Orientation) {
+ #expect(
+  orientation
+   .rotated(.clockwise)
+   .rotated(.clockwise)
+   .rotated(.clockwise)
+   .rotated(.clockwise)
+  == orientation
+ )
+}
+```
+
+Avoid `allCases` when you need concrete, case-specific expected values — use explicit arrays or tuples instead.
+
+## Common pitfalls
+
+- **Derived expected values masking bugs**: when the expected value is derived from the same input expression as the system under test, both sides shift together and bugs pass silently. Use concrete literals in `#expect` for case-specific expectations.
+
+```swift
+// ❌ Masking: if format(day) returns "monday" instead of "Monday",
+//    this test still passes because rawValue has the same casing bug.
+@Test(arguments: Day.allCases)
+func dayLabel(day: Day) {
+ #expect(format(day) == day.rawValue)
+}
+
+// ✅ Concrete: each expectation is an independent data point.
+@Test(arguments: [
+ (Day.monday, "Monday"),
+ (.friday, "Friday")
+])
+func dayLabel(day: Day, expected: String) {
+ #expect(format(day) == expected)
+}
+```
+
+- **Control flow in test bodies**: `if`/`switch` inside a parameterized test body mirrors implementation logic. Tests that branch the same way as production code verify themselves rather than the behavior independently.
+
+```swift
+// ❌ Mirrors implementation — not independent verification.
+@Test(arguments: Day.allCases)
+func greeting(day: Day) {
+ if day == .friday {
+  #expect(greet(day) == "TGIF!")
+ } else {
+  #expect(greet(day) == "Hello, \(day)!")
+ }
+}
+
+// ✅ Separate the special case into its own test.
+@Test func fridayGreeting() {
+ #expect(greet(.friday) == "TGIF!")
+}
+
+@Test(arguments: [Day.monday, .tuesday, .wednesday, .thursday, .saturday, .sunday])
+func standardGreeting(day: Day) {
+ #expect(greet(day) == "Hello, \(day)!")
+}
+```
+
+- **Using in-test `for` loops instead of parameterized arguments** (worse diagnostics).
+- **Passing huge argument sets that explode combinations** and slow CI.
+- **Mixing multiple concerns into one parameterized function**.
+- **Extracting argument arrays into separate properties or extensions**: this hides what the test covers and forces readers to jump between definitions. Keep arguments inline unless the list is genuinely reused across multiple test functions.
+
+## Review checklist
+
+- Repetitive tests are consolidated into one parameterized test.
+- Arguments reflect domain vocabulary and produce readable failures.
+- Paired inputs are modeled as arrays of tuples or dictionaries; use `zip` with equal-length explicit arrays only when the inputs must remain as separate collections.
+- Paired inputs use tuples or dictionaries rather than `zip(allCases, allCases)`.
+- `#expect` uses concrete literal expectations, not values derived from the input itself.
+- No `if`/`switch` branching inside parameterized test bodies.
+- `CaseIterable.allCases` is only used for property-based assertions, not example-based mappings.

package/skills/ios/swift-testing-expert/references/performance-and-best-practices.md

@@ -0,0 +1,187 @@
+# Performance and Best Practices
+
+## When to use this reference
+
+Use this file when test runs are slow, flaky, or not scaling in CI, and when you need practical patterns for fast, deterministic Swift Testing suites.
+
+## Core principles
+
+- Prefer deterministic tests over timing-sensitive tests.
+- Prefer synchronous verification when asynchronous waiting is not required.
+- Keep tests independent so parallel execution remains safe and effective.
+- Treat `.serialized` as a temporary compromise, not a default architecture.
+
+## 1) Keep tests synchronous where possible
+
+Synchronous tests generally run faster and are easier to reason about.
+
+```swift
+import Testing
+
+struct PriceCalculator {
+ static func total(_ subtotal: Int, discount: Int) -> Int { subtotal - discount }
+}
+
+@Test func totalCalculation() {
+ #expect(PriceCalculator.total(100, discount: 20) == 80)
+}
+```
+
+Avoid introducing `async` or sleeps for purely synchronous logic.
+
+```swift
+// Avoid:
+// @Test func totalCalculation() async {
+//   try await Task.sleep(nanoseconds: 100_000_000)
+//   #expect(...)
+// }
+```
+
+## 2) Avoid unnecessary main-actor isolation
+
+`@MainActor` can reduce useful parallelization and should be used only when code truly needs main-thread isolation.
+
+```swift
+import Testing
+
+// Good: non-UI logic stays non-main-actor.
+@Test func parserIsStable() {
+ #expect("A,B,C".split(separator: ",").count == 3)
+}
+
+// Use @MainActor only for UI/main-thread sensitive code.
+@MainActor
+@Test func viewModelMutation() {
+ #expect(true)
+}
+```
+
+## 3) Remove shared mutable state
+
+Shared mutable state is a major source of flakiness and parallel failures.
+
+```swift
+import Testing
+
+enum Globals {
+ static var token: String?
+}
+
+// Flaky pattern:
+@Test func writeToken() {
+ Globals.token = "abc"
+ #expect(Globals.token == "abc")
+}
+
+@Test func expectsNoToken() {
+ #expect(Globals.token == nil)
+}
+```
+
+Better: create isolated state per test.
+
+```swift
+import Testing
+
+struct SessionState {
+ var token: String?
+}
+
+@Test func isolatedTokenState() {
+ var state = SessionState()
+ state.token = "abc"
+ #expect(state.token == "abc")
+}
+```
+
+## 4) Prefer in-memory dependencies for the fast path
+
+Use fakes/in-memory repositories for high-volume test runs; reserve real integration dependencies for dedicated plans.
+
+```swift
+import Testing
+
+protocol CacheStore {
+ func put(key: String, value: String)
+ func get(key: String) -> String?
+}
+
+final class InMemoryCacheStore: CacheStore {
+ private var values: [String: String] = [:]
+ func put(key: String, value: String) { values[key] = value }
+ func get(key: String) -> String? { values[key] }
+}
+
+@Test func cacheRoundTrip() {
+ let cache = InMemoryCacheStore()
+ cache.put(key: "user", value: "42")
+ #expect(cache.get(key: "user") == "42")
+}
+```
+
+## 5) Use parameterized tests to reduce overhead and improve diagnostics
+
+```swift
+import Testing
+
+func isValidPort(_ value: Int) -> Bool { (1...65535).contains(value) }
+
+@Test(arguments: [1, 80, 443, 65535])
+func validPorts(_ port: Int) {
+ #expect(isValidPort(port))
+}
+```
+
+This reduces duplicated setup code and gives argument-level failure visibility.
+
+## 6) Keep setup cheap and scoped
+
+- Build expensive fixtures only when needed.
+- Prefer per-suite immutable setup for shared readonly data.
+- Avoid network/file-system setup in unit tests unless behavior depends on it.
+
+```swift
+import Testing
+
+struct CurrencyTests {
+ let rates: [String: Double]
+
+ init() {
+ rates = ["USD": 1.0, "EUR": 0.92]
+ }
+
+ @Test func hasEURRate() {
+ #expect(rates["EUR"] != nil)
+ }
+}
+```
+
+## 7) Use `.serialized` narrowly
+
+```swift
+import Testing
+
+@Suite(.serialized)
+struct TemporarySerialDBTests {
+ @Test func migrationA() async throws { #expect(true) }
+ @Test func migrationB() async throws { #expect(true) }
+}
+```
+
+Add TODO context and remove once dependencies are isolated.
+
+## 8) Flakiness reduction checklist
+
+- No reliance on execution order.
+- No shared mutable globals/singletons without reset.
+- No arbitrary sleeps as synchronization.
+- No hidden external dependencies in unit tests.
+- Deterministic fixtures and stable clocks/random sources.
+- Explicit known-issue wrappers for temporary failures.
+
+## Quick do / don't
+
+- Do optimize for determinism first, then speed.
+- Do keep most tests parallel-safe and dependency-light.
+- Don't treat test slowness as only a hardware problem.
+- Don't move everything to `@MainActor` or `.serialized` to silence flakiness.

package/skills/ios/swift-testing-expert/references/traits-and-tags.md

@@ -0,0 +1,114 @@
+# Traits and Tags
+
+## When to use this reference
+
+Use this file when controlling test execution behavior, linking bug context, and organizing large test suites for targeted runs and CI filtering.
+
+## Trait categories
+
+- **Informational**: display names, bug links, tags.
+- **Conditional**: `.enabled(if:)`, `.disabled(...)`, availability attributes.
+- **Behavioral**: `.timeLimit(...)`, `.serialized`.
+
+## Basic trait examples
+
+```swift
+import Testing
+
+@Test("Uploads complete quickly", .timeLimit(.seconds(10)))
+func uploadWithinTimeLimit() async throws {
+ #expect(true)
+}
+
+@Test(.disabled("Flaky on CI while investigating issue"), .bug("https://example.com/issues/12"))
+func temporaryDisabledTest() {
+ #expect(true)
+}
+```
+
+## Conditions and disabling
+
+- Use `.enabled(if:)` or `.disabled(if:)` for runtime-evaluated environments.
+- Use `.disabled("reason")` instead of commenting tests out.
+- Include actionable reason text in disabled traits for CI/test reports.
+- Add `.bug(...)` to link issue trackers and aid future cleanup.
+
+### Runtime condition example
+
+```swift
+import Testing
+
+enum Runtime {
+ static let isCI = ProcessInfo.processInfo.environment["CI"] == "true"
+}
+
+@Test(.enabled(if: Runtime.isCI))
+func ciOnlySmokeTest() {
+ #expect(true)
+}
+```
+
+## Availability
+
+- Use `@available` on tests when entire behavior is OS-gated.
+- Prefer `@available` over inline runtime checks for clearer reporting semantics.
+
+```swift
+import Testing
+
+@available(iOS 18, *)
+@Test func modernPushPayload() {
+ #expect(true)
+}
+```
+
+## Tags
+
+- Declare custom tags and apply to tests/suites for cross-suite grouping.
+- Use tags for test-plan include/exclude, navigator filtering, and failure analytics.
+- Treat tags as cross-cutting metadata, not a replacement for suite structure.
+- Use meaningful domain labels (e.g. `networking`, `regression`, `spicy`) over vague terms.
+
+### Defining and applying tags
+
+```swift
+import Testing
+
+extension Tag {
+ @Tag static var networking: Self
+ @Tag static var regression: Self
+}
+
+@Suite(.tags(.networking))
+struct APITests {
+ @Test func fetchUser() async throws {
+ #expect(true)
+ }
+}
+
+struct CheckoutTests {
+ @Test(.tags(.regression))
+ func orderTotal() {
+ #expect(3 * 3 == 9)
+ }
+}
+```
+
+## Inheritance and scope
+
+- Traits and tags on suites cascade to contained tests.
+- Apply at suite level when broadly true; apply per test when specific.
+- Keep trait intent explicit to avoid accidental broad behavior changes.
+
+## Do / Don't
+
+- Do put shared tags at suite level for consistency.
+- Do attach bug links for temporary disables or known failures.
+- Don't use tags as a replacement for meaningful suite grouping.
+- Don't overuse `.serialized` as a blanket reliability fix.
+
+## Review checklist
+
+- Every disabled test has a reason (and ideally a bug link).
+- Tags reflect domain concerns and are reused consistently.
+- Availability and condition traits are applied to the smallest correct scope.