test: parallelize and stabilize suite

Author: fatbobman

.github/workflows/ci.yml

@@ -28,5 +28,5 @@ jobs:
       - name: Build
         run: swift build --enable-experimental-prebuilts
 
-      - name: Test
+      - name: Test (Parallel)
         run: bash test.sh --enable-experimental-prebuilts

AGENT.md

@@ -15,23 +15,26 @@
 
 ## Test Guidance
 
-- Command-line full test runs should use serial execution:
-  - `swift test --no-parallel`
+- Command-line full test runs should use parallel execution:
+  - `swift test --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.
+- Swift Testing parallel runs should be treated as same-process concurrency, not process isolation per test case.
+- Do not assume `static` state is isolated per test. Static helpers in the test target are shared across concurrently running suites.
 - 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.
+- Prefer real test data and the actual transaction-processing path over synthetic Core Data artifacts. Do not hand-build `HookContext`, `NSManagedObjectID`, or similar fake inputs when a test can create data through `TestAppDataHandler` and trigger processing through the library.
 
 ## Known Test Constraints
 
-- Full-suite parallel execution in Xcode can hang before any individual test completes.
-- Serial full-suite execution has been verified to pass repeatedly.
+- Full-suite parallel execution has been revalidated after test-infrastructure fixes.
+- Repeated parallel runs have been observed to pass after serializing test container creation.
 - Repeated Xcode runs of `cleanTransactionsByTimestampAndAuthors` have been observed to pass.
-- Repeated Xcode serial full-suite runs have also been observed to pass.
+- `TestModelBuilder.createContainer` is intentionally serialized with a global lock.
+- Reason: concurrent `NSPersistentContainer` creation and `loadPersistentStores` can crash inside Core Data with `EXC_BAD_ACCESS`, even when each test uses a unique SQLite store URL.
+- The container creation lock is required for test stability; do not remove it unless the Core Data initialization path is reworked and revalidated under repeated parallel runs.
 
 ## Failure Triage
 
@@ -46,7 +49,7 @@ If a crash or hang appears again, collect the following before changing code:
 ## Build and Cache Notes
 
 - If SwiftPM reports compiler/module version mismatches, clear `.build` and rerun.
-- If Xcode behaves inconsistently while command-line serial runs are stable, suspect DerivedData or Xcode test execution settings before changing repository code.
+- If Xcode behaves inconsistently while command-line parallel runs are stable, suspect DerivedData or Xcode test execution settings before changing repository code.
 
 ## Version Tag Rule
 

README.md

@@ -1,4 +1,4 @@
-# Persistent History Tracking Kit
+# Persistent History Tracking Kit 2
 
 **Swift 6 ready** • **Actor-based** • **Fully concurrent** • **Type-safe**
 
@@ -503,33 +503,31 @@ let hookB = await kit.registerMergeHook(before: hookA) { _ in
 
 ## Testing
 
-**⚠️ Important: Tests Must Run Serially**
-
-Due to Core Data's singleton nature and shared persistent stores, **tests must run serially**, not in parallel. Running tests in parallel will cause race conditions and failures.
+Tests are validated under parallel execution. The test infrastructure serializes `NSPersistentContainer` creation internally to avoid Core Data store-loading crashes while preserving parallel suite execution.
 
 ### Recommended: Use the test script
 
 ```bash
-# Run all tests serially (recommended)
+# Run all tests in parallel (recommended)
 ./test.sh
 ```
 
 The test script ensures:
 
-- ✅ All tests run sequentially
-- ✅ Proper cleanup between test suites
+- ✅ Full-suite parallel execution
+- ✅ Core Data concurrency assertions enabled
 - ✅ Reliable results
 
 ### Alternative: Manual testing (caution required)
 
-If you run tests manually, use filters with caution:
+If you run tests manually, prefer the same parallel settings:
 
 ```bash
-# ⚠️ Only use this for individual test suites
-swift test --filter HookRegistryActorTests
+# Run the full suite in parallel
+swift test --parallel
 
-# ❌ AVOID: Running all tests may cause failures due to Core Data conflicts
-swift test  # May fail - use test.sh instead
+# Or run an individual suite
+swift test --filter HookRegistryActorTests
 ```
 
 Test suites include:

READMECN.md

@@ -1,4 +1,4 @@
-# Persistent History Tracking Kit
+# Persistent History Tracking Kit 2
 
 **适配 Swift 6** • **Actor 架构** • **并发安全** • **类型安全**
 
@@ -385,13 +385,18 @@ let hookB = await kit.registerMergeHook(before: hookA) { _ in print("Hook B"); r
 
 ## 测试
 
-> **重要：测试必须串行执行**。Core Data 共享同一存储，若并发运行测试可能发生竞争导致失败。
+> 测试现已验证可并行执行。测试基础设施会在内部串行化 `NSPersistentContainer` 的创建，以规避 Core Data 在并发加载存储时的崩溃，同时保留 suite 级并行执行。
 
 ```bash
-./test.sh   # 推荐脚本，自动串行化
+./test.sh   # 推荐脚本，自动启用并行测试
 ```
 
-如需手动运行，请仅针对单个测试集使用 `swift test --filter ...`。
+如需手动运行，建议使用：
+
+```bash
+swift test --parallel
+swift test --filter HookRegistryActorTests
+```
 
 ---
 

Tests/PersistentHistoryTrackingKitTests/CleanStrategyTests.swift

@@ -10,7 +10,7 @@ import Testing
 
 @testable import PersistentHistoryTrackingKit
 
-@Suite("Clean Strategy Tests", .serialized)
+@Suite("Clean Strategy Tests")
 struct CleanStrategyTests {
   @Test("None strategy disables automatic cleanup")
   func noneStrategyDisablesAutomaticCleanup() async throws {

Tests/PersistentHistoryTrackingKitTests/ConcurrencyTests.swift

@@ -10,7 +10,7 @@ import Testing
 
 @testable import PersistentHistoryTrackingKit
 
-@Suite("Concurrency Safety Tests", .serialized)
+@Suite("Concurrency Safety Tests")
 struct ConcurrencyTests {
   @Test("Multithreaded concurrent writes")
   func concurrentWrites() async throws {