refactor tests around actor data handlers

Author: fatbobman

AGENT.md

@@ -18,9 +18,13 @@
 - Command-line full test runs should use serial execution:
   - `swift test --no-parallel`
   - or `./test.sh`
+- `./test.sh` is the preferred full-suite command because it enables Core Data concurrency assertions via `com.apple.CoreData.ConcurrencyDebug=1`.
 - In Xcode, disable parallel testing for this package before running the full suite.
 - When debugging failures, prefer running a single test file or a filtered suite first.
 - This repository's tests are currently treated as serial-only at the full-suite level.
+- For new Core Data tests, do not write directly through `viewContext` or a raw background context from the test body.
+- Prefer `Tests/PersistentHistoryTrackingKitTests/TestAppDataHandler.swift` and actor-isolated helper methods for creating, updating, deleting, and reading test data.
+- If a test needs direct inspection of a handler-owned context, use the handler's `withContext` API rather than `context.perform` from the test body.
 
 ## Known Test Constraints
 

Sources/PersistentHistoryTrackingKit/PersistentHistoryTrackingKit.swift

@@ -126,6 +126,7 @@ public final class PersistentHistoryTrackingKit: @unchecked Sendable {
 
     transactionProcessor = TransactionProcessorActor(
       container: container,
+      contexts: self.contexts,
       hookRegistry: hookRegistry,
       cleanStrategy: cleanStrategy,
       timestampManager: timestampManager)
@@ -345,7 +346,6 @@ public final class PersistentHistoryTrackingKit: @unchecked Sendable {
         .processNewTransactionsWithTimestampManagement(
           from: authorsToProcess,
           after: lastTimestamp,
-          mergeInto: contexts,
           currentAuthor: currentAuthor,
           batchAuthors: batchAuthors)
 

Sources/PersistentHistoryTrackingKit/TransactionProcessorActor+Testing.swift

@@ -76,15 +76,13 @@ import Foundation
     /// - Parameters:
     ///   - authors: Authors whose transactions should be processed.
     ///   - lastTimestamp: Last processed timestamp.
-    ///   - contexts: Target contexts.
     ///   - currentAuthor: Current author.
     ///   - cleanBeforeTimestamp: Cleanup cutoff timestamp.
     ///   - expectedEntityName: Expected entity name for validation.
     /// - Returns: (transaction count, first transaction author, first change entity name)
     func testProcessNewTransactions(
       from authors: [String],
       after lastTimestamp: Date?,
-      mergeInto contexts: [NSManagedObjectContext],
       currentAuthor: String?,
       cleanBeforeTimestamp: Date?,
       expectedEntityName: String?
@@ -113,7 +111,6 @@ import Foundation
       let count = try await processNewTransactions(
         from: authors,
         after: lastTimestamp,
-        mergeInto: contexts,
         currentAuthor: currentAuthor,
         cleanBeforeTimestamp: cleanBeforeTimestamp)
 
@@ -165,14 +162,12 @@ import Foundation
     /// Verify that hooks are triggered as expected.
     /// - Parameters:
     ///   - authors: Authors to process.
-    ///   - contexts: Contexts to merge into.
     ///   - expectedEntityName: Expected entity name for the hook.
     ///   - expectedOperation: Expected operation type.
     /// - Returns: (transaction count, first change entity name, first change operation)
     func testHookTrigger(
       from authors: [String],
       after date: Date?,
-      mergeInto contexts: [NSManagedObjectContext],
       currentAuthor: String?,
       expectedEntityName: String,
       expectedOperation: HookOperation
@@ -205,7 +200,6 @@ import Foundation
       let count = try await processNewTransactions(
         from: authors,
         after: date,
-        mergeInto: contexts,
         currentAuthor: currentAuthor,
         cleanBeforeTimestamp: nil)
 

Sources/PersistentHistoryTrackingKit/TransactionProcessorActor.swift

@@ -6,7 +6,6 @@
 //  Copyright © 2025 Yang Xu. All rights reserved.
 //
 
-import CoreData
 import CoreDataEvolution
 import Foundation
 
@@ -22,6 +21,9 @@ actor TransactionProcessorActor {
   /// Timestamp manager.
   private let timestampManager: TransactionTimestampManager
 
+  /// Contexts that receive merged transactions.
+  private let mergeContexts: [NSManagedObjectContext]
+
   // MARK: - Merge Hooks (managed inside the same actor to avoid passing non-Sendable types)
 
   private struct MergeHookItem {
@@ -33,12 +35,14 @@ actor TransactionProcessorActor {
 
   init(
     container: NSPersistentContainer,
+    contexts: [NSManagedObjectContext]? = nil,
     hookRegistry: HookRegistryActor,
     cleanStrategy: TransactionCleanStrategy,
     timestampManager: consuming TransactionTimestampManager
   ) {
     self.hookRegistry = hookRegistry
     self.timestampManager = timestampManager
+    mergeContexts = contexts ?? [container.viewContext]
 
     // Initialize the cleanup strategy configuration.
     switch cleanStrategy {
@@ -101,15 +105,13 @@ actor TransactionProcessorActor {
   /// - Parameters:
   ///   - authors: Authors whose transactions need to be merged.
   ///   - lastTimestamp: The last processed timestamp.
-  ///   - contexts: Target contexts for merging.
   ///   - currentAuthor: Current author (used to exclude self-authored transactions).
   ///   - cleanBeforeTimestamp: Optional timestamp; history before this will be cleaned.
   /// - Returns: Number of transactions processed.
   @discardableResult
   func processNewTransactions(
     from authors: [String],
     after lastTimestamp: Date?,
-    mergeInto contexts: [NSManagedObjectContext],
     currentAuthor: String? = nil,
     cleanBeforeTimestamp: Date? = nil
   ) async throws -> Int {
@@ -125,7 +127,7 @@ actor TransactionProcessorActor {
 
     // 3. Trigger Merge Hooks (pipeline, may mutate data).
     // Runs within the same actor to avoid cross-actor non-Sendable transfers.
-    try await triggerMergeHooks(transactions: transactions, contexts: contexts)
+    try await triggerMergeHooks(transactions: transactions)
 
     // 4. Run cleanup when a timestamp is provided.
     if let cleanTimestamp = cleanBeforeTimestamp {
@@ -139,15 +141,13 @@ actor TransactionProcessorActor {
   /// - Parameters:
   ///   - authors: Authors whose transactions need to be merged.
   ///   - lastTimestamp: The last processed timestamp.
-  ///   - contexts: Target contexts for merging.
   ///   - currentAuthor: Current author (excluded from fetch and used to update timestamp).
   ///   - batchAuthors: Authors participating in batch work (excluded from cleanup calculation).
   /// - Returns: Number of transactions processed.
   @discardableResult
   func processNewTransactionsWithTimestampManagement(
     from authors: [String],
     after lastTimestamp: Date?,
-    mergeInto contexts: [NSManagedObjectContext],
     currentAuthor: String,
     batchAuthors: [String] = []
   ) async throws -> Int {
@@ -162,7 +162,7 @@ actor TransactionProcessorActor {
     await triggerObserverHooks(for: transactions)
 
     // 3. Trigger Merge Hooks (pipeline that may mutate data).
-    try await triggerMergeHooks(transactions: transactions, contexts: contexts)
+    try await triggerMergeHooks(transactions: transactions)
 
     // 4. Update the timestamp for the current author.
     if let newTimestamp = transactions.last?.timestamp {
@@ -358,13 +358,11 @@ actor TransactionProcessorActor {
   /// Run the Merge Hook pipeline.
   /// - Parameters:
   ///   - transactions: Transactions flowing through the pipeline.
-  ///   - contexts: Target contexts.
   /// - Note: All operations execute inside the same actor, so there are no concurrency concerns.
   private func triggerMergeHooks(
-    transactions: [NSPersistentHistoryTransaction],
-    contexts: [NSManagedObjectContext]
+    transactions: [NSPersistentHistoryTransaction]
   ) async throws {
-    let input = MergeHookInput(transactions: transactions, contexts: contexts)
+    let input = MergeHookInput(transactions: transactions, contexts: mergeContexts)
 
     // Execute each merge hook sequentially.
     for item in mergeHooks {
@@ -375,7 +373,7 @@ actor TransactionProcessorActor {
     }
 
     // All hooks returned .goOn (or none were registered), so perform the default merge.
-    try await mergeTransactions(transactions, into: contexts)
+    try await mergeTransactions(transactions, into: mergeContexts)
   }
 
   // MARK: - Clean

Tests/PersistentHistoryTrackingKitTests/CleanStrategyTests.swift

@@ -17,25 +17,19 @@ struct CleanStrategyTests {
     let container = TestModelBuilder.createContainer(
       author: "App1",
       testName: "noneStrategyDisablesAutomaticCleanup")
-    let context1 = container.viewContext
-    context1.transactionAuthor = "App1"
+    let writer = TestAppDataHandler(container: container, viewName: "Writer")
 
-    TestModelBuilder.createPerson(name: "Alice", age: 30, in: context1)
-    try context1.save()
+    try await writer.createPerson(name: "Alice", age: 30, author: "App1")
 
     try await Task.sleep(nanoseconds: 100_000_000)
 
-    TestModelBuilder.createPerson(name: "Bob", age: 31, in: context1)
-    try context1.save()
+    try await writer.createPerson(name: "Bob", age: 31, author: "App1")
 
     let processor = makeProcessor(container: container, cleanStrategy: .none)
-    let mergeContext = container.newBackgroundContext()
-    mergeContext.transactionAuthor = "App2"
 
     _ = try await processor.processNewTransactionsWithTimestampManagement(
       from: ["App1", "App2"],
       after: nil,
-      mergeInto: [mergeContext],
       currentAuthor: "App2")
 
     let remainingCount = try await processor.testTransactionCount(
@@ -51,30 +45,24 @@ struct CleanStrategyTests {
       author: "App1",
       testName: "durationStrategyThrottlesCleanup")
     let userDefaults = TestModelBuilder.createTestUserDefaults()
-    let context1 = container.viewContext
-    context1.transactionAuthor = "App1"
+    let writer = TestAppDataHandler(container: container, viewName: "Writer")
 
-    TestModelBuilder.createPerson(name: "Alice", age: 30, in: context1)
-    try context1.save()
+    try await writer.createPerson(name: "Alice", age: 30, author: "App1")
 
     try await Task.sleep(nanoseconds: 100_000_000)
 
-    TestModelBuilder.createPerson(name: "Bob", age: 31, in: context1)
-    try context1.save()
+    try await writer.createPerson(name: "Bob", age: 31, author: "App1")
 
     let processor = makeProcessor(
       container: container,
       userDefaults: userDefaults,
       cleanStrategy: .byDuration(seconds: 60 * 60))
-    let mergeContext = container.newBackgroundContext()
-    mergeContext.transactionAuthor = "App2"
 
     userDefaults.set(Date(), forKey: "PersistentHistoryTrackingKit.lastToken.App1")
 
     _ = try await processor.processNewTransactionsWithTimestampManagement(
       from: ["App1", "App2"],
       after: nil,
-      mergeInto: [mergeContext],
       currentAuthor: "App2")
 
     let countAfterFirstProcess = try await processor.testTransactionCount(
@@ -87,13 +75,11 @@ struct CleanStrategyTests {
 
     try await Task.sleep(nanoseconds: 100_000_000)
 
-    TestModelBuilder.createPerson(name: "Charlie", age: 32, in: context1)
-    try context1.save()
+    try await writer.createPerson(name: "Charlie", age: 32, author: "App1")
 
     _ = try await processor.processNewTransactionsWithTimestampManagement(
       from: ["App1", "App2"],
       after: lastTimestamp,
-      mergeInto: [mergeContext],
       currentAuthor: "App2")
 
     let countAfterSecondProcess = try await processor.testTransactionCount(
@@ -108,30 +94,24 @@ struct CleanStrategyTests {
       author: "App1",
       testName: "notificationStrategyCleansOnConfiguredCount")
     let userDefaults = TestModelBuilder.createTestUserDefaults()
-    let context1 = container.viewContext
-    context1.transactionAuthor = "App1"
+    let writer = TestAppDataHandler(container: container, viewName: "Writer")
 
-    TestModelBuilder.createPerson(name: "Alice", age: 30, in: context1)
-    try context1.save()
+    try await writer.createPerson(name: "Alice", age: 30, author: "App1")
 
     try await Task.sleep(nanoseconds: 100_000_000)
 
-    TestModelBuilder.createPerson(name: "Bob", age: 31, in: context1)
-    try context1.save()
+    try await writer.createPerson(name: "Bob", age: 31, author: "App1")
 
     let processor = makeProcessor(
       container: container,
       userDefaults: userDefaults,
       cleanStrategy: .byNotification(times: 2))
-    let mergeContext = container.newBackgroundContext()
-    mergeContext.transactionAuthor = "App2"
 
     userDefaults.set(Date(), forKey: "PersistentHistoryTrackingKit.lastToken.App1")
 
     _ = try await processor.processNewTransactionsWithTimestampManagement(
       from: ["App1", "App2"],
       after: nil,
-      mergeInto: [mergeContext],
       currentAuthor: "App2")
 
     let countAfterFirstProcess = try await processor.testTransactionCount(
@@ -144,13 +124,11 @@ struct CleanStrategyTests {
 
     try await Task.sleep(nanoseconds: 100_000_000)
 
-    TestModelBuilder.createPerson(name: "Charlie", age: 32, in: context1)
-    try context1.save()
+    try await writer.createPerson(name: "Charlie", age: 32, author: "App1")
 
     _ = try await processor.processNewTransactionsWithTimestampManagement(
       from: ["App1", "App2"],
       after: lastTimestamp,
-      mergeInto: [mergeContext],
       currentAuthor: "App2")
 
     let countAfterSecondProcess = try await processor.testTransactionCount(
@@ -164,27 +142,21 @@ struct CleanStrategyTests {
     let container = TestModelBuilder.createContainer(
       author: "App1",
       testName: "automaticCleanupWaitsForMissingAuthorTimestamps")
-    let context1 = container.viewContext
-    context1.transactionAuthor = "App1"
+    let writer = TestAppDataHandler(container: container, viewName: "Writer")
 
-    TestModelBuilder.createPerson(name: "Alice", age: 30, in: context1)
-    try context1.save()
+    try await writer.createPerson(name: "Alice", age: 30, author: "App1")
 
     try await Task.sleep(nanoseconds: 100_000_000)
 
-    TestModelBuilder.createPerson(name: "Bob", age: 31, in: context1)
-    try context1.save()
+    try await writer.createPerson(name: "Bob", age: 31, author: "App1")
 
     let processor = makeProcessor(
       container: container,
       cleanStrategy: .byDuration(seconds: 60 * 60))
-    let mergeContext = container.newBackgroundContext()
-    mergeContext.transactionAuthor = "App2"
 
     _ = try await processor.processNewTransactionsWithTimestampManagement(
       from: ["App1", "App2", "App3"],
       after: nil,
-      mergeInto: [mergeContext],
       currentAuthor: "App2")
 
     let remainingCount = try await processor.testTransactionCount(
@@ -200,30 +172,24 @@ struct CleanStrategyTests {
       author: "App1",
       testName: "batchAuthorsDoNotBlockCleanupReadiness")
     let userDefaults = TestModelBuilder.createTestUserDefaults()
-    let context1 = container.viewContext
-    context1.transactionAuthor = "App1"
+    let writer = TestAppDataHandler(container: container, viewName: "Writer")
 
-    TestModelBuilder.createPerson(name: "Alice", age: 30, in: context1)
-    try context1.save()
+    try await writer.createPerson(name: "Alice", age: 30, author: "App1")
 
     try await Task.sleep(nanoseconds: 100_000_000)
 
-    TestModelBuilder.createPerson(name: "Bob", age: 31, in: context1)
-    try context1.save()
+    try await writer.createPerson(name: "Bob", age: 31, author: "App1")
 
     let processor = makeProcessor(
       container: container,
       userDefaults: userDefaults,
       cleanStrategy: .byDuration(seconds: 60 * 60))
-    let mergeContext = container.newBackgroundContext()
-    mergeContext.transactionAuthor = "App2"
 
     userDefaults.set(Date(), forKey: "PersistentHistoryTrackingKit.lastToken.App1")
 
     _ = try await processor.processNewTransactionsWithTimestampManagement(
       from: ["App1", "App2", "BatchProcessor"],
       after: nil,
-      mergeInto: [mergeContext],
       currentAuthor: "App2",
       batchAuthors: ["BatchProcessor"])
 
@@ -245,6 +211,7 @@ struct CleanStrategyTests {
       maximumDuration: 604_800)
     return TransactionProcessorActor(
       container: container,
+      contexts: [container.newBackgroundContext()],
       hookRegistry: hookRegistry,
       cleanStrategy: cleanStrategy,
       timestampManager: timestampManager)