buildanything 1.7.1 → 2.0.0

package/skills/ios/swift-testing-expert/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antoine van der Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/ios/swift-testing-expert/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: swift-testing-expert
+description: 'Expert guidance for Swift Testing: test structure, #expect/#require macros, traits and tags, parameterized tests, test plans, parallel execution, async waiting patterns, and XCTest migration. Use when writing new Swift tests, modernizing XCTest suites, debugging flaky tests, or improving test quality and maintainability in Apple-platform or Swift server projects.'
+---
+
+# Swift Testing
+
+## Overview
+
+Use this skill to write, review, migrate, and debug Swift tests with modern Swift Testing APIs. Prioritize readable tests, robust parallel execution, clear diagnostics, and incremental migration from XCTest where needed.
+
+## Agent behavior contract (follow these rules)
+
+1. Prefer Swift Testing for Swift unit and integration tests, but keep XCTest for UI automation (`XCUIApplication`), performance metrics (`XCTMetric`), and Objective-C-only test code.
+2. Treat `#expect` as the default assertion and use `#require` when subsequent lines depend on a prerequisite value.
+3. Default to parallel-safe guidance. If tests are not isolated, first propose fixing shared state before applying `.serialized`.
+4. Prefer traits for behavior and metadata (`.enabled`, `.disabled`, `.timeLimit`, `.bug`, tags) over naming conventions or ad-hoc comments.
+5. Recommend parameterized tests when multiple tests share logic and differ only in input values.
+6. Use `@available` on test functions for OS-gated behavior instead of runtime `#available` checks inside test bodies; never annotate suite types with `@available`.
+7. Keep migration advice incremental: convert assertions first, then organize suites, then introduce parameterization/traits.
+8. Only import `Testing` in test targets, never in app/library/binary targets.
+
+## First 60 seconds (triage template)
+
+- Clarify the goal: new tests, migration, flaky failures, performance, CI filtering, or async waiting.
+- Collect minimal facts:
+  - Xcode/Swift version and platform targets
+  - Whether tests currently use XCTest, Swift Testing, or both
+  - Whether failures are deterministic or flaky
+  - Whether tests access shared resources (database, files, network, global state)
+- Branch quickly:
+  - repetitive tests -> parameterized tests
+  - noisy or flaky failures -> known issue handling and test isolation
+  - migration questions -> XCTest mapping and coexistence strategy
+  - async callback complexity -> continuation/await patterns
+
+## Routing map (read the right reference fast)
+
+- Test building blocks and suite organization -> `references/fundamentals.md`
+- `#expect`, `#require`, and throw expectations -> `references/expectations.md`
+- Traits, tags, and Xcode test-plan filtering -> `references/traits-and-tags.md`
+- Parameterized test design and combinatorics -> `references/parameterized-testing.md`
+- Default parallel execution, `.serialized`, isolation strategy -> `references/parallelization-and-isolation.md`
+- Test speed, determinism, and flakiness prevention -> `references/performance-and-best-practices.md`
+- Async waiting and callback bridging -> `references/async-testing-and-waiting.md`
+- XCTest coexistence and migration workflow -> `references/migration-from-xctest.md`
+- Test navigator/report workflows and diagnostics -> `references/xcode-workflows.md`
+- Index and quick navigation -> `references/_index.md`
+
+## Common pitfalls -> next best move
+
+- Repetitive `testFooCaseA/testFooCaseB/...` methods -> replace with one parameterized `@Test(arguments:)`.
+- Failing optional preconditions hidden in later assertions -> `try #require(...)` then assert on unwrapped value.
+- Flaky integration tests on shared database -> isolate dependencies or in-memory repositories; use `.serialized` only as a transition step.
+- Disabled tests that silently rot -> prefer `withKnownIssue` for temporary known failures to preserve signal.
+- Unclear failure values for complex types -> conform type to `CustomTestStringConvertible` for focused test diagnostics.
+- Test-plan include/exclude by names -> use tags and tag-based filters instead.
+
+## Verification checklist
+
+- Confirm each test has a single clear behavior and expressive display name when needed.
+- Confirm prerequisites use `#require` where failure should stop the test.
+- Confirm repeated logic is parameterized instead of duplicated.
+- Confirm tests are parallel-safe or intentionally serialized with rationale.
+- Confirm async code is awaited and callback APIs are bridged safely.
+- Confirm migration keeps unsupported XCTest-only scenarios on XCTest.
+
+## References
+
+- `references/_index.md`
+- `references/fundamentals.md`
+- `references/expectations.md`
+- `references/traits-and-tags.md`
+- `references/parameterized-testing.md`
+- `references/parallelization-and-isolation.md`
+- `references/performance-and-best-practices.md`
+- `references/async-testing-and-waiting.md`
+- `references/migration-from-xctest.md`
+- `references/xcode-workflows.md`

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

@@ -0,0 +1,12 @@
+# Swift Testing Reference Index
+
+- `fundamentals.md` - `@Test`, suites, structure, naming, and baseline patterns
+- `expectations.md` - `#expect`, `#require`, throw validation, and failure readability
+- `traits-and-tags.md` - traits, tags, bug linking, conditions, and test-plan filtering
+- `parameterized-testing.md` - single/multi-argument parameterization, `zip`, and scaling strategy
+- `parallelization-and-isolation.md` - default parallel execution, random order, `.serialized`, and isolation patterns
+- `performance-and-best-practices.md` - test speed, determinism, flaky-test prevention, and parallel-safe defaults
+- `async-testing-and-waiting.md` - async/await in tests, callback bridging, and event-stream verification
+- `migration-from-xctest.md` - pragmatic XCTest -> Swift Testing migration workflow
+- `xcode-workflows.md` - navigator/report workflows, insights, and diagnostics quality
+- `README.md` resources section - Apple documentation links for defining, organizing, and migrating tests

package/skills/ios/swift-testing-expert/references/async-testing-and-waiting.md

@@ -0,0 +1,127 @@
+# Async Testing and Waiting
+
+## When to use this reference
+
+Use this file when tests involve async/await functions, completion handlers, streams/events, or timing-related flakiness.
+
+## Preferred approach
+
+- Use async test functions and `await` naturally.
+- Keep async test code close to production async patterns.
+- Prefer structured concurrency patterns over ad-hoc synchronization.
+- Prefer confirmations for async event-style tests that are not naturally awaitable.
+
+### Async function test example
+
+```swift
+import Testing
+
+struct APIClient {
+ func fetchName() async throws -> String { "Antoine" }
+}
+
+@Test func fetchNameReturnsValue() async throws {
+ let client = APIClient()
+ let value = try await client.fetchName()
+ #expect(value == "Antoine")
+}
+```
+
+## Callback bridging
+
+- For completion-handler APIs without async overloads, bridge with:
+  - `withCheckedContinuation`
+  - `withCheckedThrowingContinuation`
+- Keep continuation wrappers minimal and test-focused.
+
+### Completion-handler to async bridge
+
+```swift
+import Testing
+
+func legacyLoad(_ completion: @escaping (Result<Int, Error>) -> Void) {
+ completion(.success(42))
+}
+
+@Test func legacyAPI() async throws {
+ let value = try await withCheckedThrowingContinuation { continuation in
+ legacyLoad { result in
+ continuation.resume(with: result)
+ }
+ }
+ #expect(value == 42)
+}
+```
+
+## Confirmations for asynchronous events
+
+- Use confirmations when validating event delivery/count semantics that do not map cleanly to direct `await`.
+- Set expected counts explicitly:
+  - exact count for strict validation
+  - lower-bounded range for at-least semantics
+- Keep confirmation scope small and ensure confirmations happen before the confirmation block returns.
+
+### Confirmation example
+
+```swift
+import Testing
+
+@Test func eventIsPublishedTwice() async {
+ await confirmation("Publishes two events", expectedCount: 2) { confirm in
+ confirm()
+ confirm()
+ }
+}
+```
+
+## Event handlers and multi-fire callbacks
+
+- Avoid unsafe mutable shared counters from callback closures in strict concurrency mode.
+- Use isolation-safe patterns (actor state, AsyncSequence wrappers, or thread-safe containers).
+- Verify callback counts and ordering explicitly when behavior depends on it.
+
+### Actor-isolated counting pattern
+
+```swift
+import Testing
+
+actor EventCounter {
+ private(set) var count = 0
+ func increment() { count += 1 }
+}
+
+@Test func countEventsSafely() async {
+ let counter = EventCounter()
+ await counter.increment()
+ await counter.increment()
+ #expect(await counter.count == 2)
+}
+```
+
+## Avoid legacy waiting anti-patterns
+
+- Do not return from test before async callback work completes.
+- Avoid sleeping/time-based waits as primary synchronization.
+- Replace brittle waiting with awaitable conditions and deterministic synchronization points.
+
+```swift
+// Avoid this pattern:
+// try await Task.sleep(nanoseconds: 500_000_000)
+// #expect(flag == true)
+```
+
+## Actor isolation in tests
+
+- Isolate tests to a global actor (e.g. `@MainActor`) only when behavior truly requires it.
+- Keep non-UI tests off main actor to preserve realistic concurrency behavior.
+
+### Main-actor test only when required
+
+```swift
+import Testing
+
+@MainActor
+@Test func uiModelMutation() {
+ #expect(true)
+}
+```

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

@@ -0,0 +1,145 @@
+# Expectations
+
+## When to use this reference
+
+Use this file when writing assertions, migrating from `XCTAssert*`, testing thrown errors, or documenting known failures.
+
+## `#expect` as the default
+
+- Use `#expect` for most assertions.
+- Pass natural Swift expressions (`==`, `>`, `.contains`, `.isEmpty`, etc.).
+- Rely on captured sub-expression values for rich diagnostics in Xcode.
+- Avoid old XCTest assertion families in Swift Testing tests.
+
+### Example: expressive assertions
+
+```swift
+import Testing
+
+@Test func pricingRules() {
+ let subtotal = 25
+ let discount = 5
+ let total = subtotal - discount
+
+ #expect(total == 20)
+ #expect(total > 0)
+ #expect([10, 20, 30].contains(total))
+}
+```
+
+## `#require` for prerequisites
+
+- Use `try #require(...)` when later assertions depend on this condition.
+- Treat `#require` as "guard + fail test early".
+- Use return value to unwrap optionals safely and reduce noisy optional chaining.
+- Prefer this pattern over manual optional checks when failure should halt test flow.
+
+### Example: optional precondition + unwrapped usage
+
+```swift
+import Testing
+
+@Test func parsedURLHasHTTPS() throws {
+ let value = "https://www.avanderlee.com"
+ let url = try #require(URL(string: value), "URL should parse")
+ #expect(url.scheme == "https")
+}
+```
+
+## Throwing behavior checks
+
+- For success-path calls to throwing functions, call directly and assert returned value.
+- For expected failure, use throw-aware expectations to verify:
+  - any throw
+  - specific error type
+  - specific error case/value
+- Avoid verbose hand-written `do/catch` unless custom branching is truly needed.
+
+### Example: expected throw and no-throw
+
+```swift
+import Testing
+
+enum BrewError: Error, Equatable {
+ case missingBeans
+}
+
+func brew(_ hasBeans: Bool) throws -> String {
+ guard hasBeans else { throw BrewError.missingBeans }
+ return "coffee"
+}
+
+@Test func expectedThrows() {
+ #expect(throws: BrewError.self) {
+ try brew(false)
+ }
+}
+
+@Test func expectedNoThrow() {
+ #expect(throws: Never.self) {
+ try brew(true)
+ }
+}
+```
+
+## Known issue handling
+
+- Use `withKnownIssue` for temporary expected failures you still want to compile/run.
+- Prefer `withKnownIssue` over blanket disabling when you need ongoing visibility.
+- Remove known-issue wrappers once failure condition is fixed.
+
+### Example: scope only failing section
+
+```swift
+import Testing
+
+@Test func checkoutFlow() {
+ #expect(true) // still validated
+
+ withKnownIssue("Checkout backend intermittently returns 503", isIntermittent: true) {
+ Issue.record("Known upstream issue")
+ }
+
+ #expect(2 + 2 == 4) // rest of test still executes
+}
+```
+
+## Readability upgrade
+
+- Conform complex domain types to `CustomTestStringConvertible` for concise test output.
+- Keep production `CustomStringConvertible` separate from test-specific descriptions when needed.
+
+### Example: clean diagnostic descriptions
+
+```swift
+import Testing
+
+struct Receipt: CustomTestStringConvertible {
+ let id: UUID
+ let total: Decimal
+
+ var testDescription: String {
+ "Receipt(total: \(total))"
+ }
+}
+```
+
+## XCTest mapping quick examples
+
+```swift
+// XCTAssertEqual(total, 20)
+#expect(total == 20)
+
+// try XCTUnwrap(user)
+let user = try #require(user)
+
+// XCTFail("Unreachable")
+Issue.record("Unreachable")
+```
+
+## Do / Don't
+
+- Do use `#require` when later checks depend on a value.
+- Do keep `withKnownIssue` scopes narrow.
+- Don't use XCTest assertions in Swift Testing tests.
+- Don't hide prerequisite failures inside later optional chaining.

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

@@ -0,0 +1,141 @@
+# Fundamentals
+
+## When to use this reference
+
+Use this file when creating new Swift Testing suites or refactoring test structure before deeper topics like traits, parameterization, or migration.
+
+## Building blocks
+
+- Import `Testing` only in test targets.
+- Use `@Test` to declare tests explicitly (global function or type method).
+- Use suites (`struct`, `actor`, or `class`) to group related tests.
+- Prefer `struct` suites for value semantics and accidental-state-sharing prevention.
+- Use `@Suite` when adding suite-level traits or display names.
+- Use nested suites to reflect feature grouping and improve discoverability.
+
+## Core examples
+
+### Global test function
+
+```swift
+import Testing
+@testable import FoodTruck
+
+@Test("Food truck has a valid default name")
+func defaultName() {
+ let truck = FoodTruck()
+ #expect(truck.name.isEmpty == false)
+}
+```
+
+### Suite with instance tests
+
+```swift
+import Testing
+@testable import FoodTruck
+
+@Suite("Menu tests")
+struct MenuTests {
+ @Test("Returns no duplicates")
+ func uniqueItems() {
+ let items = Menu.default.items
+ #expect(Set(items).count == items.count)
+ }
+}
+```
+
+### Nested suites for feature grouping
+
+```swift
+import Testing
+@testable import FoodTruck
+
+struct CheckoutTests {
+ struct Taxes {
+ @Test func taxIsRoundedToTwoDigits() {
+ let total = Checkout.total(subtotal: 10.00, taxRate: 0.0825)
+ #expect(total == 10.83)
+ }
+ }
+
+ struct Discounts {
+ @Test func promoCodeAppliesFixedAmount() {
+ let total = Checkout.total(subtotal: 20.00, discount: .fixed(5))
+ #expect(total == 15.00)
+ }
+ }
+}
+```
+
+## Recommended defaults
+
+- Keep tests small and behavior-focused.
+- Prefer descriptive names over boilerplate `test...` prefixes.
+- Use display names where human-readable output helps triage.
+- Keep setup local, or centralize in suite init when shared across tests.
+- Avoid hidden global mutable state.
+- Use `@MainActor` only when code under test requires main-thread isolation.
+- Use `@available` on test functions when needed for platform/language gating.
+
+## Organization guidance
+
+- Group by feature behavior, not by implementation class only.
+- Promote shared traits (e.g. tags) to suite level when all tests inherit them.
+- Use tags for cross-cutting grouping across files/targets.
+- Keep unrelated tests in separate suites to preserve clear ownership.
+
+## Suite constraints to enforce
+
+- If a suite has instance test methods, it must have a callable zero-argument initializer (implicit or explicit, sync/async, throwing or non-throwing).
+- If initialization requirements cannot be met, convert tests to static/global functions or refactor suite state.
+- Suite types (and containing types) must always be available; do not apply `@available` to suite declarations.
+
+### Zero-argument initializer requirement example
+
+```swift
+import Testing
+
+@Suite
+struct SessionTests {
+ let config: URLSessionConfiguration
+
+ // Valid: callable with zero args due to default value.
+ init(config: URLSessionConfiguration = .ephemeral) {
+ self.config = config
+ }
+
+ @Test func usesEphemeralByDefault() {
+ #expect(config == .ephemeral)
+ }
+}
+```
+
+### Invalid availability placement
+
+```swift
+import Testing
+
+// Do not do this on suite types:
+// @available(iOS 18, *)
+@Suite
+struct PushTests {
+ @available(iOS 18, *)
+ @Test func supportsNewPushFormat() {
+ #expect(true)
+ }
+}
+```
+
+## Do / Don't
+
+- Do keep each test focused on one behavior.
+- Do use display names where they improve failure readability.
+- Don't rely on test execution order.
+- Don't annotate suites with `@available`; annotate test functions instead.
+
+## Review checklist
+
+- Test target imports `Testing`, app targets do not.
+- Suite choice (`struct`/`actor`/`class`) matches setup and teardown needs.
+- Instance tests have a callable zero-argument init path.
+- Availability is applied to test functions, not suite types.

package/skills/ios/swift-testing-expert/references/migration-from-xctest.md

@@ -0,0 +1,127 @@
+# Migration from XCTest
+
+## When to use this reference
+
+Use this file for incremental migration of existing XCTest code to Swift Testing while preserving safety and CI signal.
+
+## Coexistence strategy
+
+- Swift Testing and XCTest can coexist in the same target.
+- Migrate incrementally; do not block migration on full rewrite.
+- A single source file can import both `XCTest` and `Testing` during migration.
+- Keep XCTest where Swift Testing does not apply:
+  - UI automation (`XCUIApplication`)
+  - performance APIs (`XCTMetric`)
+  - Objective-C-only tests
+
+### Mixed import file example
+
+```swift
+import XCTest
+import Testing
+```
+
+## Practical migration order
+
+1. Convert assertions to `#expect` / `#require`.
+2. Replace `test...` naming constraints with explicit `@Test`.
+3. Reorganize classes into suites where helpful.
+4. Collapse repetitive methods into parameterized tests.
+5. Add traits/tags for control and test-plan filtering.
+
+## Example conversion: class method -> Swift Testing function
+
+```swift
+// Before (XCTest)
+final class PriceTests: XCTestCase {
+ func testDiscountedTotal() {
+ XCTAssertEqual(Price.total(subtotal: 20, discount: 5), 15)
+ }
+}
+
+// After (Swift Testing)
+import Testing
+
+@Test func discountedTotal() {
+ #expect(Price.total(subtotal: 20, discount: 5) == 15)
+}
+```
+
+## Assertion mapping highlights
+
+- Most `XCTAssert*` variants -> `#expect(...)`.
+- Optional unwrap checks -> `try #require(optionalValue)`.
+- Early-stop semantics -> `#require` instead of global `continueAfterFailure = false`.
+- `XCTFail("...")` -> `Issue.record("...")`.
+
+### Table-style quick mappings
+
+```swift
+// XCTAssertTrue(isEnabled)
+#expect(isEnabled)
+
+// XCTAssertNil(error)
+#expect(error == nil)
+
+// XCTAssertThrowsError(try run())
+#expect(throws: (any Error).self) { try run() }
+
+// try XCTUnwrap(user)
+let user = try #require(user)
+```
+
+## Suite model differences
+
+- XCTest: class + `XCTestCase`.
+- Swift Testing: struct/actor/class suites, explicit attributes, value-semantics-friendly defaults.
+- Setup can move from `setUp` patterns to suite init when appropriate.
+- Teardown can move to `deinit` when using class/actor suites.
+- XCTest sync tests default to main actor behavior; Swift Testing runs tests on arbitrary tasks unless explicitly isolated (e.g. `@MainActor`).
+
+### Setup migration example
+
+```swift
+import Testing
+
+struct SessionTests {
+ let session: Session
+
+ init() {
+ self.session = Session(environment: .test)
+ }
+
+ @Test func startsDisconnected() {
+ #expect(session.isConnected == false)
+ }
+}
+```
+
+## Async migration specifics
+
+- Prefer `await` directly for async APIs.
+- Convert completion-handler APIs with `withCheckedContinuation`/`withCheckedThrowingContinuation`.
+- Replace `XCTestExpectation` patterns with confirmations when testing asynchronous event streams.
+
+### Expectation-style flow -> confirmation
+
+```swift
+import Testing
+
+@Test func receivesAtLeastOneEvent() async {
+ await confirmation("Receives event", expectedCount: 1...) { confirm in
+ confirm()
+ }
+}
+```
+
+## Migration hygiene
+
+- Prefer mechanical, reviewable commits.
+- Use editor pattern-replace to accelerate common assertion conversions.
+- Avoid mixing XCTest assertions in Swift Testing tests (and vice versa).
+
+## Common pitfalls
+
+- Migrating all files at once instead of phased migration.
+- Keeping `continueAfterFailure` patterns instead of targeted `#require`.
+- Marking every migrated test `@MainActor` unnecessarily.