crossmate

GameMutatorTests.swift (21401B)

---

 import CoreData
 import Foundation
 import Testing
 
 @testable import Crossmate
 
 @Suite("GameMutator", .serialized)
 @MainActor
 struct GameMutatorTests {
 
     // MARK: - Basic mutations
 
     @Test("setLetter writes entry and mark to game")
     func setLetterWritesToGame() throws {
         let (game, mutator, _, _) = try makeTestGame()
 
         mutator.setLetter("A", atRow: 0, atCol: 0, pencil: false)
 
         #expect(game.squares[0][0].entry == "A")
         #expect(game.squares[0][0].mark == .none)
     }
 
     @Test("setLetter in pencil mode sets pencil mark")
     func setLetterPencilMode() throws {
         let (game, mutator, _, _) = try makeTestGame()
 
         mutator.setLetter("B", atRow: 0, atCol: 1, pencil: true)
 
         #expect(game.squares[0][1].entry == "B")
         #expect(game.squares[0][1].mark == .pencil(checked: nil))
     }
 
     @Test("clearLetter clears entry and mark")
     func clearLetterClearsEntry() throws {
         let (game, mutator, _, _) = try makeTestGame()
 
         mutator.setLetter("A", atRow: 0, atCol: 0, pencil: false)
         mutator.clearLetter(atRow: 0, atCol: 0)
 
         #expect(game.squares[0][0].entry == "")
         #expect(game.squares[0][0].mark == .none)
         #expect(game.squares[0][0].letterAuthorID == nil)
     }
 
     @Test("A version 2 edit advances the largest observed logical tick")
     func versionTwoEditAdvancesLogicalTick() async throws {
         let (game, capture, updater, persistence) = try makeMutatorWithUpdater(
             actingAuthorID: "bob"
         )
         let mutator = GameMutator(
             game: game,
             gameID: capture.gameID,
             movesUpdater: updater,
             authorIDProvider: { "bob" },
             syncVersion: GameSyncVersion.logicalTicks,
             initialLogicalTick: 2_000_000
         )
 
         mutator.setLetter("M", atRow: 0, atCol: 0, pencil: false)
         try await waitForEmittedGameID(
             capture.gameID,
             updater: updater,
             collector: capture.collector
         )
 
         let persisted = try cellFromMoves(
             persistence: persistence,
             gameID: capture.gameID,
             row: 0,
             col: 0
         )
         let cell = try #require(persisted)
         #expect(cell.tick == 2_000_001)
     }
 
     @Test("A version 1 edit remains timestamp-only")
     func versionOneEditHasNoLogicalTick() async throws {
         let (game, capture, updater, persistence) = try makeMutatorWithUpdater(
             actingAuthorID: "bob"
         )
         let mutator = GameMutator(
             game: game,
             gameID: capture.gameID,
             movesUpdater: updater,
             authorIDProvider: { "bob" },
             syncVersion: GameSyncVersion.legacy
         )
 
         mutator.setLetter("N", atRow: 0, atCol: 0, pencil: false)
         try await waitForEmittedGameID(
             capture.gameID,
             updater: updater,
             collector: capture.collector
         )
 
         let persisted = try cellFromMoves(
             persistence: persistence,
             gameID: capture.gameID,
             row: 0,
             col: 0
         )
         let cell = try #require(persisted)
         #expect(cell.tick == nil)
     }
 
     @Test("A completed mutator rejects every mutation")
     func completedMutatorIsReadOnly() throws {
         let (game, _, _, persistence) = try makeTestGame()
         let mutator = GameMutator(
             game: game,
             gameID: UUID(),
             movesUpdater: nil,
             movesJournal: MovesJournal(persistence: persistence),
             isCompleted: true
         )
 
         // Single-cell input is a no-op.
         mutator.setLetter("A", atRow: 0, atCol: 0, pencil: false)
         #expect(game.squares[0][0].entry == "")
 
         // Bulk help/clear gestures are no-ops too.
         mutator.revealCells([game.puzzle.cells[0][0]])
         #expect(game.squares[0][0].entry == "")
         mutator.checkCells([game.puzzle.cells[0][2]])
         mutator.clearCells([game.puzzle.cells[0][2]])
         #expect(game.squares[0][2].entry == "")
 
         // Undo/redo are disabled and inert.
         #expect(mutator.canUndo == false)
         #expect(mutator.canRedo == false)
         #expect(mutator.undo() == nil)
         #expect(mutator.redo() == nil)
     }
 
     @Test("A revoked mutator rejects every mutation")
     func revokedMutatorIsReadOnly() throws {
         let (game, _, _, persistence) = try makeTestGame()
         let mutator = GameMutator(
             game: game,
             gameID: UUID(),
             movesUpdater: nil,
             movesJournal: MovesJournal(persistence: persistence),
             isAccessRevoked: true
         )
 
         // Revocation blocks the in-memory mutation itself, not just the sync
         // emit — no letter may even appear on the revoked copy.
         mutator.setLetter("A", atRow: 0, atCol: 0, pencil: false)
         #expect(game.squares[0][0].entry == "")
 
         // Bulk help/clear gestures are no-ops too.
         mutator.revealCells([game.puzzle.cells[0][0]])
         #expect(game.squares[0][0].entry == "")
         mutator.checkCells([game.puzzle.cells[0][2]])
         mutator.clearCells([game.puzzle.cells[0][2]])
         #expect(game.squares[0][2].entry == "")
 
         // Undo/redo are disabled and inert.
         #expect(mutator.canUndo == false)
         #expect(mutator.canRedo == false)
         #expect(mutator.undo() == nil)
         #expect(mutator.redo() == nil)
     }
 
     @Test("An unsupported sync version rejects every mutation")
     func unsupportedSyncVersionIsReadOnly() throws {
         let (game, _, _, persistence) = try makeTestGame()
         let mutator = GameMutator(
             game: game,
             gameID: UUID(),
             movesUpdater: nil,
             movesJournal: MovesJournal(persistence: persistence),
             isSyncSupported: false
         )
 
         mutator.setLetter("A", atRow: 0, atCol: 0, pencil: false)
         mutator.revealCells([game.puzzle.cells[0][0]])
 
         #expect(game.squares[0][0].entry == "")
         #expect(mutator.canUndo == false)
         #expect(mutator.canRedo == false)
         #expect(mutator.undo() == nil)
         #expect(mutator.redo() == nil)
     }
 
     // MARK: - Bulk mutations
 
     @Test("checkCells marks wrong entries via mutator")
     func checkCellsMarksWrong() throws {
         let (game, mutator, _, _) = try makeTestGame()
 
         // Cell (0,0) has solution "A", enter "Z"
         mutator.setLetter("Z", atRow: 0, atCol: 0, pencil: false)
         mutator.checkCells([game.puzzle.cells[0][0]])
 
         #expect(game.squares[0][0].mark == .pen(checked: .wrong))
     }
 
     @Test("checkCells inks correct pencil entries")
     func checkCellsStampsCorrectPencilEntries() throws {
         let (game, mutator, _, _) = try makeTestGame()
 
         // Cell (0,0) has solution "A"; checking a correct draft commits it to ink.
         mutator.setLetter("A", atRow: 0, atCol: 0, pencil: true)
         mutator.checkCells([game.puzzle.cells[0][0]])
 
         #expect(game.squares[0][0].mark == .pen(checked: .right))
     }
 
     @Test("checkCells keeps wrong pencil entries penciled")
     func checkCellsKeepsWrongPencilEntriesPenciled() throws {
         let (game, mutator, _, _) = try makeTestGame()
 
         // Cell (0,0) has solution "A"; wrong drafts stay tentative after check.
         mutator.setLetter("Z", atRow: 0, atCol: 0, pencil: true)
         mutator.checkCells([game.puzzle.cells[0][0]])
 
         #expect(game.squares[0][0].mark == .pencil(checked: .wrong))
     }
 
     @Test("checking an empty puzzle emits no empty cell moves")
     func checkingEmptyPuzzleEmitsNoEmptyCellMoves() async throws {
         let (game, capture, updater, persistence) = try makeMutatorWithUpdater(actingAuthorID: "bob")
         let mutator = makeMutator(
             game: game,
             updater: updater,
             gameID: capture.gameID,
             actingAuthorID: "bob"
         )
 
         mutator.checkCells(game.puzzle.cells.flatMap { $0 })
         await updater.flush()
 
         #expect(await capture.collector.allGameIDs.isEmpty)
         #expect(try cellFromMoves(
             persistence: persistence,
             gameID: capture.gameID,
             row: 0,
             col: 0
         ) == nil)
     }
 
     @Test("revealCells sets entry to solution and marks revealed")
     func revealCellsSetsAnswer() throws {
         let (game, mutator, _, _) = try makeTestGame()
 
         mutator.revealCells([game.puzzle.cells[0][0]])
 
         #expect(game.squares[0][0].entry == "A")
         #expect(game.squares[0][0].mark == .revealed)
     }
 
     @Test("revealCells leaves correct entries unmarked")
     func revealCellsSkipsCorrectEntries() throws {
         let (game, mutator, _, _) = try makeTestGame()
 
         // Cell (0,0) has solution "A" — user already entered it correctly in pen.
         mutator.setLetter("A", atRow: 0, atCol: 0, pencil: false)
         mutator.revealCells([game.puzzle.cells[0][0]])
 
         #expect(game.squares[0][0].entry == "A")
         #expect(game.squares[0][0].mark == .none)
     }
 
     @Test("revealCells preserves pencil mark on correct entries")
     func revealCellsPreservesPencilOnCorrect() throws {
         let (game, mutator, _, _) = try makeTestGame()
 
         mutator.setLetter("A", atRow: 0, atCol: 0, pencil: true)
         mutator.revealCells([game.puzzle.cells[0][0]])
 
         #expect(game.squares[0][0].entry == "A")
         #expect(game.squares[0][0].mark == .pencil(checked: nil))
     }
 
     @Test("revealCells overwrites wrong entries and marks them revealed")
     func revealCellsOverwritesWrong() throws {
         let (game, mutator, _, _) = try makeTestGame()
 
         mutator.setLetter("Z", atRow: 0, atCol: 0, pencil: false)
         mutator.revealCells([game.puzzle.cells[0][0]])
 
         #expect(game.squares[0][0].entry == "A")
         #expect(game.squares[0][0].mark == .revealed)
     }
 
     @Test("fill quarter reveals a quarter of empty fillable cells")
     func fillQuarterRevealsQuarterOfRemainingCells() throws {
         let (game, mutator, _, _) = try makeTestGame()
         let session = PlayerSession(game: game, mutator: mutator)
 
         session.fillQuarter()
 
         #expect(revealedCellCount(in: game) == 2)
         #expect(revealedCells(in: game).allSatisfy { cell in
             game.squares[cell.row][cell.col].entry == cell.solution?.uppercased()
         })
     }
 
     @Test("fill half counts only still-empty cells")
     func fillHalfCountsOnlyEmptyRemainingCells() throws {
         let (game, mutator, _, _) = try makeTestGame()
         let session = PlayerSession(game: game, mutator: mutator)
 
         mutator.setLetter("A", atRow: 0, atCol: 0, pencil: false)
         mutator.setLetter("B", atRow: 0, atCol: 1, pencil: false)
         mutator.setLetter("C", atRow: 0, atCol: 2, pencil: false)
         mutator.setLetter("D", atRow: 1, atCol: 0, pencil: false)
 
         session.fillHalf()
 
         #expect(revealedCellCount(in: game) == 2)
         #expect(revealedCells(in: game).allSatisfy { cell in
             game.squares[cell.row][cell.col].entry == cell.solution?.uppercased()
         })
         #expect(!game.squares[0][0].mark.isRevealed)
         #expect(!game.squares[0][1].mark.isRevealed)
         #expect(!game.squares[0][2].mark.isRevealed)
         #expect(!game.squares[1][0].mark.isRevealed)
     }
 
     @Test("clearCells clears non-revealed cells")
     func clearCellsClearsNonRevealed() throws {
         let (game, mutator, _, _) = try makeTestGame()
 
         mutator.setLetter("X", atRow: 0, atCol: 0, pencil: false)
         mutator.clearCells([game.puzzle.cells[0][0]])
 
         #expect(game.squares[0][0].entry == "")
         #expect(game.squares[0][0].mark == .none)
     }
 
     // MARK: - Completion
 
     @Test("completion state updates incrementally as entries change")
     func completionStateUpdatesIncrementally() throws {
         let (game, mutator, _, _) = try makeTestGame()
 
         mutator.setLetter("A", atRow: 0, atCol: 0, pencil: false)
         mutator.setLetter("B", atRow: 0, atCol: 1, pencil: false)
         mutator.setLetter("C", atRow: 0, atCol: 2, pencil: false)
         mutator.setLetter("D", atRow: 1, atCol: 0, pencil: false)
         mutator.setLetter("E", atRow: 1, atCol: 2, pencil: false)
         mutator.setLetter("F", atRow: 2, atCol: 0, pencil: false)
         mutator.setLetter("G", atRow: 2, atCol: 1, pencil: false)
 
         #expect(game.completionState == .incomplete)
 
         mutator.setLetter("Z", atRow: 2, atCol: 2, pencil: false)
         #expect(game.completionState == .filledWithErrors)
 
         mutator.setLetter("H", atRow: 2, atCol: 2, pencil: false)
         #expect(game.completionState == .solved)
 
         mutator.clearLetter(atRow: 0, atCol: 0)
         #expect(game.completionState == .incomplete)
     }
 
     @Test("reveal and clear keep completion cache in sync")
     func revealAndClearKeepCompletionCacheInSync() throws {
         let (game, mutator, _, _) = try makeTestGame()
 
         mutator.revealCells(game.puzzle.cells.flatMap { $0 })
         #expect(game.completionState == .solved)
 
         mutator.clearCells(game.puzzle.cells.flatMap { $0 })
         #expect(game.completionState == .solved)
     }
 
     // MARK: - Author preservation
 
     @Test("setLetter preserves the existing author when the letter is unchanged")
     func setLetterSameLetterPreservesAuthor() throws {
         let (game, _, _, _) = try makeTestGame()
         game.setLetter("A", atRow: 0, atCol: 0, pencil: false, authorID: "alice")
 
         game.setLetter("A", atRow: 0, atCol: 0, pencil: false, authorID: "bob")
 
         #expect(game.squares[0][0].entry == "A")
         #expect(game.squares[0][0].letterAuthorID == "alice")
     }
 
     @Test("setLetter normalises case before deciding whether the letter changed")
     func setLetterSameLetterCaseInsensitivePreservesAuthor() throws {
         let (game, _, _, _) = try makeTestGame()
         game.setLetter("A", atRow: 0, atCol: 0, pencil: false, authorID: "alice")
 
         game.setLetter("a", atRow: 0, atCol: 0, pencil: false, authorID: "bob")
 
         #expect(game.squares[0][0].letterAuthorID == "alice")
     }
 
     @Test("setLetter overwrites the author when the letter changes")
     func setLetterDifferentLetterOverwritesAuthor() throws {
         let (game, _, _, _) = try makeTestGame()
         game.setLetter("A", atRow: 0, atCol: 0, pencil: false, authorID: "alice")
 
         game.setLetter("B", atRow: 0, atCol: 0, pencil: false, authorID: "bob")
 
         #expect(game.squares[0][0].entry == "B")
         #expect(game.squares[0][0].letterAuthorID == "bob")
     }
 
     @Test("revealCells preserves the existing author for cells already correct")
     func revealCellsPreservesAuthorOnCorrect() throws {
         let (game, _, _, _) = try makeTestGame()
         // Cell (0,0) has solution "A".
         game.setLetter("A", atRow: 0, atCol: 0, pencil: false, authorID: "alice")
 
         game.revealCells([game.puzzle.cells[0][0]])
 
         #expect(game.squares[0][0].entry == "A")
         #expect(game.squares[0][0].letterAuthorID == "alice")
     }
 
     // MARK: - Move emission carries the cell-effective author
 
     @Test("Same-letter rewrite emits a move carrying the preserved author, not the acting user")
     func sameLetterEmitsMoveWithPreservedAuthor() async throws {
         let (game, capture, updater, persistence) = try makeMutatorWithUpdater(actingAuthorID: "bob")
 
         // Alice already entered "A" — seed via Game directly so the updater
         // only sees Bob's subsequent action.
         game.setLetter("A", atRow: 0, atCol: 0, pencil: false, authorID: "alice")
 
         let mutator = makeMutator(
             game: game,
             updater: updater,
             gameID: capture.gameID,
             actingAuthorID: "bob"
         )
         mutator.setLetter("A", atRow: 0, atCol: 0, pencil: false)
 
         try await waitForEmittedGameID(
             capture.gameID,
             updater: updater,
             collector: capture.collector
         )
 
         let affected = await capture.collector.allGameIDs
         #expect(affected.contains(capture.gameID))
         let cell = try cellFromMoves(
             persistence: persistence,
             gameID: capture.gameID,
             row: 0,
             col: 0
         )
         #expect(cell?.letter == "A")
         #expect(cell?.authorID == "alice")
         #expect(game.squares[0][0].letterAuthorID == "alice")
     }
 
     @Test("Reveal of an already-correct cell emits a move carrying the preserved author")
     func revealCorrectEmitsMoveWithPreservedAuthor() async throws {
         let (game, capture, updater, persistence) = try makeMutatorWithUpdater(actingAuthorID: "bob")
 
         // Cell (0,0)'s solution is "A". Alice has already filled it in.
         game.setLetter("A", atRow: 0, atCol: 0, pencil: false, authorID: "alice")
 
         let mutator = makeMutator(
             game: game,
             updater: updater,
             gameID: capture.gameID,
             actingAuthorID: "bob"
         )
         mutator.revealCells([game.puzzle.cells[0][0]])
 
         try await waitForEmittedGameID(
             capture.gameID,
             updater: updater,
             collector: capture.collector
         )
 
         let affected = await capture.collector.allGameIDs
         #expect(affected.contains(capture.gameID))
         let cell = try cellFromMoves(
             persistence: persistence,
             gameID: capture.gameID,
             row: 0,
             col: 0
         )
         #expect(cell?.authorID == "alice")
         #expect(game.squares[0][0].letterAuthorID == "alice")
         // The cell was already correct, so it is not locked into `.revealed`.
         #expect(game.squares[0][0].mark == .none)
     }
 
     // MARK: - Test scaffolding for emission tests
 
     actor GameIDCollector {
         private(set) var allGameIDs: Set<UUID> = []
         func append(_ ids: Set<UUID>) { allGameIDs.formUnion(ids) }
     }
 
     /// Polls `updater.flush()` until the collector sees `gameID`. `setLetter`
     /// and friends spawn an internal Task to call `updater.enqueue`; if the
     /// test flushed before that Task landed it would see an empty buffer.
     /// Each iteration re-flushes so the first flush after the enqueue lands
     /// reaches the sink; total wall-clock is typically <10ms versus the
     /// previous fixed 50ms grace period.
     private func waitForEmittedGameID(
         _ gameID: UUID,
         updater: MovesUpdater,
         collector: GameIDCollector,
         timeout: Duration = .seconds(2)
     ) async throws {
         let deadline = ContinuousClock.now.advanced(by: timeout)
         while ContinuousClock.now < deadline {
             await updater.flush()
             if await collector.allGameIDs.contains(gameID) { return }
             try await Task.sleep(for: .milliseconds(5))
         }
     }
 
     struct UpdaterHarness {
         let collector: GameIDCollector
         let gameID: UUID
     }
 
     /// Builds a `Game` plus a `MovesUpdater` whose sink is captured. Returns
     /// the game, the capture harness, the updater, and the persistence
     /// controller (so the test can read back the persisted MovesEntity).
     private func makeMutatorWithUpdater(
         actingAuthorID: String
     ) throws -> (Game, UpdaterHarness, MovesUpdater, PersistenceController) {
         let (game, _, entity, persistence) = try makeTestGame()
         let collector = GameIDCollector()
         let updater = MovesUpdater(
             debounceInterval: .seconds(10),
             persistence: persistence,
             writerAuthorIDProvider: { actingAuthorID },
             sink: { ids, _ in await collector.append(ids) }
         )
         let gameID = entity.id ?? UUID()
         return (game, UpdaterHarness(collector: collector, gameID: gameID), updater, persistence)
     }
 
     private func makeMutator(
         game: Game,
         updater: MovesUpdater,
         gameID: UUID,
         actingAuthorID: String
     ) -> GameMutator {
         GameMutator(
             game: game,
             gameID: gameID,
             movesUpdater: updater,
             authorIDProvider: { actingAuthorID }
         )
     }
 
     private func revealedCellCount(in game: Game) -> Int {
         game.squares.flatMap { $0 }.filter { $0.mark.isRevealed }.count
     }
 
     private func revealedCells(in game: Game) -> [Puzzle.Cell] {
         game.puzzle.cells.flatMap { $0 }.filter { cell in
             game.squares[cell.row][cell.col].mark.isRevealed
         }
     }
 
     /// Reads back the per-cell entry at `(row, col)` from the local-device
     /// MovesEntity for `gameID`. Used by emission tests to verify what got
     /// persisted into the cells blob.
     private func cellFromMoves(
         persistence: PersistenceController,
         gameID: UUID,
         row: Int,
         col: Int
     ) throws -> TimestampedCell? {
         let ctx = persistence.viewContext
         let req = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
         req.predicate = NSPredicate(
             format: "game.id == %@ AND deviceID == %@",
             gameID as CVarArg,
             RecordSerializer.localDeviceID
         )
         req.fetchLimit = 1
         ctx.refreshAllObjects()
         guard let entity = try ctx.fetch(req).first,
               let data = entity.cells
         else { return nil }
         let cells = try MovesCodec.decode(data)
         return cells[GridPosition(row: row, col: col)]
     }
 }