Skip to content
Skills Library
Programming · Testing

scaffolding-testing

/scaffolding-testing

Test Scaffolding navigation with Swift Testing and ScaffoldingTesting. Use for activation, typed hierarchy assertions, deadline-based waits, results and cancellation, tabs, split columns, deep links, or restoration.

Repository
scaffolding ↗
Licence
MIT
Last repository change
04.10.2026

Assessment and security

95/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 04.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Test Scaffolding navigation with Swift Testing and ScaffoldingTesting. Use for activation, typed hierarchy assertions, deadline-based waits, results and cancellation, tabs, split columns, deep links, or restoration.

Original author description

Test Scaffolding navigation with Swift Testing and ScaffoldingTesting. Use for activation, typed hierarchy assertions, deadline-based waits, results and cancellation, tabs, split columns, deep links, or restoration.

How it works

  1. Establish initial state
  2. Assert public behavior
  3. Await a result safely
  4. Modal queues and tab guards
  5. Deep links and restoration
  6. Keep unit and rendered checks separate
Original SKILL.md headings · 131 lines, 647 words
SKILL.md preview
---
description: "Test Scaffolding navigation with Swift Testing and ScaffoldingTesting. Use for activation, typed hierarchy assertions, deadline-based waits, results and cancellation, tabs, split columns, deep links, or restoration."
name: scaffolding-testing
---

# Test navigation through the coordinator

Link **ScaffoldingTesting** only into the test target; it imports Swift Testing.
Test the shipping coordinator on `@MainActor`. Ordinary navigation changes state
synchronously; awaited navigation needs a task that the test can complete.

```swift
// Package.swift
.testTarget(name: "MyAppTests", dependencies: [
    "MyApp",
    .product(name: "ScaffoldingTesting", package: "scaffolding"),
])
```

## Establish initial state

```swift
import Testing
import Scaffolding
import ScaffoldingTesting
@testable import MyApp

@MainActor @Suite("Home flow")
struct HomeFlowTests {
    @Test func opensDetail() {
        let home = HomeCoordinator().activated()
        home.open(Transaction.sample)
        #expect(home.depth == 1)
        #expect(home.topDestination == .transaction)
    }
}
```

Containers resolve lazily. Navigation and many queries resolve them;
`debugHierarchy()` and `hierarchySnapshot()` deliberately do not. Use
`activated()` when a test needs the complete initial hierarchy. Calling it
again is harmless.

## Assert public behavior

| Question | API |
|---|---|
| Number and top case of pushes | `depth`, `topDestination` (exclude modals) |
| Own entries matching a case | `isInStack(_:)`, `count(of:)` (include modals, exclude root) |
| Modal requests, including pending | `isPresentingModal`, `pendingModalCount` |
| Selected root / tab | `isRoot(_:)`, `selectedTabDestination`, `selectedTabIndex` |
| Tab metadata | `badge(for:)`, `tabAccessibilityIdentifier(for:)` |
| Split columns | `sidebarDestination`, `contentDestination`, `detailDestination`, `isDetail(_:)` |
| Presentation and ancestry | `routeType`, `ancestor(ofType:)`, `hierarchyRoot` |
| Whole-tree shape | `hierarchyContains(_:_:as:)`, `hierarchySnapshot()` |

Prefer typed assertions over matching debug strings:

```swift
#expect(app.hierarchyContains(HomeCoordinator.self, .transaction, as: .push))
#expect(app.hierarchyContains(MainTabCoordinator.self, .home,
                              as: .tab(index: 0, isSelected: true)))
#expect(split.hierarchyContains(LibraryCoordinator.self, .planet,
                                as: .column(.detail)))
```

Use `expecting:` when the test performs navigation. Use `descendant(ofType:)`
or `descendants(ofType:)` to find children that the code under test created.
Those helpers never materialize children. Do not add stored child references
to production coordinators just to make tests easier.

## Await a result safely

```swift
let picking = Task { await cards.present(.limitPicker, awaiting: Decimal.self) }
defer { picking.cancel() }
guard await waitUntil({ cards.isPresentingModal }, timeout: .seconds(2)) else {
    picking.cancel()
    return
}

let picker = try #require(cards.descendant(ofType: LimitCoordinator.self))
picker.finish(2_000)
#expect(await picking.value == 2_000)
```

The enclosing test must be `async throws`. `waitUntil` returns `Bool`, uses a
monotonic deadline (five seconds by default), and records an issue at the caller
on timeout. Cancellation returns false without a timeout issue. Guard the result
before awaiting a task that cannot complete after a failed condition. The old
`iterations:` overload is deprecated.

For cancellation, cancel the waiting task and assert that the route remains.
For dismissal without a result, call `dismissPresentedModal()` and assert nil.
Assert the navigation state as well as the nil return to distinguish these behaviors.

## Modal queues and tab guards

With A visible and B queued on the same coordinator, `dismissModal()` removes B;
`dismissPresentedModal()` closes A; `cancelPendingModals()` removes B and leaves
A. Verify the operation your action intends to perform. Modal helpers never pop
pushed destinations. Child self-dismissal uses `dismissCoordinator()`.

`shouldSelect(tab:isReselection:)` is an ordinary method. Call it explicitly to
test a veto or re-tap side effect. `selectFirstTab` is programmatic selection
and bypasses that hook. Check `selectedTabIndex`, not a nonexistent `selectedIndex`.

## Deep links and restoration

Test a deep link as one coordinator action, including unauthenticated and
repeated-link cases. `setRoot` creates a fresh child even if its case is unchanged;
assert whether the action should retain or replace an existing branch.

```swift
let data = try original.captureNavigationState(version: 1)
let restored = AppCoordinator().activated()
let report = try restored.restoreNavigationStateWithReport(from: data, mode: .replace)
#expect(report.issues.isEmpty)
#expect(restored.hierarchyContains(HomeCoordinator.self, .transaction, as: .push))
```

Test expected partial recovery with saved fixtures when routes change. An
unsupported child restores at its initial state; an unsupported capture root
throws. Repeated `.replace` restoration should not duplicate seeded paths.

## Keep unit and rendered checks separate

Coordinator tests assert decisions and tree state. They do not inspect a view's
`@State` or environment `\.destination`. A bare view preview also lacks real
destination metadata; a coordinator preview does not.

Library changes affecting rendering need hosted checks as well. `swift test`
includes macOS hosted regressions; check iOS presentation and native tab
metadata in a running app. Platform compilation alone cannot verify them.

Versions

The database has no other skills named scaffolding-testing.

Database snapshot: 13.11.2026 · package version 5235eb8f29f5 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100swift-test-scaffold
    Use when adding Swift tests, creating test targets, scaffolding ViewModel or service tests, or choosing Swift Testing over XCTest.
  • 100scaffolding-state-restoration
    Capture, restore, migrate, and diagnose Scaffolding navigation snapshots. Use for Codable routes, replay versus replacement, partial-restoration reports, per-scene checkpoints, and hierarchy inspection.
  • 100swift-testing-pro
    Writes, reviews, and improves Swift Testing code using modern APIs and best practices. Use when reading, writing, or reviewing projects that use Swift Testing.
  • 96scaffolding-routing
    Write and review Scaffolding navigation: pushes, pops, modal queues, dismissal, typed child access, awaited results, animation scopes, and deep links. Use when choosing a navigation call or migrating deprecated overloads.
  • 100swift-testing-pro
    Writes, reviews, and improves Swift Testing code using modern APIs and best practices. Use when reading, writing, or reviewing projects that use Swift Testing.
  • 100swift-testing
    Use when developers mention - (1) Swift Testing, @Test, expect, require, or @Suite, (2) "use Swift Testing" or "modern testing patterns", (3) test doubles, mocks, stubs, spies, or fixtures, (4) unit tests, integration tests, or snapshot tests, (5) migrating from XCTest to Swift Testing, (6) TDD…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.