Tic-tac-toe implemented in Bash using a pseudo-functional style with self-contained TDD tools.

./test_tictactoe.sh

Last run: 2026-03-23 · Branch: claude/analyze-test-coverage-KRPNY

[PASSED] - desc_should_return_passed
[PASSED] - desc_should_return_failed
[PASSED] - id_should_return_input_string
[PASSED] - id_should_return_input_number
[PASSED] - can_compare_multiple_word_strings
[PASSED] - testLength
[PASSED] - testHasMoreTrue
[PASSED] - testHasMoreFalse
[PASSED] - testTrueFalse
[PASSED] - testTrueFalseBranchTwo        ← NEW
[PASSED] - testWhenTrue
[PASSED] - testWhenFalse
[PASSED] - testCanCreateGame
[PASSED] - testCanPlaceCross
[PASSED] - testCount
[PASSED] - testInitialNextPlayer
[PASSED] - testNextPlayerAfterCross
[PASSED] - testNextPlayerAfterNought
[PASSED] - testCannotPlaceCrossTwice
[PASSED] - testCanPlaceNoughtAfterCross
[PASSED] - testCannotPlaceNoughtIntoAnOccupiedSpace
[PASSED] - testCannotPlaceNoughtFirst    ← NEW
[PASSED] - testSkip
[PASSED] - testSkipZero                  ← NEW
[PASSED] - testTake
[PASSED] - testTakeZero                  ← NEW
[PASSED] - testWinner
[PASSED] - testCanDetectWinnerAtFirstRow
[PASSED] - testCanDetectWinnerAtSecondRow
[PASSED] - testCanDetectWinnerAtThirdRow
[PASSED] - testSortVertically
[PASSED] - testSortVerticallyAlpha
[PASSED] - testSortItemMultipleOfFour    ← NEW
[PASSED] - testSortItemEven              ← NEW
[PASSED] - testSortItemOdd               ← NEW
[PASSED] - testNearestLower4Multiple     ← NEW
[PASSED] - testNearestHigher4Multiple    ← NEW
[PASSED] - testCanDetectWinnerAtFirstColumn
[PASSED] - testCanDetectWinnerAtSecondColumn
[PASSED] - testCanDetectWinnerAtThirdColumn
[PASSED] - testFilterEven
[PASSED] - testCanDetectWinnerAtDiagonal1
[PASSED] - testFilterMultipleOfFour
[PASSED] - testCanDetectWinnerAtDiagonal2
[PASSED] - testCanDetectNoughtWinner     ← NEW
[PASSED] - testNoWinnerYet               ← NEW
[PASSED] - testDraw                      ← NEW

Function                   Tested?   Tests
─────────────────────────────────────────────────────────
game                         YES    testCanCreateGame
play (valid)                 YES    testCanPlaceCross, testCanPlaceNoughtAfterCross
play (wrong turn)            YES    testCannotPlaceCrossTwice, testCannotPlaceNoughtFirst
play (occupied)              YES    testCannotPlaceNoughtIntoAnOccupiedSpace
nextPlayer (initial)         YES    testInitialNextPlayer
nextPlayer (after X)         YES    testNextPlayerAfterCross
nextPlayer (after O)         YES    testNextPlayerAfterNought
checkWinner (row 0)          YES    testCanDetectWinnerAtFirstRow
checkWinner (row 1)          YES    testCanDetectWinnerAtSecondRow
checkWinner (row 2)          YES    testCanDetectWinnerAtThirdRow
checkWinner (col 0)          YES    testCanDetectWinnerAtFirstColumn
checkWinner (col 1)          YES    testCanDetectWinnerAtSecondColumn
checkWinner (col 2)          YES    testCanDetectWinnerAtThirdColumn
checkWinner (diag ╲)         YES    testCanDetectWinnerAtDiagonal1
checkWinner (diag ╱)         YES    testCanDetectWinnerAtDiagonal2
checkWinner (player 2 wins)  YES    testCanDetectNoughtWinner      ← NEW
checkWinner (no winner yet)  YES    testNoWinnerYet                ← NEW
checkWinner (draw)           YES    testDraw                       ← NEW
winner                       YES    testWinner
take (n > 0)                 YES    testTake
take (n = 0)                 YES    testTakeZero                   ← NEW
skip (n > 0)                 YES    testSkip
skip (n = 0)                 YES    testSkipZero                   ← NEW
sortVertically               YES    testSortVertically, testSortVerticallyAlpha
sortItem (mult. of 4)        YES    testSortItemMultipleOfFour     ← NEW
sortItem (even)              YES    testSortItemEven               ← NEW
sortItem (odd)               YES    testSortItemOdd                ← NEW
nearestLower4Multiple        YES    testNearestLower4Multiple      ← NEW
nearestHigher4Multiple       YES    testNearestHigher4Multiple     ← NEW
filter (isEven)              YES    testFilterEven
filter (isMultipleOfFour)    YES    testFilterMultipleOfFour
count                        YES    testCount
length                       YES    testLength
hasMore (true)               YES    testHasMoreTrue
hasMore (false)              YES    testHasMoreFalse
when (true)                  YES    testWhenTrue
when (false)                 YES    testWhenFalse
trueFalse (branch 1)         YES    testTrueFalse
trueFalse (branch 2)         YES    testTrueFalseBranchTwo         ← NEW
─────────────────────────────────────────────────────────
Total functions:   39   Covered: 39 / 39   Coverage: 100%

checkWinner returns an empty string for both "no winner yet" and "draw". Add a helper that checks if the board is full to distinguish the two cases:

function isBoardFull {
    local -r board=$(read_input)
    [ $(echo "$board" | count "$NONE") -eq 0 ]
}

Printing the raw string 1 _ _ 2 _ _ _ _ _ is hard to read during a game session. A thin formatter would make the project immediately more usable:

function printBoard {
    local -r b=($(read_input))
    echo "+---+---+---+"
    for row in 0 1 2; do
        printf "| %s | %s | %s |\n" ${b[$((row*3))]} ${b[$((row*3+1))]} ${b[$((row*3+2))]}
        echo "+---+---+---+"
    done
}

Wrap game/play/checkWinner into a gameLoop that reads coordinates from stdin:

function gameLoop {
    local board=$(game)
    while true; do
        read -r player row col
        board=$(echo "$board" | play "$player" "$row" "$col")
        echo "$board" | printBoard
        local w=$(echo "$board" | checkWinner)
        [ -n "$w" ] && echo "Winner: $w" && break
    done
}

The heavy use of subshells ($(...)) and recursive calls in filter/winner adds noticeable overhead. Three concrete options:

ORDER=3 is a constant, but sortItem's math already generalises. Expose it as an argument to game and test for a 4×4 board to prove the invariant holds beyond 3×3.

assert_that $(expr) | is "expected"

The assert_that / is pair models an expectation builder entirely in Bash. assert_that evaluates an expression and writes its output; is reads from stdin and compares. This avoids global state and is composable.

Reusable in any Bash project that has functions returning values through echo. Examples: config parsers, file processors, CLI tools.

test_tools.sh is sourced before game code. The framework itself has tests (desc_should_return_passed, id_should_return_input_string, …). This "test the tests" bootstrap gives confidence that assertion failures are real, not framework bugs.

Reuse tip: copy test_tools.sh as a minimal dependency into any shell project that cannot install bats or shunit2.

Game state is a string (1 _ _ 2 _ _ _ _ _). Tests assert the whole board string, not just one cell. This documents the full observable effect of each operation and catches accidental side effects.

Reuse tip: wherever your Bash function produces a structured string (CSV line, JSON fragment, log record), test the exact output string. Avoid partial matching unless intentional.

testSkipZero, testTakeZero, testNearestLower4Multiple test n = 0 and border values around multiples. Standard boundary-value analysis applied to arithmetic Bash functions.

Reuse tip: every $((...)) expression in shell scripts has edge cases (integer division, modulo of 0, negative numbers). Always add a test for n = 0, n = 1, and the first value that crosses a branch.

filter isEven and filter isMultipleOfFour pass a function name as a string. This simulates higher-order functions in Bash. Tests for sortItem cover all three branches of the dispatching logic independently.

Reuse tip: if a Bash function accepts a callback name, write one test per callback variant. Mock the callback with a trivial echo function to isolate the routing logic from the callback logic.

testCanDetectNoughtWinner, testDraw, and testNoWinnerYet compose multiple play calls into a scenario and assert the final state. This is scenario-based / black-box testing layered on top of unit tests.

Reuse tip: after unit-testing all primitives, write at least three scenario tests: happy path, edge case, failure case. For a game engine, that maps to someone wins, draw, invalid input.

• Start functional, stay functional. You chose to avoid if/else in favour of trueFalse + when, and avoided global mutable state entirely. This was a deliberate exploration of how far pure composition goes in Bash.
• TDD from the very first function. The test framework was built before (or alongside) the game code. The game functions were shaped by what was easy to assert, not the other way around.
• Pipe as the data bus. Every function reads from stdin and writes to stdout. This mirrors the Unix philosophy and allows arbitrary chaining: game | play 1 0 0 | play 2 1 1 | checkWinner.
• sortVertically as the cleverness peak. The index-math trick in sortItem (using nearest multiples of 4) is the most non-obvious piece. You probably spent the most design time here.

1. Add a checkDraw function that returns "draw" when the board is full and checkWinner is empty. One test needed: testCheckDraw.

2. Write a game loop script (play.sh) that calls gameLoop and lets two humans play in a terminal — the engine is complete, only the UI wrapper is missing.

3. Write the tutorial (listed in TODO). The commit history and test names already tell the story; the tutorial would be: one test → one function → next test. The pipe-based style is genuinely unusual and worth documenting.

4. Publish to GitHub Pages or similar with an automatically updated test badge. The CI pipeline would be: bash test_tictactoe.sh | tee results.txt, with the result embedded in the README via a GitHub Action.

5. Profile the test run (time bash test_tictactoe.sh) and identify the slowest three tests. Replace the recursive filter with a loop and measure the speedup — this directly addresses the "Test execution is slow" TODO.

6. Generalise to N×N — try ORDER=4 and add testCanDetectWinnerAtRow_4x4. The sortItem math already hints at a general formula.

Gap worth noting: existing Bash tic-tac-toe implementations are all imperative with no tests. A functionally-styled, TDD-driven implementation like this one fills a real gap in the space.

stdin ──► game ──► play ──► play ──► ... ──► checkWinner ──► stdout
              │         │                         │
              │   nextPlayer (validation)          │
              │   count / when / trueFalse         │
              │                             sortVertically
              │                             filter isEven
              │                             filter isMultipleOfFour
              │                             winner (recursive)
              └─ board: space-separated 9-cell string (immutable)

All state flows through stdout. No global variables are mutated after init.

1. Add checkDraw function and tests
2. Document the process of analysis and implementation (tutorial)
3. Build interactive game loop (play.sh)
4. Fix test execution speed (profile + replace recursive filter with loop)
5. Generalise to N×N board
6. Add CI badge with auto-updated test results