Mention accessed property key path in perception warnings (#167)

pyrtsa · stephencelis · web-flow · commit b7fc720a2c7b · 2025-10-23T12:33:46.000-07:00
* Fix unit tests on macOS, where tests now build against macosx14.0 by default

* Update CI matrix to include Xcode 26.0

* Update CI to use actions/checkout@v5

* Skip perception checking tests if ImageRenderer is not available

* Re-enable several perception checking tests on macOS

* Mention accessed property key path in perception warnings

---------

Co-authored-by: Stephen Celis &lt;stephen@stephencelis.com&gt;
diff --git a/README.md b/README.md
@@ -66,7 +66,7 @@ It's unfortunate to have to wrap your view's content in `WithPerceptionTracking`
 then you will helpfully get a runtime warning letting you know that observation is not set up
 correctly:
 
-> 🟣 Runtime Warning: Perceptible state was accessed from a view but is not being tracked.
+> 🟣 Runtime Warning: Perceptible state '\FeatureModel.count' was accessed from a view but is not being tracked.
 
 Finally, the `Observations` async sequence has been back-ported as `Perceptions`, which can be used
 to observe changes to perceptible and observable objects over time:
diff --git a/Sources/PerceptionCore/Documentation.docc/PerceptionCore.md b/Sources/PerceptionCore/Documentation.docc/PerceptionCore.md
@@ -53,7 +53,7 @@ It's unfortunate to have to wrap your view's content in `WithPerceptionTracking`
 then you will helpfully get a runtime warning letting you know that observation is not set up
 correctly:
 
-> 🟣 Runtime Warning: Perceptible state was accessed from a view but is not being tracked.
+> 🟣 Runtime Warning: Perceptible state '\FeatureModel.count' was accessed from a view but is not being tracked.
 
 Finally, the `Observations` async sequence has been back-ported as `Perceptions`, which can be used
 to observe changes to perceptible and observable objects over time:
diff --git a/Sources/PerceptionCore/Perception/PerceptionRegistrar.swift b/Sources/PerceptionCore/Perception/PerceptionRegistrar.swift
@@ -62,7 +62,7 @@ public struct PerceptionRegistrar: Sendable {
     keyPath: KeyPath<Subject, Member>
   ) {
     #if DEBUG && canImport(SwiftUI)
-      check()
+      check(keyPath)
     #endif
     #if canImport(Observation)
       if #available(iOS 17, macOS 14, tvOS 17, watchOS 10, *),
@@ -254,7 +254,7 @@ extension PerceptionRegistrar: Hashable {
   extension PerceptionRegistrar {
     @_transparent
     @usableFromInline
-    func check() {
+    func check<Subject, Member>(_ keyPath: KeyPath<Subject, Member>) {
       if _isPerceptionCheckingEnabled,
         PerceptionCore.isPerceptionCheckingEnabled,
         !_PerceptionLocals.isInPerceptionTracking,
@@ -263,7 +263,7 @@ extension PerceptionRegistrar: Hashable {
       {
         reportIssue(
           """
-          Perceptible state was accessed from a view but is not being tracked.
+          Perceptible state '\(keyPath)' was accessed from a view but is not being tracked.
 
           Use this warning's stack trace to locate the view in question and wrap it with a \
           'WithPerceptionTracking' view. For example:
diff --git a/Sources/PerceptionCore/SwiftUI/WithPerceptionTracking.swift b/Sources/PerceptionCore/SwiftUI/WithPerceptionTracking.swift
@@ -40,7 +40,7 @@
   /// If a field of a `@Perceptible` model is accessed in a view while _not_ inside
   /// ``WithPerceptionTracking``, then a runtime warning will helpfully be triggered:
   ///
-  /// > Warning: Perceptible state was accessed but is not being tracked.
+  /// > Warning: Perceptible state '\FeatureModel.count' was accessed but is not being tracked.
   ///
   /// To debug this, expand the warning in the Issue Navigator of Xcode (cmd+5), and click through
   /// the stack frames displayed to find the line in your view where you are accessing state without
diff --git a/Tests/PerceptionTests/PerceptionCheckingTests.swift b/Tests/PerceptionTests/PerceptionCheckingTests.swift
@@ -35,7 +35,7 @@
       struct FeatureView: View {
         let model = Model()
         var body: some View {
-          Text(expectRuntimeWarning { model.count }.description)
+          Text(expectRuntimeWarning(on: #"\Model.count"#) { model.count }.description)
         }
       }
       try await render(FeatureView())
@@ -47,7 +47,7 @@
         let model = Model()
         var body: some View {
           Wrapper {
-            Text(expectRuntimeWarning { model.count }.description)
+            Text(expectRuntimeWarning(on: #"\Model.count"#) { model.count }.description)
           }
         }
       }
@@ -88,13 +88,13 @@
         @Perception.Bindable var model: Model
         var body: some View {
           Form {
-            TextField("", text: expectRuntimeWarning { $model.text })
+            TextField("", text: expectRuntimeWarning(on: #"\Model.text"#) { $model.text })
           }
         }
       }
       #if os(macOS)
         // NB: This failure is triggered out-of-body by the binding.
-        XCTExpectFailure { $0.compactDescription.contains("Perceptible state was accessed") }
+        XCTExpectFailure { $0.compactDescription.contains(#"Perceptible state '\Model.text' was accessed"#) }
       #endif
       try await render(FeatureView(model: Model()))
     }
@@ -117,8 +117,8 @@
       struct FeatureView: View {
         let model: Model
         var body: some View {
-          ForEach(expectRuntimeWarning { model.list }) { model in
-            Text(expectRuntimeWarning { model.count }.description)
+          ForEach(expectRuntimeWarning(on: #"\Model.list"#) { model.list }) { model in
+            Text(expectRuntimeWarning(on: #"\Model.count"#) { model.count }.description)
           }
         }
       }
@@ -141,7 +141,7 @@
       struct FeatureView: View {
         let model: Model
         var body: some View {
-          ForEach(expectRuntimeWarning { model.list }) { model in
+          ForEach(expectRuntimeWarning(on: #"\Model.list"#) { model.list }) { model in
             WithPerceptionTracking {
               Text(model.count.description)
             }
@@ -169,7 +169,7 @@
         var body: some View {
           WithPerceptionTracking {
             ForEach(model.list) { model in
-              Text(expectRuntimeWarning { model.count }.description)
+              Text(expectRuntimeWarning(on: #"\Model.count"#) { model.count }.description)
             }
           }
         }
@@ -222,13 +222,13 @@
         @Perception.Bindable var model: Model
         var body: some View {
           Text("Parent")
-            .sheet(item: expectRuntimeWarning { $model.child }) { child in
-              Text(expectRuntimeWarning { child.count }.description)
+            .sheet(item: expectRuntimeWarning(on: #"\Model.child"#) { $model.child }) { child in
+              Text(expectRuntimeWarning(on: #"\Model.count"#) { child.count }.description)
             }
         }
       }
       // NB: This failure is triggered out-of-body by the binding.
-      XCTExpectFailure { $0.compactDescription.contains("Perceptible state was accessed") }
+      XCTExpectFailure { $0.compactDescription.contains(#"Perceptible state '\Model.child' was accessed"#) }
       try await render(FeatureView(model: Model(child: Model())))
     }
 
@@ -238,15 +238,15 @@
         @Perception.Bindable var model: Model
         var body: some View {
           Text("Parent")
-            .sheet(item: expectRuntimeWarning { $model.child }) { child in
+            .sheet(item: expectRuntimeWarning(on: #"\Model.child"#) { $model.child }) { child in
               WithPerceptionTracking {
                 Text(child.count.description)
               }
             }
         }
       }
       // NB: This failure is triggered out-of-body by the binding.
-      XCTExpectFailure { $0.compactDescription.contains("Perceptible state was accessed") }
+      XCTExpectFailure { $0.compactDescription.contains(#"Perceptible state '\Model.child' was accessed"#) }
       try await render(FeatureView(model: Model(child: Model())))
     }
 
@@ -258,7 +258,7 @@
           WithPerceptionTracking {
             Text("Parent")
               .sheet(item: $model.child) { child in
-                Text(expectRuntimeWarning { child.count }.description)
+                Text(expectRuntimeWarning(on: #"\Model.count"#) { child.count }.description)
               }
           }
         }
@@ -384,7 +384,7 @@
         var body: some View {
           VStack {
             ChildView(model: self.childModel)
-            Text(expectRuntimeWarning { childModel.count }.description)
+            Text(expectRuntimeWarning(on: #"\Model.count"#) { childModel.count }.description)
           }
           .onAppear { let _ = childModel.count }
         }
@@ -398,7 +398,7 @@
       struct ChildView: View {
         let model: Model
         var body: some View {
-          Text(expectRuntimeWarning { model.count }.description)
+          Text(expectRuntimeWarning(on: #"\Model.count"#) { model.count }.description)
             .onAppear { let _ = model.count }
         }
       }
@@ -426,7 +426,7 @@
       struct ChildView: View {
         let model: Model
         var body: some View {
-          Text(expectRuntimeWarning { model.count }.description)
+          Text(expectRuntimeWarning(on: #"\Model.count"#) { model.count }.description)
             .onAppear { let _ = model.count }
         }
       }
@@ -440,7 +440,7 @@
         var body: some View {
           VStack {
             ChildView(model: self.childModel)
-            Text(expectRuntimeWarning { childModel.count }.description)
+            Text(expectRuntimeWarning(on: #"\Model.count"#) { childModel.count }.description)
           }
           .onAppear { let _ = childModel.count }
         }
@@ -535,7 +535,7 @@
         var body: some View {
           WithPerceptionTracking {
             GeometryReader { _ in
-              Text(expectRuntimeWarning { model.count }.description)
+              Text(expectRuntimeWarning(on: #"\Model.count"#) { model.count }.description)
             }
           }
         }
@@ -569,7 +569,7 @@
         }
         var content: some View {
           GeometryReader { _ in
-            Text(expectRuntimeWarning { model.count }.description)
+            Text(expectRuntimeWarning(on: #"\Model.count"#) { model.count }.description)
           }
         }
       }
@@ -613,9 +613,9 @@
     }
   }
 
-  private func expectRuntimeWarning<R>(failingBlock: () -> R) -> R {
+  private func expectRuntimeWarning<R>(on keyPathString: String, failingBlock: () -> R) -> R {
     XCTExpectFailure(failingBlock: failingBlock) {
-      $0.compactDescription.contains("Perceptible state was accessed")
+      $0.compactDescription.contains("Perceptible state '\(keyPathString)' was accessed")
     }
   }
 

Original file line number	Diff line number	Diff line change
`@@ -35,7 +35,7 @@`
`35`	`35`	`struct FeatureView: View {`
`36`	`36`	`let model = Model()`
`37`	`37`	`var body: some View {`
`38`		`- Text(expectRuntimeWarning { model.count }.description)`
	`38`	`+ Text(expectRuntimeWarning(on: #"\Model.count"#) { model.count }.description)`
`39`	`39`	`}`
`40`	`40`	`}`
`41`	`41`	`try await render(FeatureView())`
`@@ -47,7 +47,7 @@`
`47`	`47`	`let model = Model()`
`48`	`48`	`var body: some View {`
`49`	`49`	`Wrapper {`
`50`		`- Text(expectRuntimeWarning { model.count }.description)`
	`50`	`+ Text(expectRuntimeWarning(on: #"\Model.count"#) { model.count }.description)`
`51`	`51`	`}`
`52`	`52`	`}`
`53`	`53`	`}`
`@@ -88,13 +88,13 @@`
`88`	`88`	`@Perception.Bindable var model: Model`
`89`	`89`	`var body: some View {`
`90`	`90`	`Form {`
`91`		`- TextField("", text: expectRuntimeWarning { $model.text })`
	`91`	`+ TextField("", text: expectRuntimeWarning(on: #"\Model.text"#) { $model.text })`
`92`	`92`	`}`
`93`	`93`	`}`
`94`	`94`	`}`
`95`	`95`	`#if os(macOS)`
`96`	`96`	`// NB: This failure is triggered out-of-body by the binding.`
`97`		`- XCTExpectFailure { $0.compactDescription.contains("Perceptible state was accessed") }`
	`97`	`+ XCTExpectFailure { $0.compactDescription.contains(#"Perceptible state '\Model.text' was accessed"#) }`
`98`	`98`	`#endif`
`99`	`99`	`try await render(FeatureView(model: Model()))`
`100`	`100`	`}`
`@@ -117,8 +117,8 @@`
`117`	`117`	`struct FeatureView: View {`
`118`	`118`	`let model: Model`
`119`	`119`	`var body: some View {`
`120`		`- ForEach(expectRuntimeWarning { model.list }) { model in`
`121`		`- Text(expectRuntimeWarning { model.count }.description)`
	`120`	`+ ForEach(expectRuntimeWarning(on: #"\Model.list"#) { model.list }) { model in`
	`121`	`+ Text(expectRuntimeWarning(on: #"\Model.count"#) { model.count }.description)`
`122`	`122`	`}`
`123`	`123`	`}`
`124`	`124`	`}`
`@@ -141,7 +141,7 @@`
`141`	`141`	`struct FeatureView: View {`
`142`	`142`	`let model: Model`
`143`	`143`	`var body: some View {`
`144`		`- ForEach(expectRuntimeWarning { model.list }) { model in`
	`144`	`+ ForEach(expectRuntimeWarning(on: #"\Model.list"#) { model.list }) { model in`
`145`	`145`	`WithPerceptionTracking {`
`146`	`146`	`Text(model.count.description)`
`147`	`147`	`}`
`@@ -169,7 +169,7 @@`
`169`	`169`	`var body: some View {`
`170`	`170`	`WithPerceptionTracking {`
`171`	`171`	`ForEach(model.list) { model in`
`172`		`- Text(expectRuntimeWarning { model.count }.description)`
	`172`	`+ Text(expectRuntimeWarning(on: #"\Model.count"#) { model.count }.description)`
`173`	`173`	`}`
`174`	`174`	`}`
`175`	`175`	`}`
`@@ -222,13 +222,13 @@`
`222`	`222`	`@Perception.Bindable var model: Model`
`223`	`223`	`var body: some View {`
`224`	`224`	`Text("Parent")`
`225`		`- .sheet(item: expectRuntimeWarning { $model.child }) { child in`
`226`		`- Text(expectRuntimeWarning { child.count }.description)`
	`225`	`+ .sheet(item: expectRuntimeWarning(on: #"\Model.child"#) { $model.child }) { child in`
	`226`	`+ Text(expectRuntimeWarning(on: #"\Model.count"#) { child.count }.description)`
`227`	`227`	`}`
`228`	`228`	`}`
`229`	`229`	`}`
`230`	`230`	`// NB: This failure is triggered out-of-body by the binding.`
`231`		`- XCTExpectFailure { $0.compactDescription.contains("Perceptible state was accessed") }`
	`231`	`+ XCTExpectFailure { $0.compactDescription.contains(#"Perceptible state '\Model.child' was accessed"#) }`
`232`	`232`	`try await render(FeatureView(model: Model(child: Model())))`
`233`	`233`	`}`
`234`	`234`
`@@ -238,15 +238,15 @@`
`238`	`238`	`@Perception.Bindable var model: Model`
`239`	`239`	`var body: some View {`
`240`	`240`	`Text("Parent")`
`241`		`- .sheet(item: expectRuntimeWarning { $model.child }) { child in`
	`241`	`+ .sheet(item: expectRuntimeWarning(on: #"\Model.child"#) { $model.child }) { child in`
`242`	`242`	`WithPerceptionTracking {`
`243`	`243`	`Text(child.count.description)`
`244`	`244`	`}`
`245`	`245`	`}`
`246`	`246`	`}`
`247`	`247`	`}`
`248`	`248`	`// NB: This failure is triggered out-of-body by the binding.`
`249`		`- XCTExpectFailure { $0.compactDescription.contains("Perceptible state was accessed") }`
	`249`	`+ XCTExpectFailure { $0.compactDescription.contains(#"Perceptible state '\Model.child' was accessed"#) }`
`250`	`250`	`try await render(FeatureView(model: Model(child: Model())))`
`251`	`251`	`}`
`252`	`252`
`@@ -258,7 +258,7 @@`
`258`	`258`	`WithPerceptionTracking {`
`259`	`259`	`Text("Parent")`
`260`	`260`	`.sheet(item: $model.child) { child in`
`261`		`- Text(expectRuntimeWarning { child.count }.description)`
	`261`	`+ Text(expectRuntimeWarning(on: #"\Model.count"#) { child.count }.description)`
`262`	`262`	`}`
`263`	`263`	`}`
`264`	`264`	`}`
`@@ -384,7 +384,7 @@`
`384`	`384`	`var body: some View {`
`385`	`385`	`VStack {`
`386`	`386`	`ChildView(model: self.childModel)`
`387`		`- Text(expectRuntimeWarning { childModel.count }.description)`
	`387`	`+ Text(expectRuntimeWarning(on: #"\Model.count"#) { childModel.count }.description)`
`388`	`388`	`}`
`389`	`389`	`.onAppear { let _ = childModel.count }`
`390`	`390`	`}`
`@@ -398,7 +398,7 @@`
`398`	`398`	`struct ChildView: View {`
`399`	`399`	`let model: Model`
`400`	`400`	`var body: some View {`
`401`		`- Text(expectRuntimeWarning { model.count }.description)`
	`401`	`+ Text(expectRuntimeWarning(on: #"\Model.count"#) { model.count }.description)`
`402`	`402`	`.onAppear { let _ = model.count }`
`403`	`403`	`}`
`404`	`404`	`}`
`@@ -426,7 +426,7 @@`
`426`	`426`	`struct ChildView: View {`
`427`	`427`	`let model: Model`
`428`	`428`	`var body: some View {`
`429`		`- Text(expectRuntimeWarning { model.count }.description)`
	`429`	`+ Text(expectRuntimeWarning(on: #"\Model.count"#) { model.count }.description)`
`430`	`430`	`.onAppear { let _ = model.count }`
`431`	`431`	`}`
`432`	`432`	`}`
`@@ -440,7 +440,7 @@`
`440`	`440`	`var body: some View {`
`441`	`441`	`VStack {`
`442`	`442`	`ChildView(model: self.childModel)`
`443`		`- Text(expectRuntimeWarning { childModel.count }.description)`
	`443`	`+ Text(expectRuntimeWarning(on: #"\Model.count"#) { childModel.count }.description)`
`444`	`444`	`}`
`445`	`445`	`.onAppear { let _ = childModel.count }`
`446`	`446`	`}`
`@@ -535,7 +535,7 @@`
`535`	`535`	`var body: some View {`
`536`	`536`	`WithPerceptionTracking {`
`537`	`537`	`GeometryReader { _ in`
`538`		`- Text(expectRuntimeWarning { model.count }.description)`
	`538`	`+ Text(expectRuntimeWarning(on: #"\Model.count"#) { model.count }.description)`
`539`	`539`	`}`
`540`	`540`	`}`
`541`	`541`	`}`
`@@ -569,7 +569,7 @@`
`569`	`569`	`}`
`570`	`570`	`var content: some View {`
`571`	`571`	`GeometryReader { _ in`
`572`		`- Text(expectRuntimeWarning { model.count }.description)`
	`572`	`+ Text(expectRuntimeWarning(on: #"\Model.count"#) { model.count }.description)`
`573`	`573`	`}`
`574`	`574`	`}`
`575`	`575`	`}`
`@@ -613,9 +613,9 @@`
`613`	`613`	`}`
`614`	`614`	`}`
`615`	`615`
`616`		`- private func expectRuntimeWarning<R>(failingBlock: () -> R) -> R {`
	`616`	`+ private func expectRuntimeWarning<R>(on keyPathString: String, failingBlock: () -> R) -> R {`
`617`	`617`	`XCTExpectFailure(failingBlock: failingBlock) {`
`618`		`- $0.compactDescription.contains("Perceptible state was accessed")`
	`618`	`+ $0.compactDescription.contains("Perceptible state '\(keyPathString)' was accessed")`
`619`	`619`	`}`
`620`	`620`	`}`
`621`	`621`