// TODO: Test
function getActions(gameState) {

Commit: "Remove resolved TODO comment".

Alright. Okay. Let's start off by copy-pasting the part we got to last time, before we stumbled into the action legality issue, and merging it with our new isLegalAction() code:

// index.js
function resolveAction(gameState, action) {
    let resultingGameState = {
        ...gameState,
        block: gameState.block + 5,
        energy: gameState.energy - 1
    };
    return [{ gameState: resultingGameState, probability: 1 }];
}

// ... snipped code ...

// Export in Node.js for testing
if (typeof module === 'object' && module != null && 'exports' in module) {
    module.exports = { getActions, isLegalAction, resolveAction };
}

// test.mjs
import { getActions, isLegalAction, resolveAction } from './index.js';

// ... snipped code ...

describe('resolveAction()', () => {
    it('resolves Defend', () => {
        fc.assert(
            fc.property(getArbGameState(), gameState => {
                let action = { name: 'Play Defend' };
                let result = resolveAction(gameState, action);
                let sumOfProbabilities = result.reduce((acc, x) => acc + x.probability, 0);
                assert.equal(sumOfProbabilities, 1);
                for (let outcome of result) {
                    assert.equal(outcome.gameState.block, gameState.block + 5);
                    assert.equal(outcome.gameState.energy, gameState.energy - 1);

                    let firstDefendIndex = gameState.hand.indexOf('Defend');
                    let expectedHand = gameState.hand.toSpliced(firstDefendIndex, 1);
                    assert.deepEqual(outcome.gameState.hand, expectedHand);
                }
            })
        );
    });
});

A few things to note:

• resolveAction() only handles "Play Defend", and even that is only half-implemented, we still need to move Defend from the hand to the discard pile.
• The test is currently trying to assert that Defend is removed from the hand.
• The test looks like a mess to me, oh moly.
• We are still trying to resolve "Play Defend" for game states where it isn't legal.

Let's comment out that last section of the assertion loop (shudder) so we get a passing test, and make resolveAction() handle illegal actions in a helpful way. For ease of debugging, resolveAction() should always check if the action is legal, and if not, throw an error (this is inefficient, but we'll worry about performance when we have a working system).

for (let outcome of result) {
    assert.equal(outcome.gameState.block, gameState.block + 5);
    assert.equal(outcome.gameState.energy, gameState.energy - 1);

    // TODO:
    // - Remove Defend from hand
    // - Add Defend to discard pile
    // let firstDefendIndex = gameState.hand.indexOf('Defend');
    // let expectedHand = gameState.hand.toSpliced(firstDefendIndex, 1);
    // assert.deepEqual(outcome.gameState.hand, expectedHand);
}

Cool, passing tests. Add a new failing test: resolveAction() should throw errors for illegal moves.

it('throws an error when the action is illegal', () => {
    fc.assert(
        fc.property(getArbGameState(), arbAction, (gameState, action) => {
            fc.pre(!isLegalAction(gameState, action));

            let error = null;
            try {
                resolveAction(gameState, action);
            } catch (e) {
                error = e;
            }

            assert.ok(error);
            assert.match(error.message, /illegal action/);
        })
    );
});

fc.pre() comes in handy here to filter for illegal gameState-action combinations in one swing. Now, this test fails immediately on assert.ok(error) because error is falsy. Let's try to fix it in one swing:

function resolveAction(gameState, action) {
    if (!isLegalAction(gameState, action)) throw new Error('Cannot resolve an illegal action');

    let resultingGameState = {
        ...gameState,
        block: gameState.block + 5,
        energy: gameState.energy - 1
    };

    return [{ gameState: resultingGameState, probability: 1 }];
}

Hey, the test passes now, but "resolves Defend" fails now. Let's make "Play Defend" being legal a precondition:

it('resolves Defend', () => {
    fc.assert(
        fc.property(getArbGameState(), gameState => {
            let action = { name: 'Play Defend' };
            fc.pre(isLegalAction(gameState, action));
            // ... rest of test ...
        })
    );
});

There we go, test passes again. Though I'm curious - my editor told me the Error constructor has a second "options" parameter? Could we pass more useful context there, like what the illegal gameState plus action was?

MDN says no. That's disappointing. Maybe we can make an error subclass for that instead, then? Is that allowed?

class IllegalActionError extends Error {
    constructor(gameState, action) {
        super('IllegalActionError: Tried to resolve a game state with an illegal action.')
        this.gameState = gameState;
        this.action = action;
    }
}

if (!isLegalAction(gameState, action)) throw new IllegalActionError(gameState, action);

That works, but will the properties show in my test runner when a test fails? Let's remove the if-check and always throw an error on resolveAction() to find out.

  Error: Property failed after 1 tests
  { seed: 1896921034, path: "0:0:1:0:4:3:3:3", endOnFailure: true }
  Counterexample: [{"hp":1,"maxHp":80,"block":0,"energy":1,"maxEnergy":3,"hand":["Defend"],"drawPile":[],"discardPile":[],"relics":[],"enemies":[{"name":"Jaw Worm","hp":42,"maxHp":42,"block":0,"nextMove":[],"moveHistory":[],"buffs":[],"debuffs":[]}]}]
  Shrunk 7 time(s)
  
  Hint: Enable verbose mode in order to have the list of all failing values encountered during the run
      -- snipped stack trace -- {
    [cause]: Error: IllegalActionError: Tried to resolve a game state with an illegal action.
        -- snipped stack trace -- {
      gameState: { hp: 1, maxHp: 80, block: 0, energy: 1, maxEnergy: 3, hand: [Array], drawPile: [], discardPile: [], relics: [], enemies: [Array] },
      action: { name: 'Play Defend' }
    }
  }

Hey! It does show up! That's lovely, let's keep it this way, I have a feeling it may come in handy later. Also, we can change our "throws an error" test to assert for a specific error class instead of a specific error message (right after returning the if-check and exporting and importing the class):

it('throws an IllegalActionError when the action is illegal', () => {
    fc.assert(
        fc.property(getArbGameState(), arbAction, (gameState, action) => {
            fc.pre(!isLegalAction(gameState, action));

            let error = null;
            try {
                resolveAction(gameState, action);
            } catch (e) {
                error = e;
            }

            assert.ok(error instanceof IllegalActionError);
        })
    );
});

Nice stuff, test passes. Okay. Back to resolving Defend. Reinstate the assertion to remove it from the hand:

let firstDefendIndex = gameState.hand.indexOf('Defend');
let expectedHand = gameState.hand.toSpliced(firstDefendIndex, 1);
assert.deepEqual(outcome.gameState.hand, expectedHand);

Fails, Defend is still in hand. Implement the fix:

function resolveAction(gameState, action) {
    if (!isLegalAction(gameState, action)) throw new IllegalActionError(gameState, action);

    let firstDefendIndex = gameState.hand.indexOf('Defend');
    let resultingGameState = {
        ...gameState,
        block: gameState.block + 5,
        energy: gameState.energy - 1,
        hand: gameState.hand.toSpliced(firstDefendIndex, 1)
    };

    return [{ gameState: resultingGameState, probability: 1 }];
}

Yeaurgh, the test and implementation are uncomfortably similar. Holding my nose and asserting the discard pile situation just the same:

let expectedDiscardPile = [...gameState.discardPile, 'Defend'];
assert.deepEqual(outcome.gameState.discardPile, expectedDiscardPile);

Test fails, implement fix:

function resolveAction(gameState, action) {
    if (!isLegalAction(gameState, action)) throw new IllegalActionError(gameState, action);

    let firstDefendIndex = gameState.hand.indexOf('Defend');
    let resultingGameState = {
        ...gameState,
        block: gameState.block + 5,
        energy: gameState.energy - 1,
        hand: gameState.hand.toSpliced(firstDefendIndex, 1),
        discardPile: [...gameState.discardPile, 'Defend']
    };

    return [{ gameState: resultingGameState, probability: 1 }];
}

Test passes. I think that's everything that happens when you play Defend. We can successfully resolve it now.

Okay. Let's review the test code. What's the damage?

it('resolves Defend', () => {
    fc.assert(
        fc.property(getArbGameState(), gameState => {
            let action = { name: 'Play Defend' };
            fc.pre(isLegalAction(gameState, action));

            let result = resolveAction(gameState, action);
            let sumOfProbabilities = result.reduce((acc, x) => acc + x.probability, 0);
            assert.equal(sumOfProbabilities, 1);
            for (let outcome of result) {
                assert.equal(outcome.gameState.block, gameState.block + 5);
                assert.equal(outcome.gameState.energy, gameState.energy - 1);

                let firstDefendIndex = gameState.hand.indexOf('Defend');
                let expectedHand = gameState.hand.toSpliced(firstDefendIndex, 1);
                assert.deepEqual(outcome.gameState.hand, expectedHand);

                let expectedDiscardPile = [...gameState.discardPile, 'Defend'];
                assert.deepEqual(outcome.gameState.discardPile, expectedDiscardPile);
            }
        })
    );
});

I mean, it could be worse. But it could be better. We can make the result assertion stronger and assert it always returns one outcome:

let result = resolveAction(gameState, action);
assert.equal(result.length, 1);

That lets us simplify and get rid of the for-loop:

it('resolves Defend', () => {
    fc.assert(
        fc.property(getArbGameState(), gameState => {
            let action = { name: 'Play Defend' };
            fc.pre(isLegalAction(gameState, action));

            let result = resolveAction(gameState, action);
            assert.equal(result.length, 1);

            let outcome = result[0];
            assert.equal(outcome.probability, 1);
            assert.equal(outcome.gameState.block, gameState.block + 5);
            assert.equal(outcome.gameState.energy, gameState.energy - 1);

            let firstDefendIndex = gameState.hand.indexOf('Defend');
            let expectedHand = gameState.hand.toSpliced(firstDefendIndex, 1);
            assert.deepEqual(outcome.gameState.hand, expectedHand);

            let expectedDiscardPile = [...gameState.discardPile, 'Defend'];
            assert.deepEqual(outcome.gameState.discardPile, expectedDiscardPile);
        })
    );
});

Okay. I'll take it. I don't see an immediate improvement to make here. I suspect we can add some helper functions to assert expected hands and discard piles when we have more tests that check the same thing, but adding them now seems premature.

We've done a lot of work now, it's high time to commit, but let's leave one little TODO note since we still have a weird resolveAction() implementation:

// TODO: Resolve other actions than Play Defend
function resolveAction(gameState, action) {

There. Commit: "Implement resolveAction() for Play Defend".

Progress is slow, I will admit. Live-blogging the thought process and every little code change slows everything right down. I'm also not sure what I value more - progress on the project, or progress on this blog series.

Factors to consider:

• I only have the opportunity to work on this 1-2 hours a week, at most.
• I have taken breaks for months at a time and will do it again.
• The blog posts make the progress of each work session more concrete and tangible.
• The blog posts help me recover my train of thought between long breaks.
• Writing forces me to justify my decisions and stay on track.
• Writing a blog post will always take some time!
• If I take a break from writing this style of post and make progress outside of them, it will break the continuous train of thought that you can follow along from the very start of the series.

I see three options:

1. Continue code-liveblogging like this, maybe taking slightly coarser steps.
2. Change the series from a liveblogging style to more of a devlog style, only sharing select snippets of code.
   • This would split the coding and writing activities into two separate chunks, giving me a backlog of progress to write about. I think this would make it harder to sit down and knock out another post and a bit of progress.
3. Drop the series entirely and work in private.
   • This has the highest odds of killing the project. Having the project out in public on my website is a persistent encouragement to continue working on it.

In other words, there's no good option here but to keep trucking and tolerate that this be a slow-paced project. This does rhyme with how Ron Jeffries (who inspired me to start this series) makes progress on his own projects, though he's written a lot more posts than me and hence accumulated a lot more progress.

Ah well. As long as the time spent feels meaningful.

Next time: Strike! Bash! Probably not End Turn quite yet because that's a whole can of worms!

View this app version | Last commit: Implement resolveAction() for Play Defend

First, a little design talk: What is the interface of resolveAction()? It needs to take two parameters:

• A game state
• An action

All actions resolve to a set of possible game states (at least one), with different probabilities. The combined probability of all the possible game states is 100%. To satisfy this, resolveAction() can return an array of objects, where each object has a gameState property and a probability property.

So far, the design just seems like a repeat of my C# attempt at this problem. Same minds think alike, huh? But it will do.

Ho-kay, let's test-drive this thing. First, a new test suite in test.mjs:

describe('resolveAction()', () => {
    // Tests go here
});

Then... hm, I'm not quite sure how best to do this. We have a few general properties we want to assert, like "the probability of all possible game states sums to 100%". Then there are properties like "playing a card removes it from our hand" or "playing a card puts it in the discard pile", but these properties come with some big asterisks down the line when certain cards and abilities come into play. Even "playing Defend gives you 5 armor" comes with asterisks (what if you have Dexterity? or Frail? or you get damaged when you play a card?). All this is making me feel uncertain of how good a fit property-based testing actually is for our project. But hey, the arbitraries for generating test data are nice, and at worst we're bringing an example-based mindset to a property-based tool, which still does the job.

Bah, we can handle the asterisks when we get to them. Let's test a simple action first: "Play Defend".

it('resolves Defend', () => {
    fc.assert(
        fc.property(getArbGameState(), gameState => {
            let action = { name: 'Play Defend' };
            let result = resolveAction(gameState, action);
        })
    );
});

Now, the test fails because resolveAction is not defined yet, so let's implement and export that in index.js:

function resolveAction(gameState, action) {
    return []; // TODO: Implement this :)
}

// Export in Node.js for testing
if (typeof module === 'object' && module != null && 'exports' in module) {
    module.exports = { getActions, resolveAction };
}

Then import it in test.mjs:

import { getActions, resolveAction } from './index.js';

Test passes! Let's expand it to actually assert some things about the result. How about asserting the sum of probabilities?

it('resolves Defend', () => {
    fc.assert(
        fc.property(getArbGameState(), gameState => {
            let action = { name: 'Play Defend' };
            let result = resolveAction(gameState, action);
            let sumOfProbabilities = result.reduce((acc, x) => acc + x.probability, 0);
            assert.equal(sumOfProbabilities, 1);
        })
    );
});

Fails - the sum is 0. Let's make resolveAction() slightly more correct:

function resolveAction(gameState, action) {
    return [{ gameState, probability: 1 }];
}

Test passes! Yet it resolves all actions to the same game state. We need to assert some things about how it changes, like block increasing by 5.

it('resolves Defend', () => {
    fc.assert(
        fc.property(getArbGameState(), gameState => {
            let action = { name: 'Play Defend' };
            let result = resolveAction(gameState, action);
            let sumOfProbabilities = result.reduce((acc, x) => acc + x.probability, 0);
            assert.equal(sumOfProbabilities, 1);
            for (let outcome of result) {
                assert.equal(outcome.gameState.block, gameState.block + 5);
            }
        })
    );
});

Oof, my test complexity senses are tingling. But hey, failing test. So, make it pass...

function resolveAction(gameState, action) {
    let resultingGameState = {
        ...gameState,
        block: gameState.block + 5
    };
    return [{ gameState: resultingGameState, probability: 1 }];
}

Slowly getting somewhere. It also needs to reduce our energy by 1:

assert.equal(outcome.gameState.energy, gameState.energy - 1);

function resolveAction(gameState, action) {
    let resultingGameState = {
        ...gameState,
        block: gameState.block + 5,
        energy: gameState.energy - 1
    };
    return [{ gameState: resultingGameState, probability: 1 }];
}

A new fail and a new pass. Then, also, it needs to move Defend from our hand to the discard pile. Uh... How do we assert that?

let firstDefendIndex = gameState.hand.indexOf('Defend');
let expectedHand = gameState.hand.toSpliced(firstDefendIndex, 1);
assert.deepEqual(outcome.gameState.hand, expectedHand);

Okay, yeah, this really looks like the wrong way to write this test, but I want to see where this train wreck will lead us.

The test fails... for a hand containing just Strike. Mm. Right. Design question time: How should resolveAction handle illegal actions? Should it...

• ...reject them with an exception?
• ...return an error message?
• ...return an empty array?
• ...assume it will not receive illegal actions and resolve them anyway?

The last option would be best for performance (no extra logic to run at the top of each call), but until we have a rules engine that even works, I really believe the code ought to help us catch errors. The error should describe what was wrong, so we want some sort of error message. Making resolveAction() return a string when it fails might be weird to handle... I think throwing an exception is the right option.

You know, this legality thing sounds interesting enough that we should implement an isLegalAction() function first. Let's scrap all our changes and start over. New test:

describe('isLegalAction()', () => {
    it('handles Play Defend', () => {
        fc.assert(
            fc.property(getArbGameState(), gameState => {
                let result = isLegalAction(gameState, { name: 'Play Defend' });
            })
        );
    });
});

Fails because isLegalAction is not defined, so let's implement, export and import it:

function isLegalAction(gameState, action) {
    return true; // TODO: specify laws
}

// ...

// Export in Node.js for testing
if (typeof module === 'object' && module != null && 'exports' in module) {
    module.exports = { getActions, isLegalAction };
}

Alright, now to assert what the result ought to be:

describe('isLegalAction()', () => {
    it('handles Play Defend', () => {
        fc.assert(
            fc.property(getArbGameState(), gameState => {
                let result = isLegalAction(gameState, { name: 'Play Defend' });
                let expectedResult = gameState.hand.includes('Defend') && gameState.energy >= 1;
                assert.equal(result, expectedResult);
            })
        );
    });
});

Fails! Then let's implement it the simplest way to pass:

function isLegalAction(gameState, action) {
    return gameState.hand.includes('Defend') && gameState.energy >= 1;
}

Test passes. Cool. Now to do Play Strike:

it('handles Play Strike', () => {
    fc.assert(
        fc.property(getArbGameState(), fc.integer({ min: -1, max: 10 }), (gameState, enemyIndex) => {
            let result = isLegalAction(gameState, { name: 'Play Strike', enemyIndex });
            let expectedResult = gameState.hand.includes('Strike')
                && gameState.energy >= 1
                && enemyIndex >= 0
                && enemyIndex < gameState.enemies.length;
            assert.equal(result, expectedResult);
        })
    );
});

Test fails, make it pass (with proper distinction between the two actions now):

function isLegalAction(gameState, action) {
    if (action.name === 'Play Strike') {
        return gameState.hand.includes('Strike')
            && gameState.energy >= 1
            && typeof action.enemyIndex === 'number'
            && gameState.enemies[action.enemyIndex] != null;
    } else if (action.name === 'Play Defend') {
        return gameState.hand.includes('Defend')
            && gameState.energy >= 1;
    } else {
        return false;
    }
}

Test passes. Now we do Play Bash, same pattern:

it('handles Play Bash', () => {
    fc.assert(
        fc.property(getArbGameState(), fc.integer({ min: -1, max: 10 }), (gameState, enemyIndex) => {
            let result = isLegalAction(gameState, { name: 'Play Bash', enemyIndex });
            let expectedResult = gameState.hand.includes('Bash')
                && gameState.energy >= 2
                && enemyIndex >= 0
                && enemyIndex < gameState.enemies.length;
            assert.equal(result, expectedResult);
        })
    );
});

Red...

/* ... */
else if (action.name === 'Play Bash') {
    return gameState.hand.includes('Bash')
        && gameState.energy >= 2
        && typeof action.enemyIndex === 'number'
        && gameState.enemies[action.enemyIndex] != null;
}
/* ... */

...green. Now End Turn.

it('handles End Turn', () => {
    fc.assert(
        fc.property(getArbGameState(), gameState => {
            let result = isLegalAction(gameState, { name: 'End Turn' });
            let expectedResult = true;
            assert.equal(result, expectedResult);
        })
    );
});

/* ... */
else if (action.name === 'End Turn') {
    return true;
}
/* ... */

Red, green. That's all we need for now. We could add tests and checks for the game being over, but I believe it's enough that getActions() checks for it. I think we can do a slight refactor before we commit, because this function really looks like it ought to be a switch statement:

function isLegalAction(gameState, action) {
    switch (action.name) {
        case 'Play Strike':
            return gameState.hand.includes('Strike')
                && gameState.energy >= 1
                && typeof action.enemyIndex === 'number'
                && gameState.enemies[action.enemyIndex] != null;
        case 'Play Bash':
            return gameState.hand.includes('Bash')
                && gameState.energy >= 2
                && typeof action.enemyIndex === 'number'
                && gameState.enemies[action.enemyIndex] != null;
        case 'Play Defend':
            return gameState.hand.includes('Defend')
                && gameState.energy >= 1;
        case 'End Turn':
            return true;
        default:
            return false;
    }
}

Cool cool cool. Commit: "Add isLegalAction()"

Now - I see some potential here to go back and write the tests for getActions() a bit differently now, using this function. First we'll need an arbitrary to generate actions:

let arbAction = fc.oneof(
    fc.record({
        name: fc.constant('Play Strike'),
        enemyIndex: fc.integer({ min: 0, max: 9 })
    }),
    fc.record({
        name: fc.constant('Play Bash'),
        enemyIndex: fc.integer({ min: 0, max: 9 })
    }),
    fc.constant({ name: 'Play Defend' }),
    fc.constant({ name: 'End Turn' })
);

Hoping I'm using fc.oneof() correctly here. Then we write the test:

it('returns legal actions', () => {
    fc.assert(
        fc.property(getArbGameState(), arbAction, (gameState, action) => {
            let actions = getActions(gameState);
            let matches = actions.filter(x => deepEqual(x, action)).length;
            let expectedMatches = isLegalAction(gameState, action) ? 1 : 0;
            assert.equal(matches, expectedMatches);
        })
    );
});

Yes. Yes, here we have it. For every game state and action, if the action is legal, getActions() should return it, otherwise, it should not. This can replace our four action-specific tests and the duplicates test! Well, I hope it can, at least. The test passes, but let's prod at getActions() to see if this test actually catches bugs.

• If we don't return "End Turn", it fails. Nice.
• If we change the "Play Bash" to check for 3 energy instead of 2, it passes.
  • Wait. Oh no.

Right, okay, the test's not quite as strong as I'd like. Does it not run enough times to hit the case where we have Bash in hand, two energy, and a valid target? Do we need to up the run count?

it('returns legal actions', () => {
    fc.assert(
        fc.property(getArbGameState(), arbAction, (gameState, action) => {
            let actions = getActions(gameState);
            let matches = actions.filter(x => deepEqual(x, action)).length;
            let expectedMatches = isLegalAction(gameState, action) ? 1 : 0;
            assert.equal(matches, expectedMatches);
        }),
        { numRuns: 10000 }
    );
});

Apparently numRuns is 100 by default. A test that covers this much ground definitely ought to run more often than that. Give it a spin and... Yeah, there we go, property failed after 1674 tests. Now if we remove the error, it does take 160 milliseconds to pass instead of 4 milliseconds, so it has a cost, but it's still near-instant enough for my taste.

I'm curious whether we could and should split it into two tests, though... I saw the docs say something about preconditions, using .filter or fc.pre. Let's try the latter one:

it('returns legal actions', () => {
    fc.assert(
        fc.property(getArbGameState(), arbAction, (gameState, action) => {
            fc.pre(isLegalAction(gameState, action));
            let actions = getActions(gameState);
            let matches = actions.filter(x => deepEqual(x, action)).length;
            assert.equal(matches, 1);
        }),
        { numRuns: 5000 }
    );
});

it('does not return illegal actions', () => {
    fc.assert(
        fc.property(getArbGameState(), arbAction, (gameState, action) => {
            fc.pre(!isLegalAction(gameState, action));
            let actions = getActions(gameState);
            let matches = actions.filter(x => deepEqual(x, action)).length;
            assert.equal(matches, 0);
        }),
        { numRuns: 5000 }
    );
});

One test for legal actions, one test for illegal actions. Tidy! fc.pre() cancels the test if the precondition does not hold. Unfortunately, this looks like it doubles the run time - I guess it generates a ton of extra cases now that get canceled. It was a fun experiment, but let's roll it back to a single test.

I'm wondering now about test "efficiency" and distribution between different test cases. Maybe testing actions with enemyIndex above 5 is wasteful. And maybe we do not need to test "End Turn" so often. Apparently fc.oneof lets you pass weights?

let arbAction = fc.oneof(
    {
        weight: 5,
        arbitrary: fc.record({
            name: fc.constant('Play Strike'),
            enemyIndex: fc.integer({ min: 0, max: 5 })
        })
    },
    {
        weight: 5,
        arbitrary: fc.record({
            name: fc.constant('Play Bash'),
            enemyIndex: fc.integer({ min: 0, max: 5 })
        })
    },
    { weight: 2, arbitrary: fc.constant({ name: 'Play Defend' }) },
    { weight: 1, arbitrary: fc.constant({ name: 'End Turn' }) }
);

Testing this with the Bash energy change, and it doesn't really make a dramatic difference. If I turn the weight way up for "Play Bash" specifically, then it tends to find it in slightly fewer, but it's still within an order of magnitude. Let's roll this back too (but still lower the enemyIndex limit to 5).

Enough experimenting, time to commit: "Replace getActions() tests with 'returns valid actions'"

Small progress, but I'm happy. We learned a bit more about how we can use fast-check, and we found a design for our code that makes more sense with property-based testing. I didn't have a isValidAction function when we did this in C#! The tests were way different! Exciting differences!

Next time: implementing resolveAction(), for reals this time (probably)!

View this app version | Last commit: Replace getActions() tests with 'returns valid actions'

1. Finish implementing getActions().
2. Implement a function to resolve actions - something like resolveAction(gameState, action)?
3. Compute and render real actions on the page.
4. Something something implement a solver.

• We'll think more about this one when we get to it.

Having it written down helps! It also helps clarifying the design here - I think every action returned by getActions() should be valid input to resolveAction(). Hence, "Defeat" and "Victory" do not make any sense as actions, instead there should be no actions available when you win or lose.

Let's update the test we wrote last time to expect an empty list instead:

it('offers no actions when HP is zero', () => {
    fc.assert(
        fc.property(arbGameState, gameState => {
            if (gameState.hp === 0) {
                let actions = getActions(gameState);
                assert.deepEqual(actions, []);
            }
        })
    );
});

$ node --test
▶ getActions()
  ✔ can play Defend and End Turn (1.181773ms)
  ✔ can play Strike and End Turn (0.146242ms)
  ✖ offers no actions HP is zero (7.617366ms)
    Error: Property failed after 23 tests
    { seed: -1695486517, path: "22:0:0:0", endOnFailure: true }
    Counterexample: [{"hp":0,"maxHp":80,"block":0,"energy":0,"maxEnergy":3,"hand":[],"drawPile":[],"discardPile":[],"relics":[],"enemies":[]}]
    Shrunk 3 time(s)

Nice. Writing these tests feels really smooth. Then we update getActions to match:

if (gameState.hp === 0) {
    return [];
}

Tests pass! Commit: "getActions(): return no actions when dead".

Our solver will have to implement a separate function to check for victory and defeat now, but that sounds sensible. Oh, speaking of victory, we win when there are no enemies left:

    it('offers no actions when no enemies are left', () => {
        fc.assert(
            fc.property(arbGameState, gameState => {
                if (gameState.enemies.length === 0) {
                    let actions = getActions(gameState);
                    assert.deepEqual(actions, []);
                }
            })
        );
    });

Test failed, so then we update the implementation:

if (gameState.hp === 0 || gameState.enemies.length === 0) {
    return [];
}

Tests pass, commit: "getActions(): return no actions when no enemies left".

I'm noticing that our test logic looks suspiciously similar to our implementation logic. I'm also noticing that we have an if-check in our test. I have gotten the impression that tests should be as simple and explicit as possible, to make sure you understand what they are asserting, and to minimize the risk of logic errors. This is typically easy with example-based testing - given a specific input, expect a specific output, no logic to check for. But now we're asserting for properties that only hold for certain conditions, so we cannot write the test quite that simply. I'm smelling the risk of writing slightly tricky logic into the test, introducing an error, and writing that very same error into the implementation.

Maybe we can mitigate this risk by specifying the logic differently in our tests and our implementation. Maybe that .map() chaining method can help us here.

it('offers no actions when HP is zero', () => {
    fc.assert(
        fc.property(arbGameState.map(x => ({ ...x, hp: 0 })), gameState => {
            let actions = getActions(gameState);
            assert.deepEqual(actions, []);
        })
    );
});

it('offers no actions when no enemies are left', () => {
    fc.assert(
        fc.property(arbGameState.map(x => ({ ...x, enemies: [] })), gameState => {
            let actions = getActions(gameState);
            assert.deepEqual(actions, []);
        })
    );
});

Yeah, that works. I mean, ideally, we'd change the game state arbitrary so that it didn't produce a variety of values for hp and enemies that we just discard, but this looks like an improvement. Speaking of improvement, I think "it returns no actions" sounds better than "offers no actions", so let's change that as well. Commit: "Refactor property-based tests".

While we're at it, let's rewrite the other tests too: "can play Defend and End Turn" and "can play Strike and End Turn". These tests do not translate as cleanly, and I believe we need to test for a full handful of properties to replace them.

Given that both the player and enemies are alive:

• You can end the turn.
• If you have Defend in hand and at least 1 Energy, you can play Defend.
• If you have Strike in hand and at least 1 Energy, you can play Strike on any of the enemies.
• If you have Bash in hand and at least 2 Energy, you can play Bash on any of the enemies.
• You never get duplicate actions.

There, work cut out for us. And we'll need a more powerful way to specify arbitrary game state variants to do it. How about a little arbitrary factory?

function getArbGameState(options = {}) {
    let defaults = {
        hp: fc.integer({ min: 1, max: 80 }),
        maxHp: fc.constant(80),
        block: fc.constant(0),
        energy: fc.nat({ max: 999 }),
        maxEnergy: fc.constant(3),
        hand: fc.array(arbCard, { minLength: 0, maxLength: 10 }),
        drawPile: fc.constant([]),
        discardPile: fc.constant([]),
        relics: fc.constant([]),
        enemies: fc.array(arbEnemy, { minLength: 1, maxLength: 5 })
    };
    return fc.record({ ...defaults, ...options });
}

Now we have a set of useful defaults (the player is alive, enemies are alive) with an optional parameter to specify new arbitraries for any property. Then we update our tests:

it('returns no actions when HP is zero', () => {
    fc.assert(
        fc.property(getArbGameState({ hp: fc.constant(0) }), gameState => {
            let actions = getActions(gameState);
            assert.deepEqual(actions, []);
        })
    );
});

it('returns no actions when no enemies are left', () => {
    fc.assert(
        fc.property(getArbGameState({ enemies: fc.constant([]) }), gameState => {
            let actions = getActions(gameState);
            assert.deepEqual(actions, []);
        })
    );
});

Tests pass! Commit: "tests: add getArbGameState() function".

Now we can write all the tests we want. First, we can always end the turn:

it('returns End Turn', () => {
    fc.assert(
        fc.property(getArbGameState(), gameState => {
            let actions = getActions(gameState);
            // ... how do we assert this??
        })
    );
});

Okay we're not quite there yet. Uh. We want to assert that actions contains an object with one specific property with a specific value. It sounds like we need our deepEqual() function again. Time to dig through the Git log to recover it... Ah, found it.

Lil' copy-paste back into the project, and we can write:

it('returns End Turn', () => {
    fc.assert(
        fc.property(getArbGameState(), gameState => {
            let actions = getActions(gameState);
            return actions.some(x => deepEqual(x, { name: 'End Turn' }));
        })
    );
});

Nice! That passes. Though, I haven't seen it fail, and we're returning true/false now instead of using an assert function, so I'm paranoid that it doesn't actually test it properly. Let me just change the implementation to call it 'Finish Turn' instead to see that it fails... Okay yeah it fails, loudly, this works fine, undo the text change.

Next, let's ensure there are never any duplicate actions.

it('does not return duplicate actions', () => {
    fc.assert(
        fc.property(getArbGameState(), gameState => {
            let actions = getActions(gameState);
            return actions.every(x => {
                let matches = actions.filter(y => deepEqual(x, y));
                return matches.length === 1;
            });
        })
    );
});

Passes - the quadratic complexity makes me frown, but it's the simplest solution I see, and I'll take a simple test over a slightly more efficient test. Let's return the "Play Bash" action twice to make sure it fails... Yeah, it fails, undo the error.

Cool! Next up, Defend.

it('returns Play Defend', () => {
    fc.assert(
        fc.property(getArbGameState({
            hand: fc.array(arbCard, { minLength: 0, maxLength: 9 }).map(x => x.concat('Defend')),
            energy: fc.integer({ min: 1, max: 999 })
        }), gameState => {
            let actions = getActions(gameState);
            return actions.some(x => deepEqual(x, { name: 'Play Defend' }));
        })
    );
});

Passes! That way of specifying "any hand of cards including Defend" is clunky, though, and we'll have to repeat that pattern. Can we improve it? Do the docs offer a cleaner solution? ...three minutes of browsing say "no". Let's extract a function, then.

function getArbHand(options = {}) {
    let includedCards = options?.with ?? [];
    let constraints = { minLength: 0, maxLength: 10 - includedCards.length };
    return fc.array(arbCard, constraints).map(x => x.concat(includedCards));
}

it('returns Play Defend', () => {
    fc.assert(
        fc.property(getArbGameState({
            hand: getArbHand({ with: ['Defend'] }),
            energy: fc.integer({ min: 1, max: 999 })
        }), gameState => {
            let actions = getActions(gameState);
            return actions.some(x => deepEqual(x, { name: 'Play Defend' }));
        })
    );
});

Passes! We move on.

Next, Strike. This one's different, because when we have multiple enemies, we can have multiple actions with different targets. Our current code doesn't even support multiple targets yet. We can start with a test constrained to a single enemy:

it('returns Play Strike', () => {
    fc.assert(
        fc.property(getArbGameState({
            hand: getArbHand({ with: ['Strike'] }),
            energy: fc.integer({ min: 1, max: 999 }),
            enemies: fc.tuple(arbEnemy)
        }), gameState => {
            let actions = getActions(gameState);
            return actions.some(x => deepEqual(x, { name: 'Play Strike', enemyIndex: 0 }));
        })
    );
});

Cool, that passes. But we also want to assert there are not additional "Play Strike" actions with invalid enemy indexes. Maybe like this?

it('returns Play Strike', () => {
    fc.assert(
        fc.property(getArbGameState({
            hand: getArbHand({ with: ['Strike'] }),
            energy: fc.integer({ min: 1, max: 999 }),
            enemies: fc.tuple(arbEnemy)
        }), gameState => {
            let actions = getActions(gameState);
            let strikeActions = actions.filter(x => x.name === 'Play Strike').toSorted((a, b) => a.enemyIndex - b.enemyIndex);
            assert.deepEqual(strikeActions, [{ name: 'Play Strike', enemyIndex: 0 }]);
        })
    );
});

Oof, it's getting a bit involved, but it works. We can complicate the code even more so it tests multiple enemies:

it('returns Play Strike', () => {
    fc.assert(
        fc.property(getArbGameState({
            hand: getArbHand({ with: ['Strike'] }),
            energy: fc.integer({ min: 1, max: 999 })
        }), gameState => {
            let actions = getActions(gameState);
            let strikeActions = actions
                .filter(x => x.name === 'Play Strike')
                .toSorted((a, b) => a.enemyIndex - b.enemyIndex);
            let expectedStrikeActions = [...gameState.enemies.entries()]
                .map(([idx, _value]) => ({ name: 'Play Strike', enemyIndex: idx }))
                .toSorted((a, b) => a.enemyIndex - b.enemyIndex);
            assert.deepEqual(strikeActions, expectedStrikeActions);
        })
    );
});

Oof, ouch, this is setting off my "test is too complicated" sensors. I would never do this with example-based testing. But, I mean, it works:

AssertionError [ERR_ASSERTION]: Expected values to be loosely deep-equal:
    
    [
      {
        enemyIndex: 0,
        name: 'Play Strike'
      }
    ]
    
    should loosely deep-equal
    
    [
      {
        enemyIndex: 0,
        name: 'Play Strike'
      },
      {
        enemyIndex: 1,
        name: 'Play Strike'
      }
    ]

Sooo... Maybe it's fine? Maybe it's fine. We can fix the implementation now:

if (gameState.hand.includes('Strike') && gameState.energy >= 1) {
    for (let i = 0; i < gameState.enemies.length; i++) {
        actions.push({ name: 'Play Strike', enemyIndex: i });
    }
}

Green! Onwards to Bash. It works the same way as Strike, except it costs two energy:

it('returns Play Bash', () => {
    fc.assert(
        fc.property(getArbGameState({
            hand: getArbHand({ with: ['Bash'] }),
            energy: fc.integer({ min: 2, max: 999 })
        }), gameState => {
            let actions = getActions(gameState);
            let bashActions = actions
                .filter(x => x.name === 'Play Bash')
                .toSorted((a, b) => a.enemyIndex - b.enemyIndex);
            let expectedBashActions = [...gameState.enemies.entries()]
                .map(([idx, _value]) => ({ name: 'Play Bash', enemyIndex: idx }))
                .toSorted((a, b) => a.enemyIndex - b.enemyIndex);
            assert.deepEqual(bashActions, expectedBashActions);
        })
    );
});

Yup, fails as expected. Implement fix:

if (gameState.hand.includes('Bash') && gameState.energy >= 2) {
    for (let i = 0; i < gameState.enemies.length; i++) {
        actions.push({ name: 'Play Bash', enemyIndex: i });
    }
}

And the tests pass! I think this means getActions() is fully implemented for our Jaw Worm fight. Yay!

I notice now that these tests only assert the presence of actions when they should be there, and not the absence of actions when they should not be there. For instance, our tests pass if we do not require energy to play Bash. I mean. We could test this too. We could... maybe...

it('returns Play Bash', () => {
    fc.assert(
        fc.property(getArbGameState(), gameState => {
            let actions = getActions(gameState);
            let bashActions = actions
                .filter(x => x.name === 'Play Bash')
                .toSorted((a, b) => a.enemyIndex - b.enemyIndex);
            let canPlayBash = gameState.hand.includes('Bash') && gameState.energy >= 2;
            let expectedBashActions = canPlayBash
                ? [...gameState.enemies.entries()]
                    .map(([idx, _value]) => ({ name: 'Play Bash', enemyIndex: idx }))
                    .toSorted((a, b) => a.enemyIndex - b.enemyIndex)
                : [];
            assert.deepEqual(bashActions, expectedBashActions);
        })
    );
});

Lord almighty. I mean, um, both arrays are already sorted by enemyIndex, so we could trim the sorting...?

it('returns Play Bash', () => {
    fc.assert(
        fc.property(getArbGameState(), gameState => {
            let actions = getActions(gameState);
            let bashActions = actions.filter(x => x.name === 'Play Bash');
            let canPlayBash = gameState.hand.includes('Bash') && gameState.energy >= 2;
            let expectedBashActions = canPlayBash
                ? [...gameState.enemies.entries()]
                    .map(([idx, _value]) => ({ name: 'Play Bash', enemyIndex: idx }))
                : [];
            assert.deepEqual(bashActions, expectedBashActions);
        })
    );
});

You know what? Sure. Let's go with this. It's significantly less transparent than splitting it up into multiple tests, but it asserts exactly when we can play Bash, and it does it in a single test. We might get punished for this later, but we will take that punishment when it happens.

Let's rewrite the rest of the tests to the same style, extract a getIndexes() function, inline a few variables, and give the remaining variables similar names:

function getIndexes(array) {
    return [...array.entries()].map(([idx, _value]) => idx);
}

describe('getActions()', () => {
    it('returns no actions when HP is zero', () => {
        fc.assert(
            fc.property(getArbGameState({ hp: fc.constant(0) }), gameState => {
                let actions = getActions(gameState);
                assert.deepEqual(actions, []);
            })
        );
    });

    it('returns no actions when no enemies are left', () => {
        fc.assert(
            fc.property(getArbGameState({ enemies: fc.constant([]) }), gameState => {
                let actions = getActions(gameState);
                assert.deepEqual(actions, []);
            })
        );
    });

    it('does not return duplicate actions', () => {
        fc.assert(
            fc.property(getArbGameState(), gameState => {
                let actions = getActions(gameState);
                return actions.every(x => {
                    let matches = actions.filter(y => deepEqual(x, y));
                    return matches.length === 1;
                });
            })
        );
    });

    it('returns End Turn', () => {
        fc.assert(
            fc.property(getArbGameState(), gameState => {
                let actions = getActions(gameState).filter(x => x.name === 'End Turn');
                let expectedActions = [{ name: 'End Turn' }];
                assert.deepEqual(actions, expectedActions);
            })
        );
    });

    it('returns Play Defend', () => {
        fc.assert(
            fc.property(getArbGameState(), gameState => {
                let actions = getActions(gameState).filter(x => x.name === 'Play Defend');
                let expectedActions = gameState.hand.includes('Defend') && gameState.energy >= 1
                    ? [{ name: 'Play Defend' }]
                    : [];
                assert.deepEqual(actions, expectedActions);
            })
        );
    });

    it('returns Play Strike', () => {
        fc.assert(
            fc.property(getArbGameState(), gameState => {
                let actions = getActions(gameState).filter(x => x.name === 'Play Strike');
                let expectedActions = gameState.hand.includes('Strike') && gameState.energy >= 1
                    ? getIndexes(gameState.enemies).map(idx => ({ name: 'Play Strike', enemyIndex: idx }))
                    : [];
                assert.deepEqual(actions, expectedActions);
            })
        );
    });

    it('returns Play Bash', () => {
        fc.assert(
            fc.property(getArbGameState(), gameState => {
                let actions = getActions(gameState).filter(x => x.name === 'Play Bash');
                let expectedActions = gameState.hand.includes('Bash') && gameState.energy >= 2
                    ? getIndexes(gameState.enemies).map(idx => ({ name: 'Play Bash', enemyIndex: idx }))
                    : [];
                assert.deepEqual(actions, expectedActions);
            })
        );
    });
});

That looks like a fairly comprehensive test suite to me. Commit: "getActions(): support targetting different enemies".

We can now cross getActions() off our to-do list. The list is now:

1. Implement resolveAction(gameState, action).
2. Compute and render real actions on the page.
3. Implement a solver.

resolveAction() is going to be significantly more complicated. That's good. We can handle a challenge.

Until next time!

View this app version | Last commit: getActions(): support targetting different enemies

Let's kick things off by scrapping our own self-written test runner and switching to Node's. Having our own tests page is cute, but having less code to maintain is cuter.

I have not used Node's test runner before, so I'll have to reference the documentation. It looks like the node:test module exports a test() function (also aliased to it()) and a suite() function (also aliased to describe()). Tests fail when they throw an exception, and succeed when they don't. You can write assertions for tests by using the node:assert module. You run the tests by calling node --test on the command line, and it automatically discovers test files with names matching one of several patterns with "test" in it.

Let's convert our tests.js to a test.js file for Node. First, we rename it to test.js. Then we import assert, describe and it at the top of the file:

import assert from 'node:assert';
import { describe, it } from 'node:test';

Oh man it feels good being able to import things. Anyway. Next we declare a test suite with describe():

describe('getActions()', () => {

});

Then - we'd better see the test runner in action as soon as we can - we write a failing test:

describe('getActions()', () => {
    it('fails', () => {
        assert.equal(true, false);
    });
});

And we run it with node --test:

$ node --test
(node:49267) Warning: To load an ES module, set "type": "module" in the package.json or use the .mjs extension.
(Use `node --trace-warnings ...` to show where the warning was created)
/home/cvennevik/dev/crystal-spire/test.js:1
import assert from 'node:assert';
^^^^^^

SyntaxError: Cannot use import statement outside a module

Ah. test.js is not an ES module, so it can't import. I might want to add "type": "module" to the package, but that may have unexpected consequences - let's rename it to test.mjs for the moment. Then rerun node --test:

$ node --test
▶ getActions()
  ✖ fails (1.473907ms)
    AssertionError [ERR_ASSERTION]: true == false

Yay! A failing test! Then we can change it to pass:

it('passes', () => {
    assert.equal(true, true);
});

$ node --test
▶ getActions()
  ✔ passes (0.736913ms)

Beautiful. Now to convert the actual test. We take our array of test cases:

let testCases = [
    {
        name: 'Can Play Defend and End Turn',
        input: {
            // ... a game state ...
        },
        expectedOutput: [{ name: 'Play Defend' }, { name: 'End Turn' }]
    },
    {
        name: 'Can Play Strike and End Turn',
        input: {
            // ... another game state ...
        },
        expectedOutput: [{ name: 'Play Strike', enemyIndex: 0 }, { name: 'End Turn' }]
    }
];

for (let testCase of testCases) {
    testCase.actualOutput = getActions(testCase.input);
    testCase.passed = deepEqual(testCase.actualOutput, testCase.expectedOutput);
}

...and we add equivalent Node tests:

describe('getActions()', () => {
    it('can play Defend and End Turn', () => {
        let gameState = { /* ... a game state ... */ };
        let actions = getActions(gameState);
        assert.deepEqual(actions, [{ name: 'Play Defend' }, { name: 'End Turn' }]);
    });

    it('can play Strike and End Turn', () => {
        let gameState = { /* ... another game state ... */ };
        let actions = getActions(gameState);
        assert.deepEqual(actions, [{ name: 'Play Strike', enemyIndex: 0 }, { name: 'End Turn' }]);
    });
});

Then we try to run them:

$ node --test
▶ getActions()
  ✖ can play Defend and End Turn (0.831261ms)
    ReferenceError [Error]: getActions is not defined

Ah. Right. We need to import getActions. Hm.

I am not entirely sure how to go about this. I think if we use export in index.js, that will give us an error in the browser, since it's not a module. Let's try it to verify:

export function getActions(gameState) {
    // ...
}

Uncaught SyntaxError: export declarations may only appear at top level of a module

Yeah. So that doesn't work. I know there's another way to do exports with Node, though, which is to assign exports to module.exports, and we might be able to do that without the browser complaining. Pop this little bad boy at the end of index.js:

// Export in Node.js for testing
if (module !== undefined && 'exports' in module) {
    module.exports = { getActions };
}

It works! Our page works as normal now. Okay, well, we do still get a nasty Uncaught ReferenceError: module is not defined in the console still, so actually, the if-check doesn't work at all. I've heard of globalThis being an environment-neutral way to access global variables, though, maybe we can access module.exports that way?

// Export in Node.js for testing
if ('module' in globalThis && 'exports' in globalThis.module) {
    globalThis.module.exports = { getActions };
}

Browser doesn't complain, so that's one out of two steps passed. Now to try and import it in the test:

import { getActions } from './index.js';

$ node --test
file:///home/cvennevik/dev/crystal-spire/test.mjs:3
import { getActions } from './index.js';
         ^^^^^^^^^^
SyntaxError: Named export 'getActions' not found. The requested module './index.js' is a CommonJS module, which may not support all module.exports as named exports.

Ah. The code fails to actually export getActions. Wow, modules aren't straightforward to half-use. I think we need to take a proper research timeout.

...

Okay. Several important facts learned with a few web searches:

• module.exports is used by CommonJS modules, as opposed to import/export which are used by ECMAScript modules.
  • If we use module.exports in one file and import in another, then we're mixing CommonJS and ES modules, and we have to rely on Node's CommonJS/ES module interoperability.
• CommonJS modules are executed inside a function wrapper, and variables like module and require are parameters of that function. That explains why we can't access those variables through globalThis.
• The typeof operator works on undeclared variables!

Putting this all together, we can solve the export problem like this:

// Export in Node.js for testing
if (typeof module === 'object' && module != null && 'exports' in module) {
    module.exports = { getActions };
}

The HTML page loads without error! What about the command line tests?

$ node --test
▶ getActions()
  ✔ can play Defend and End Turn (1.18629ms)
  ✔ can play Strike and End Turn (0.149797ms)
▶ getActions() (2.403152ms)
ℹ tests 2
ℹ suites 1
ℹ pass 2
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 58.991965

Oh bless. It actually works. That was significantly more work that I thought this would be.

Halfway there. The other half is saying goodbye to the old test code:

• We remove the link to tests.html from our rendered HTML.
• We remove tests.html.
• We remove tests.css.
• We remove the leftover code from test.mjs.

And a couple finishing touches to package.json:

• Add "type": "commonjs" to explicitly declare that .js files are CommonJS modules, as I saw recommended in the Node.js documentation.
  • We can still use .mjs for ES modules, like we do with test.mjs.
• Add a "test" script for node --test to document how we run our tests, and to make the npm test command work.

{
  "name": "crystal-spire",
  "version": "1.0.0",
  "type": "commonjs",
  "scripts": {
    "test": "node --test"
  },
  "devDependencies": {
    "fast-check": "^4.5.2"
  }
}

And commit: "Migrate tests to Node.js test runner".

Whew.

I said we're doing property-based testing today, and I'm sticking to my word. We're not stopping until we're there.

From my understanding, property-based testing is about writing properties that should hold for any possible input, then running the code against random possible inputs to test that the properties hold.

Let's begin by reading through fast-check's Getting Started guide...

• fast-check "works in any test runner without needing any specific change".
  • ...putting a pin in that thought, but moving on...
• It suggests importing the library like import fc from 'fast-check'.
• Inside any test in your test runner of choice, you call fc.assert, which "takes a property and runs it multiple times".
  • In case of failure, it will try to "shrink" the input value to the simplest possible value that causes the failure. This is neat.
• Inside fc.assert, we declare properties using fc.property, which takes a list of arbitraries to generate inputs with, and a predicate to test the inputs with.

Okay! This seems like a manageable set of concepts. It looks like the final piece we need is defining our own arbitraries. Browsing the arbitraries documentation, fast-check has:

• Primitives, like fc.boolean(), fc.integer(), fc.string(), and so on, with parameters to customize their range of values.
• Composites, like fc.tuple(), fc.array(), fc.func(), fc.object(), and so on.
• Combiners, like fc.constant(), fc.subarray(), fc.option(), and chaining methods like .filter() and .map().

Let's jump into the deep end, then, and define an arbitrary for game states. For generating objects with specific properties, we'll want to use fc.record():

let arbGameState = fc.record({
    hp: 'todo',
    maxHp: 'todo',
    block: 'todo',
    energy: 'todo',
    maxEnergy: 'todo',
    hand: 'todo',
    drawPile: 'todo',
    discardPile: 'todo',
    relics: 'todo',
    enemies: 'todo'
});

For the numbers, we can use fc.nat() for all non-negative integer values:

let arbGameState = fc.record({
    hp: fc.nat(),
    maxHp: fc.nat(),
    block: fc.nat(),
    energy: fc.nat(),
    maxEnergy: fc.nat(),
    hand: 'todo',
    drawPile: 'todo',
    discardPile: 'todo',
    relics: 'todo',
    enemies: 'todo'
});

...although, no, this will generate invalid states where hp is greater than maxHp, and weird states where energy is in the hundreds of millions.

We could pass a max value to some of these, but for the sake of finding available moves, some of these never matter, so let's leave those a constant instead:

let arbGameState = fc.record({
    hp: fc.nat({ max: 80 }),
    maxHp: fc.constant(80),
    block: fc.constant(0),
    energy: fc.nat({ max: 999 }),
    maxEnergy: fc.constant(3),
    hand: 'todo',
    drawPile: 'todo',
    discardPile: 'todo',
    relics: 'todo',
    enemies: 'todo'
});

Then we have the hand and piles. We can define an arbitrary for cards:

let arbCard = fc.constantFrom('Strike', 'Defend', 'Bash');

Then define arrays using fc.array() - though, again, only cards in hand matter here, so drawPile and discardPile can be left as constant empty arrays, and relics also don't matter, so let's throw an empty array in there at the same time:

let arbGameState = fc.record({
    hp: fc.nat({ max: 80 }),
    maxHp: fc.constant(80),
    block: fc.constant(0),
    energy: fc.nat({ max: 999 }),
    maxEnergy: fc.constant(3),
    hand: fc.array(arbCard, { minLength: 0, maxLength: 10 }),
    drawPile: fc.constant([]),
    discardPile: fc.constant([]),
    relics: fc.constant([]),
    enemies: 'todo'
});

Finally, the enemies array. That will need an arbitrary for enemies:

let arbEnemy = fc.record({
    name: 'todo',
    hp: 'todo',
    maxHp: 'todo',
    block: 'todo',
    nextMove: 'todo',
    moveHistory: 'todo',
    buffs: 'todo',
    debuffs: 'todo'
});

...and I don't know of any relevant enemy variations, so let's make them all constants:

let arbEnemy = fc.record({
    name: fc.constant('Jaw Worm'),
    hp: fc.constant(42),
    maxHp: fc.constant(42),
    block: fc.constant(0),
    nextMove: fc.constant([]),
    moveHistory: fc.constant([]),
    buffs: fc.constant([]),
    debuffs: fc.constant([])
});

Then we can use it with fc.array() to specify enemies. I'm not sure whether the minimum number of enemies should be one or zero. I think killing the last enemy gets you to a game state with zero enemies, so let's make the lower bound zero:

let arbGameState = fc.record({
    hp: fc.nat({ max: 80 }),
    maxHp: fc.constant(80),
    block: fc.constant(0),
    energy: fc.nat({ max: 999 }),
    maxEnergy: fc.constant(3),
    hand: fc.array(arbCard, { minLength: 0, maxLength: 10 }),
    drawPile: fc.constant([]),
    discardPile: fc.constant([]),
    relics: fc.constant([]),
    enemies: fc.array(arbEnemy, { minLength: 0, maxLength: 5 })
});

There! We have an arbitrary for game states that hopefully works.

Now we write our first property-based test. Let's test for a property that I suspect will not pass: "If the player has zero HP, the only available action is defeat."

it('only has Defeat available when HP is zero', () => {
    fc.assert(
        fc.property(arbGameState, gameState => {
            if (gameState.hp === 0) {
                let actions = getActions(gameState);
                assert.deepEqual(actions, [{ name: 'Defeat' }]);
            }
        })
    );
})

I don't think this is the ideal way to write the test - maybe, instead, the arbitrary should have hp as a constant of zero. But I think this will still work, and it's readable, and we can reconsider our approach when we have more tests.

Deep breath. Time to run it. Does it work?

$ node --test
▶ getActions()
  ✔ can play Defend and End Turn (1.208453ms)
  ✔ can play Strike and End Turn (0.146097ms)
  ✖ only has Defeat available when HP is zero (7.154977ms)
    Error: Property failed after 10 tests
    { seed: -288422701, path: "9:0:0:0:0", endOnFailure: true }
    Counterexample: [{"hp":0,"maxHp":80,"block":0,"energy":0,"maxEnergy":3,"hand":[],"drawPile":[],"discardPile":[],"relics":[],"enemies":[]}]
    Shrunk 4 time(s)

Haha!! It's alive!! We're doing property-based testing!!

Ahem. Now we can implement the fix:

function getActions(gameState) {
    if (gameState.hp === 0) {
        return [{ name: 'Defeat' }];
    }
    // ...
}

Then rerun the test:

$ node --test
▶ getActions()
  ✔ can play Defend and End Turn (1.166435ms)
  ✔ can play Strike and End Turn (0.140492ms)
  ✔ only has Defeat available when HP is zero (7.334557ms)

We're green. We TDD'd with PBT. Our yak is shaved.

Commit: "Add 'Defeat' action".

I am really excited! We can finally return to implementing our solver, with the support of a testing tool I've wanted to try out for years. I'm stoked to figure out the design for this. Last time I did this in C# it got really involved, with a lot of files and a lot of tests. This time, I think we'll go with quite different strategies for both implementation and testing. I don't know what they will be yet! It'll be fun to find out!

See you next time :)

View this app version | Last commit: Add 'Defeat' action

• I have never written a property-based test before.
• The most visible and actively maintained property-based testing library for JavaScript, fast-check, gives zero indication of being able to run standalone in a browser, and I don't want to add Node as a dependency if we can get away with it.
• From what I can tell, implementing a decent property-based testing library is complicated.

There's a ways we can go about this:

1. Implement our own testing library. We'd be able to ensure it satisfies our requirements, and it would be a great learning experience. On the other hand, implementing a good enough library may take so much effort, it would take years before this series returns to actually implementing a Slay the Spire solver. It would be a massive yak shave.
2. Find a way to run an existing library in the browser. It would let us get on with writing tests, and doing any property-based testing at all is still a great learning experience. On the other hand, the project wouldn't be as "pure" in terms of solving everything ourselves, and we'd be taking on a large amount of JavaScript to run our tests. Also it may not be possible.
3. Give up on running this project with just a browser and start relying on Node.
4. Give up on property-based tests and go back to example-based testing.

Option 1 seems inappropriately ambitious. Option 2 seems potentially doable, although it may not give us the best tool for the job. Option 3 would mean getting access to a local JavaScript runtime and a package manager, which in turn gives us access to some of the best tools for both this job and many other jobs, but...

Okay, let's take a moment to consider. Why do I value keeping this project buildless and free of external dependencies?

• I want the code to be accessible to newcomers who do not already have all kinds of toolchains installed.
• I want the code to be easy to copy into different contexts, without assuming a given framework or runtime.
• I want the software to be cold-blooded, so I can leave it for months and years and pick it up again just the way I left it.

Not having to install anything extra to run the code is good! Building on a stable platform is good! Yet some things that are worth doing are not practical to do without extra dependencies. Some things require a web server. Some things require a database. Some things require a local JavaScript runtime like Node. Scratch that, a lof of things require a local JavaScript runtime like Node.

I also wonder if now, by the end of 2025, that Node qualifies as boring technology. It's 16 years old, ubiquitious, and seemingly fairly stable by now. I also wonder if property-based testing does not count as boring technology, and that we cannot realistically adopt it without paying the tax of an npm dependency.

And, unexpectedly, this self-imposed restriction is making me feel lonely. My setup today is a weird fringe thing that modern libraries and browser security mechanisms do not make space for. I have to make awkward workarounds and compromises and give up things that are table stakes for most developers. Doing web application development with no tooling, as it turns out, is not a path I want to invite others to follow. Certainly not for a project with such limited development time as this one.

Okay. Enough crisis of faith. It's time to bite the bullet.

Commit: "Add package.json"

Commit: "Add node_modules to .gitignore"

And we add our first dependency to package.json:

{
  "name": "crystal-spire",
  "version": "1.0.0",
  "devDependencies": {
    "fast-check": "^4.5.2"
  }
}

> npm i

added 2 packages, and audited 3 packages in 658ms

Oh hey, fast-check actually only has a single transitive dependency, so our node_modules directory has a grand total of two packages in it. That's pretty neat!

Commit: "Add fast-check to devDependencies"

That's enough excitement for one post. I still don't feel comfortable with this decision, but I accept the risk of regret.

Next time: property-based testing, for real this time.

View this app version | Last commit: Add fast-check to devDependencies

To begin, let's review the code and see if we can make it easier to work with. Points to note:

1. The inline style block in tests.html could be extracted to a separate CSS file. It adds one more file, but leaves tests.html to act as glue between the different files, and gives us a natural spot to add more styles in the future.
2. tests.js immediately runs code to render the page, making it impossible to reuse the file if we add another page with test code. We should extract a render() function like we did in index.js.
3. Taking that point more broadly, I think the global state and side effects in index.js and tests.js are design liabilities. I would rather convert them into libraries of pure functions, and add a little more glue code to index.html and tests.html to render the page.
4. We should consider converting the code from classic scripts to module scripts. Explicit imports and exports may come in handy.

That looks like enough points to get started with. Point 1: Extract tests.css.

/* tests.css */
table, th, td {
    border: 1px solid grey;
    border-collapse: collapse;
}

<!-- tests.html -->
<head>
    <meta charset="UTF-8">
    <title>Crystal Spire - Tests</title>
    <link rel="stylesheet" href="./tests.css">
</head>

Commit: "Extract tests.css from tests.html". Then onto point 2.

// tests.js
function renderTests() {
    document.body.innerHTML = `
    ...
    `;
}

<!-- tests.html -->
<script>renderTests()</script>

Can't name it render() because that would collide with the same function from index.js. Another point towards using module scripts. Commit: "tests.js: Extract renderTests() function".

Point 3 takes a bit of design judgement. We have a test suite, we want to run it, and we want to render the results. I do not know it should be decomposed (should we have a test suite object? a "run tests" function? a results object?), so let's make it all a single function.

// tests.js
function runAndRenderTests() {
    let testCases = [
        // ...
    ];

    for (let testCase of testCases) {
        testCase.actualOutput = getActions(testCase.input);
        testCase.passed = deepEqual(testCase.actualOutput, testCase.expectedOutput);
    }

    passedTestCases = testCases.filter(x => x.passed);
    failedTestCases = testCases.filter(x => !x.passed);

    return `
        ...
    `;
}

<!-- tests.html -->
<script>document.body.innerHTML = runAndRenderTests()</script>

Commit: "tests.js: Convert to runAndRenderTests() function".

Then onto index.js. Currently it deserializes window.location.search directly to get the game state. If we instead do that in index.html and pass the game state to the render function, that opens for rendering any game state we want.

<!-- index.html -->
<script>
let gameState = window.location.search ? deserialize(window.location.search) : defaultGameState;
document.body.innerHTML = render(gameState);
</script>

// index.js
function render(gameState) {
    return `
        ...
    `;
}

Not a lot of code to change! Commit: "Make gameState a parameter to the render function".

Finally, point 4 about JavaScript modules. They have been broadly available since... what, 2018? I'm trying to find any downsides to switching to them, and the only things I can find is being forced into strict mode, and a vague memory of some functionality having stricter security limitations when using modules? Both of these things sound like upsides in our case, so everything is pointing us towards modules.

Let's just add a little type="module" to our inline script in index.html, and...

<script type="module">
import { render, deserialize } from './index.js';
let gameState = window.location.search ? deserialize(window.location.search) : defaultGameState;
document.body.innerHTML = render(gameState);
</script>

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at file:///home/cvennevik/dev/crystal-spire/index.js. (Reason: CORS request not http).

Well fuck.

So if we use JavaScript modules, the browser enforces the Same Origin Policy on imports. And anything on the file system counts as a remote resource, so it blocks the request. That means our app becomes unusable as plain files on the file system, and requires a web server to function.

Given how we value being able to develop and run our code with minimal dependencies, adding a web server is way too steep a cost to pay for adopting modules. We have to scrap it and stick to classic scripts.

Maybe we should adopt "strict mode", however. It looks like it will help catch mistakes loudly instead of silently. All it takes is adding 'use strict'; to the top of index.js and tests.js, and... Wait, what's this?

Uncaught ReferenceError: assignment to undeclared variable passedTestCases

Ah! Two of the variables in tests.js are undeclared. Whoops! Thank you for pointing it out, strict mode, we'll fix it right away. Commit: "Use strict mode, fix undeclared variables".

This post has already stretched over two days, so let's wrap it here. The code looks to be in good shape for further development now.

Next time: property-based testing, maybe?

View this app version | Last commit: Use strict mode, fix undeclared variables

Part of the challenge I'm giving myself in this series is implementing everything in hand-written, buildless HTML + CSS + JS. I want to flex my web coding muscles and try some things I don't otherwise get to try.

I've used a few test frameworks over the years, but I've never tried making one myself. Nearly all of them involve using the command line as the test runner. We can't do that here, as I don't want to make this project dependent on something like Node. What we can do instead is use the browser as our test runner, a la standalone Jasmine.

To aid our thinking, let's code a little bit, and make a new HTML page to run our tests in. We make a new file titled test.html:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Crystal Spire - Tests</title>
</head>
<body>
    <noscript>
        This application only works with JavaScript enabled.
    </noscript>
</body>
</html>

Now let's sketch out what we want we want to see. We want to test that our getActions function works as expected. I think the simplest thing to implement would be an example-based approach, where we specify an input, pass it to the function, and compare the result to an expected output.

If the tests succeed, we can show something simple like...

<h1>Crystal Spire - Tests</h1>
<h2>getActions</h2>
<p>✅ 3 tests passed</p>

And if any tests fail, we want to show how they failed:

<h1>Crystal Spire - Tests</h1>
<h2>getActions</h2>
<p>✅ 1 test passed</p>
<p>❌ 2 tests failed</p>
<table>
    <tr>
        <th>Input</th>
        <th>Actual output</th>
        <th>Expected output</th>
    </tr>
    <tr>
        <td><code>{ full gameState object }</code></td>
        <td><code>[{ name: 'Play Defend' }]</code></td>
        <td><code>[{ name: 'Play Defend' }, { name: 'End Turn' }]</code></td>
    </tr>
    <tr>
        <td><code>{ full gameState object }</code></td>
        <td><code>[{ name: 'End Turn' }]</code></td>
        <td><code>[{ name: 'End Turn' }, { name: 'Play Strike', enemyIndex: 0 }]</code></td>
    </tr>
</table>

I wasn't quite sure how to display the test results at first, but I think a table makes a lot of sense. The default display style doesn't give me any borders between cells in Firefox, though, so let's write our first bit of CSS up in the head, for readability:

<style>
    table, th, td {
        border: 1px solid black;
        border-collapse: collapse;
    }
</style>

Yeah that looks alright. But, I have a sneaking suspicion the { full gameState object } will look really long when it's a real object, so let's try pasting in the default gameState for something more realistic:

<td><code>{ hp: 80, maxHp: 80, block: 0, energy: 3, maxEnergy: 3, hand: ['Bash', 'Defend', 'Defend', 'Defend', 'Strike'], drawPile: ['Defend', 'Strike', 'Strike', 'Strike', 'Strike'], discardPile: [], relics: ['Burning Blood'], enemies: [{ name: 'Jaw Worm', hp: 42, maxHp: 42, block: 0, nextMove: 'Chomp', moveHistory: [], buffs: [], debuffs: [] }]}</code></td>

Wow that is hard to read on a single line. Maybe preformatted and pretty-printed would be better.

<td><pre><code>{
    hp: 80,
    maxHp: 80,
    block: 0,
    energy: 3,
    maxEnergy: 3,
    hand: ['Bash', 'Defend', 'Defend', 'Defend', 'Strike'],
    drawPile: ['Defend', 'Strike', 'Strike', 'Strike', 'Strike'],
    discardPile: [],
    relics: ['Burning Blood'],
    enemies: [
        {
            name: 'Jaw Worm',
            hp: 42,
            maxHp: 42,
            block: 0,
            nextMove: 'Chomp',
            moveHistory: [],
            buffs: [],
            debuffs: []
        }
    ]
}</code></pre></td>

Okay, that actually looks readable. I could give each test a name too:

<th>Name</th>

<td>Can Play Defend and End Turn</td>

<td>Can Play Strike and End Turn</td>

It's kind of ugly, but it's servicable. Okay. Let's implement this.

First, we make a new JavaScript file for test.html, namely test.js. Then we create our test cases - actual real ones, this time:

let testCases = [
    {
        name: 'Can Play Defend and End Turn',
        input: {
            hp: 80,
            maxHp: 80,
            block: 0,
            energy: 3,
            maxEnergy: 3,
            hand: ['Defend'],
            drawPile: [],
            discardPile: [],
            relics: [],
            enemies: [
                {
                    name: 'Jaw Worm',
                    hp: 42,
                    maxHp: 42,
                    block: 0,
                    nextMove: 'Chomp',
                    moveHistory: [],
                    buffs: [],
                    debuffs: []
                }
            ]
        },
        expectedOutput: [{ name: 'Play Defend' }, { name: 'End Turn' }]
    },
    {
        name: 'Can Play Strike and End Turn',
        input: {
            hp: 80,
            maxHp: 80,
            block: 0,
            energy: 3,
            maxEnergy: 3,
            hand: ['Strike'],
            drawPile: [],
            discardPile: [],
            relics: [],
            enemies: [
                {
                    name: 'Jaw Worm',
                    hp: 42,
                    maxHp: 42,
                    block: 0,
                    nextMove: 'Chomp',
                    moveHistory: [],
                    buffs: [],
                    debuffs: []
                }
            ]
        },
        expectedOutput: [{ name: 'Play Strike', enemyIndex: 0 }, { name: 'End Turn' }]
    }
];

Then, we find the results of each test, by calling the function for each test case - and we might as well use the test case objects to store the results:

for (let testCase of testCases) {
    testCase.actualOutput = getActions(testCase.input);
}

And then we need to find out whether the test has passed or failed - whether actualOutput and expectedOutput match. So I guess we need to write a deep equality function that works for arrays, objects, and primitive values? There are definitely already implementations of this online, I've copied them before, but let me just write my best attempt off the top of my head...

function deepEqual(a, b) {
    // Passes equal cases of null, undefined, number, and string
    if (a === b) return true;

    // Passes equal cases of arrays
    if (Array.isArray(a)) {
        if (!Array.isArray(b)) return false;
        if (a.length !== b.length) return false;
        for (let i = 0; i < a.length; i++) {
            if (!deepEqual(a[i], b[i])) {
                return false;
            }
        }
        
        return true;
    }

    // Passes equal cases of objects
    if (typeof a === 'object') {
        if (!typeof b === 'object') return false;

        let aKeys = Object.keys(a);
        let bKeys = Object.keys(b);
        if (aKeys.length !== bKeys.length) return false;

        for (let key of aKeys) {
            if (!bKeys.includes(key)) return false;
            if (!deepEqual(a[key], b[key])) return false;
        }

        return true;
    }

    // All equal cases we care about have passed - fail the equality
    return false;
}

Okay, whew, I hope that works. Let's take it for a spin:

for (let testCase of testCases) {
    testCase.actualOutput = getActions(testCase.input);
    testCase.passed = deepEqual(actualOutput, expectedOutput);
}

Then render the page based on this data, just like in index.js:

passedTestCases = testCases.filter(x => x.passed);
failedTestCases = testCases.filter(x => !x.passed);
document.body.innerHTML = `
    <h1>Crystal Spire - Tests</h1>
    <h2>getActions</h2>
    ${passedTestCases.length > 0
        ? `<p>✅ ${passedTestCases.length} ${passedTestCases.length === 1 ? 'test' : 'tests'} passed</p>`
        : ''
    }
    ${failedTestCases.length > 0
        ? `
        <p>✅ ${failedTestCases.length} ${failedTestCases.length === 1 ? 'test' : 'tests'} passed</p>
        <table>
            <tr>
                <th>Name</th>
                <th>Input</th>
                <th>Actual output</th>
                <th>Expected output</th>
            </tr>
            ${failedTestCases.map(testCase => `
                <tr>
                    <td>${testCase.name}</td>
                    <td><pre><code>${testCase.input}</code></pre></td>
                    <td><pre><code>${testCase.actualOutput}</code></pre></td>
                    <td><pre><code>${testCase.expectedOutput}</code></pre></td>
                </tr>
            `)}
        `
        : ''
    }
`;

And plug the file into test.html, then try loading the page...

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Crystal Spire - Tests</title>
    <style>
        table, th, td {
            border: 1px solid grey;
            border-collapse: collapse;
        }
    </style>
</head>
<body>
    <noscript>
        This application only works with JavaScript enabled.
    </noscript>
</body>
<script src="test.js"></script>
</html>

Ah, console error, getActions is not defined. I usually fix this with an import, but... what if we just...?

<script src="index.js"></script>
<script src="test.js"></script>

Okay no that doesn't work because index.js also renders to our body. Right. Let's move the rendering logic of index.js into a render function:

function render() {
    document.body.innerHTML = `
        ...omitted...
    `;
}

I probably should factor it differently, but let's just get it working for now. So now we can call this function in index.html only:

<script>render()</script>

Okay, now index.html still works. But test.html still fails because "actualOutput is not defined". Need to go back to test.js and fix this block where I just wrote deepEqual(actualOutput, expectedOutput), which gave a console error:

for (let testCase of testCases) {
    testCase.actualOutput = getActions(testCase.input);
    testCase.passed = deepEqual(testCase.actualOutput, testCase.expectedOutput);
}

And now, now - test.html renders! Wrongly. It says "2 tests passed", but it displays a table with failed test results, and the input/output table cells say [object Object]. And there's a comma before the table.

One error at a time. It says "2 tests passed" because I copy-pasted it for the failed tests line, so let's fix that:

<p>❌ ${failedTestCases.length} ${failedTestCases.length === 1 ? 'test' : 'tests'} failed</p>

Then the weird comma before the table... Oh, I also forgot to write </table> at the end. Lovely of HTML for forgiving me forgetting that, let's enter it correctly. Oh, and I forgot to put a .join('') at the end of the row mapping, interpolating the plain array must somehow have resulted in a comma, fix that:

${failedTestCases.map(testCase => `
    <tr>
        <td>${testCase.name}</td>
        <td><pre><code>${testCase.input}</code></pre></td>
        <td><pre><code>${testCase.actualOutput}</code></pre></td>
        <td><pre><code>${testCase.expectedOutput}</code></pre></td>
    </tr>
`).join('')}

Then, let's use JSON.stringify to print the input/output prettier. The "2" argument at the end tells the function to use two spaces for indentation.

<tr>
    <td>${testCase.name}</td>
    <td><pre><code>${JSON.stringify(testCase.input, null, 2)}</code></pre></td>
    <td><pre><code>${JSON.stringify(testCase.actualOutput, null, 2)}</code></pre></td>
    <td><pre><code>${JSON.stringify(testCase.expectedOutput, null, 2)}</code></pre></td>
</tr>

Now, finally, we have two successfully failing tests. We're expecting { "name": "End Turn" }, but we actually get "End Turn", becuase I made a mistake last time:

function getActions(gameState) {
    /* ... */
    actions.push('End Turn');
    /* ... */
}

Now we can fix it:

function getActions(gameState) {
    /* ... */
    actions.push({ name: 'End Turn' });
    /* ... */
}

...and test.html tells us "✅ 2 tests passed". That's it. We officially have tests for our project, and have used them to find and fix an error.

Before we forget, commit: "Add tests in test.html, fix 'End Turn' action in getActions()".

This felt sloppier than I want it to be. The code wasn't factored well for testing. The functions in index.js should be separated from the parts that read from window.location.search and write to document.body.innerHTML. And I made several plain mistakes that I would have caught if I had slowed down and re-read my code as I wrote it.

I'm also unsure about the example-based testing approach for the long run. The cases will get very verbose, and writing a thorough set of test cases will take a while. I think a property-based testing approach would suit this project better, so that after writing a generator for input game states, we can write properties for things like "End Turn should always be available" and "if you have at least 1 Energy and a Strike in hand, you can Play Strike".

Still, what we have now is certainly better than nothing.

Oh, before we end, let's add some links to make the pages discoverable from each other:

// index.js, end of rendering code
<a href="./test.html">Tests page</a>

// test.js, end of rendering code
<a href="./index.html">Main page</a>

Commit: "Add links between tests page".

...And heck it, the files should be named "tests" instead of "test". Fix that, fix the links, fix the script source, last commit: "Rename 'test' files to 'tests'".

Next time: Tidying and making this better, probably.

View this app version | Last commit: Add getActions function

So, I'd forgotten that we already do have enemies' next move stored in state and rendered in the HTML. We just need to add their move history. Let's call it moveHistory.

{
    name: 'Jaw Worm',
    hp: 42,
    maxHp: 42,
    block: 0,
    nextMove: 'Chomp',
    moveHistory: [],
    buffs: [],
    debuffs: []
}

Then, for the "end turn" actions, add 'Chomp' to their move history:

<a href="${encodeURI(serialize({
    ...defaultGameState,
    hp: 69,
    hand: ['Defend', 'Strike', 'Strike', 'Strike', 'Strike'],
    discardPile: ['Bash', 'Defend', 'Defend', 'Defend', 'Strike'],
    enemies: [{ ...defaultGameState.enemies[0], moveHistory: ['Chomp'] }]
}))}">
    End turn 1 (60% chance)
</a>

<a href="${encodeURI(serialize({
    ...defaultGameState,
    hp: 69,
    hand: ['Defend', 'Strike', 'Strike', 'Strike', 'Strike'],
    discardPile: ['Bash', 'Defend', 'Defend', 'Defend', 'Strike'],
    enemies: [{ ...defaultGameState.enemies[0], moveHistory: ['Chomp'] }]
}))}">
    End turn 2 (40% chance)
</a>

Then finally, per enemy, display their move history:

${enemy.moveHistory.length > 0 ? `<p>Past moves: ${enemy.moveHistory.join(', ')}</p>` : ''}

Neat! Now the resulting states from the "end turn" action say "Past moves: Chomp"! Commit: "Add moveHistory to enemies".

I noticed we don't update the Jaw Worm's next move in those URLs, so we need to fix that as well:

enemies: [{ ...defaultGameState.enemies[0], moveHistory: ['Chomp'], nextMove: 'Bellow' }]

enemies: [{ ...defaultGameState.enemies[0], moveHistory: ['Chomp'], nextMove: 'Thrash' }]

And then we'll need to update moveDescriptions:

let moveDescriptions = {
    'Chomp': 'Deal 11 damage',
    'Thrash': 'Deal 7 damage, gain 5 Block',
    'Bellow': 'Gain 3 Strength and 6 Block'
};

Done! Commit: "Update enemy nextMove in action URLs".

We're now able to render any game state in the fight based on URL parameters. Nice.

The next step will be a little more complicated. Those hardcoded actions and outcomes need to go, and we need to generate real ones based on the current game state. Once we have that, we'll be truly able to navigate through the entire fight.

I've been thinking about this a lot since last time, so let's establish some key concepts:

• An action is something the player can do anytime they're offered a choice. Examples:
  • Play a card
  • Use a potion
  • End the turn
  • Make a choice an effect asks of them (e.g. after drawing a card, Warcry asks you to place a card in hand back on top of the deck )
• An outcome is a resulting game state from an action.
  • An action may have multiple potential outcomes when randomness is involved (e.g. which cards you draw, what next move the enemy picks, etc.)

Based on this, I think we want two functions:

• getActions(gameState) returns the actions you can take in a given game state.
• getOutcomes(gameState, action) returns the potential outcomes of an action, including the probability of each outcome.

There's lots of ways we could structure the return values of these. In my first go implementing this in C#, "action" objects were tied to the game state they came from, and could .Resolve() to their potential outcomes. I'm going to try restricting actions and outcomes to be pure data this time around, on the hunch that shuffling pure data around will be easier to optimize for performance later than shuffling functions or methods around.

We can start out with this simple schema for actions:

{ name: 'Play Defend' }

Every action has a name property. Some actions may have additional properties:

{ name: 'Play Strike', enemyIndex: 0 }

We can write our getOutcomes function to read the additional properties only as needed, with different blocks of logic running depending on the action's name, which leaves a lot of flexibility for implementing future actions.

The outcome schema can be similarly simple:

{ gameState: gameState, probability: 0.6 }

Given this rough plan, we can break it down into three sequential steps:

1. Implement getActions
2. Implement getOutcomes
3. Update our rendering logic to use these.

Starting with step 1... "Implement getActions" seems a lot more complicated than anything we've done so far. Let's describe the requirements in plain English first, as far as they apply to the Jaw Worm fight:

• If we have Strike in hand and 1 or more Energy, we can 'Play Strike' on the Jaw Worm.
• If we have Bash in hand and 2 or more Energy, we can 'Play Bash' on the Jaw Worm.
• If we have Defend in hand and 1 or more Energy, we can 'Play Defend'.
• We can always 'End Turn'.

Oh. When we put it like this, it looks really straightforward to implement, actually.

function getActions(gameState) {
    let actions = [];
    if (gameState.hand.includes('Strike') && gameState.energy >= 1) {
        actions.push({ name: 'Play Strike', enemyIndex: 0 });
    }
    if (gameState.hand.includes('Bash') && gameState.energy >= 2) {
        actions.push({ name: 'Play Bash', enemyIndex: 0 });
    }
    if (gameState.hand.includes('Defend') && gameState.energy >= 1) {
        actions.push({ name: 'Play Defend' });
    }
    actions.push('End Turn');
    return actions;
}

Although, now I realize there are lots of cases our requirements don't handle. What if we're dead? What if we have multiple enemies?

And for that matter, how do we check that this code even works? So far, we've been refreshing the page, clicking around and seeing if everything looks correct, but now we have a lot more cases to check, and this isn't even wired up to the page yet.

I think this is the signal to start writing tests. For now, let's leave a comment above the function:

// TODO: Test

And commit: "Add getActions function".

Next time: setting up our first tests!

View this app version | Last commit: Add getActions function

The goal this time is to add enemy armor, buffs and debuffs to the dynamic state. The Jaw Worm gains armor and the Strength buff when using Bellow, and... hold up, I think I have some inconsistent terminology here.

Double-checking, and yes, it's not called "armor", it's called "block". Let's search, replace and commit: "Rename 'Armor' to 'Block'".

Take two: The goal this time is to add enemy block, buffs and debuffs. The Jaw Worm gains block and the Strength buff when using Bellow, and gains the Vulnerable debuff when we play Bash.

Adding Vulnerable seems most straightforward, since we already have an action that's supposed to add it. We can add a debuffs property to the default Jaw Worm enemy object:

{
    name: 'Jaw Worm',
    hp: 42,
    maxHp: 42,
    nextMove: 'Chomp',
    debuffs: []
}

Then, we need to update the serialized "enemies" data in our URLs, to make sure they include the debuffs array. This is a bit of a pain, as I had to look up how to URI encode JSON again, and the strings I get now have less characters replaced than what's committed from before, which makes me nervous I'm doing it wrong. The data seems to deserialize fine, though, so let's just commit: "Add 'debuffs' array to enemy state".

Before we go any further, I want to reduce the pain of updating the URLs. Let's refactor and add some helpful functions. I want a serialize function that takes a game state object and serializes it to a URL query string, and I want a deserialize function that takes a URL query string and deserializes it to a game state object.

Step one: gather all our state variables into a single object.

let gameState = {
    hp: queryParams.get('hp') ?? 80,
    maxHp: queryParams.get('maxhp') ?? 80,
    block: queryParams.get('block'),
    energy: queryParams.get('energy') ?? 3,
    maxEnergy: queryParams.get('maxenergy') ?? 3,
    hand: queryParams.get('hand')?.split(',') ?? ['Bash', 'Defend', 'Defend', 'Defend', 'Strike'],
    drawPile: queryParams.get('draw')?.split(',') ?? ['Defend', 'Strike', 'Strike', 'Strike', 'Strike'],
    discardPile: queryParams.get('discard')?.split(',') ?? [],
    relics: queryParams.get('relics')?.split(',') ?? ['Burning Blood'],
    enemies: JSON.parse(queryParams.get('enemies')) ?? [
        {
            name: 'Jaw Worm',
            hp: 42,
            maxHp: 42,
            nextMove: 'Chomp',
            debuffs: []
        }
    ]
}

This also requires adding gameState. in front of everywhere we use these variables, e.g. <p>HP: ${gameState.hp}/${gameState.maxHp}</p>. The page still loads fine, so this seems committable: "Gather game state variables into a gameState object".

Step two: move our deserialization code into a deserialize function.

function deserialize(queryString) {
    let queryParams = new URLSearchParams(queryString);
    return  {
        hp: queryParams.get('hp') ?? 80,
        maxHp: queryParams.get('maxhp') ?? 80,
        block: queryParams.get('block'),
        energy: queryParams.get('energy') ?? 3,
        maxEnergy: queryParams.get('maxenergy') ?? 3,
        hand: queryParams.get('hand')?.split(',') ?? ['Bash', 'Defend', 'Defend', 'Defend', 'Strike'],
        drawPile: queryParams.get('draw')?.split(',') ?? ['Defend', 'Strike', 'Strike', 'Strike', 'Strike'],
        discardPile: queryParams.get('discard')?.split(',') ?? [],
        relics: queryParams.get('relics')?.split(',') ?? ['Burning Blood'],
        enemies: JSON.parse(queryParams.get('enemies')) ?? [
            {
                name: 'Jaw Worm',
                hp: 42,
                maxHp: 42,
                nextMove: 'Chomp',
                debuffs: []
            }
        ]
    }
}

let gameState = deserialize(window.location.search);

Runs fine, commit: "Extract deserialize(queryString) function".

Step three: write a serialize function, and use it to generate the URLs we need.

function serialize(gameState) {
    return `?hp=${gameState.hp}`
        + `&maxhp=${gameState.maxHp}`
        + `&block=${gameState.block}`
        + `&energy=${gameState.energy}`
        + `&maxenergy=${gameState.maxEnergy}`
        + `&hand=${String.join(gameState.hand, ',')}`
        + `&draw=${String.join(gameState.drawPile, ',')}`
        + `&discard=${String.join(gameState.discardPile, ',')}`
        + `&relics=${String.join(gameState.relics, ',')}`
        + `&enemies=${JSON.stringify(gameState.enemies)}`;
}

I think I did that right, so let's test it out:

<a href="${encodeURI(serialize({ ...gameState, energy: 1, hand: ['Defend', 'Defend', 'Defend', 'Strike'], discardPile: ['Bash'], enemies: [{ ...gameState.enemies[0], hp: 34 }]}))}">
    Play Bash on Jaw Worm
</a>

Still some effort to write out, but somewhat easier to read and modify. Testing it out, we get an error in the console: "Uncaught TypeError: String.join is not a function". Whoops, I forgot how joining an array into a string works. This should work instead:

        + `&hand=${gameState.hand.join(',')}`
        + `&draw=${gameState.drawPile.join(',')}`
        + `&discard=${gameState.discardPile.join(',')}`
        + `&relics=${gameState.relics.join(',')}`

Success! The page renders, the URL looks alright, and clicking on it renders a correctly updated page! ...mostly.

Below player HP it now says:

Block: null

That doesn't look right. When we don't have block, it gets serialized as the string "null". Having no block probably shouldn't be stored as null. Storing it as 0 sounds correct, and since 0 is falsy, the templating logic we've written should still work.

Update deserialize to default block to 0:

        block: queryParams.get('block') ?? 0,

Bingo! Works like a charm now. Let's rewrite the remaining four URLs:

<a href="${encodeURI(serialize({ ...gameState, energy: 2, hand: ['Bash', 'Defend', 'Defend', 'Defend'], discardPile: ['Strike'], enemies: [{ ...gameState.enemies[0], hp: 36 }] }))}">
    Play Strike on Jaw Worm
</a>

<a href="${encodeURI(serialize({ ...gameState, block: 5, energy: 2, hand: ['Bash', 'Defend', 'Defend', 'Strike'], discardPile: ['Defend'] }))}">
    Play Defend
</a>

<a href="${encodeURI(serialize({ ...gameState, hp: 69, hand: ['Defend', 'Strike', 'Strike', 'Strike', 'Strike'], discardPile: ['Bash', 'Defend', 'Defend', 'Defend', 'Strike'] }))}">
    End turn 1 (60% chance)
</a>

<a href="${encodeURI(serialize({ ...gameState, hp: 69, hand: ['Defend', 'Strike', 'Strike', 'Strike', 'Strike'], discardPile: ['Bash', 'Defend', 'Defend', 'Defend', 'Strike'] }))}">
    End turn 2 (40% chance)
</a>

Yes, far more readable. And it all seems to work! Though, clicking around, it seems that by using gameState to produce our URLs, we can now end up in game states that partially combine the effects of each action. For instance, clicking "Play Strike on Jaw Worm" then "Play Defend" puts us in a state where we have 5 Block and the Jaw Worm has 36 HP. It's not a valid state, since we still have 2 Energy left and Strike in hand, but hey, kind of neat. Commit: "Create URLs with new serialize function".

Neat as that bug is, let's clean it up by creating a defaultGameState and basing default state and the action URLs on that.

let defaultGameState = {
    hp: 80,
    maxHp: 80,
    block: 0,
    energy: 3,
    maxEnergy: 3,
    hand: ['Bash', 'Defend', 'Defend', 'Defend', 'Strike'],
    drawPile: ['Defend', 'Strike', 'Strike', 'Strike', 'Strike'],
    discardPile: [],
    relics: ['Burning Blood'],
    enemies: [
        {
            name: 'Jaw Worm',
            hp: 42,
            maxHp: 42,
            nextMove: 'Chomp',
            debuffs: []
        }
    ]
};

Now we can use that state if the URL has no query string, and remove the default values from deserialize, since every query string will now have fully serialized game state data:

let gameState = window.location.search ? deserialize(window.location.search) : defaultGameState;

function deserialize(queryString) {
    let queryParams = new URLSearchParams(queryString);
    return {
        hp: queryParams.get('hp'),
        maxHp: queryParams.get('maxhp'),
        block: queryParams.get('block'),
        energy: queryParams.get('energy'),
        maxEnergy: queryParams.get('maxenergy'),
        hand: queryParams.get('hand')?.split(','),
        drawPile: queryParams.get('draw')?.split(','),
        discardPile: queryParams.get('discard')?.split(','),
        relics: queryParams.get('relics')?.split(','),
        enemies: JSON.parse(queryParams.get('enemies'))
    }
}

Seems to work. Commit: "Replace defaults in deserialize() with defaultGameState object". Then, replace our use of gameState with defaultGameState when generating URLs, like so:

<a href="${encodeURI(serialize({ ...defaultGameState, energy: 1, hand: ['Defend', 'Defend', 'Defend', 'Strike'], discardPile: ['Bash'], enemies: [{ ...defaultGameState.enemies[0], hp: 34 }] }))}">
    Play Bash on Jaw Worm
</a>

Now the URLs stay consistent regardless of current game state. Commit: "Base URLs on defaultGameState instead of current gameState".

Whoops. Seems to be a bug now where zero block gets deserialized as the string "0", so the page says "Block: 0". Let's update deserialize to convert strings to numbers where appropriate:

    hp: Number(queryParams.get('hp')),
    maxHp: Number(queryParams.get('maxhp')),
    block: Number(queryParams.get('block')),
    energy: Number(queryParams.get('energy')),
    maxEnergy: Number(queryParams.get('maxenergy')),

That fixes it. Commit: "Correctly deserialize number properties as numbers instead of strings"

Whew. I think that's enough refactoring done to the point where we can continue adding the Vulnerable debuff.

We need to store two aspects of debuffs in state: which debuff it is (by its name, probably), and how many "stacks" it has. Most buffs and debuffs are stackable, which either intensifies it (in Strength's case) or increases its duration (in Vulnerable's case).

Going off of this, we could represent the Vulnerable debuff as an object:

{ name: 'Vulnerable', stacks: 2 }

Add it to the enemy's debuffs when playing Bash:

<a href="${encodeURI(serialize({ ...defaultGameState, energy: 1, hand: ['Defend', 'Defend', 'Defend', 'Strike'], discardPile: ['Bash'], enemies: [{ ...defaultGameState.enemies[0], hp: 34, debuffs: [{ name: 'Vulnerable', stacks: 2 }] }] }))}">
    Play Bash on Jaw Worm
</a>

Then for each enemy, render enemy.debuffs similarly to how we render cards and relics:

<details open>
    <summary>Debuffs (${enemy.debuffs.length})</summary>
    <ul>
        ${enemy.debuffs.map(debuff =>
            `<li>${debuff.name} (${debuff.stacks})</li>`
        ).join('')}
    </ul>
</details>

Putting it all together, it works! That was easy enough. Though I'm not sure I like displaying a collapsible list of zero debuffs, so let's only render it when the enemy has at least one debuff:

${enemy.debuffs.length > 0 ?
`<details open>
    <summary>Debuffs (${enemy.debuffs.length})</summary>
    <ul>
        ${enemy.debuffs.map(debuff => `<li>${debuff.name} (${debuff.stacks})</li>`).join('')}
    </ul>
</details>`
: ''}

Looks better. Now we can commit: "Add Vulnerable debuff when playing Bash".

For adding enemy block and Strength, none of the existing links in our template should lead to that, as the Jaw Worm is not about to use Bellow. To work around this, we can add a test link to the bottom of the page.

<h2>Test links</h2>
<a href="${encodeURI(serialize({ ...defaultGameState /* TODO: assign strength and block */ }))}">
    Jaw Worm with 3 Strength and 6 Block
</a>

Enemy block can be a block property, enemy buffs can be a buffs property, and each buff can have a name and stacks, just like debuffs.

We add the properties to our default game state:

{
    name: 'Jaw Worm',
    hp: 42,
    maxHp: 42,
    block: 0,
    nextMove: 'Chomp',
    buffs: [],
    debuffs: []
}

Update block and buffs in our test link:

<a href="${encodeURI(serialize({ ...defaultGameState, enemies: [{ ...defaultGameState.enemies[0], block: 6, buffs: [{ name: 'Strength', stacks: 3 }] }] }))}">
    Jaw Worm with 3 Strength and 6 Block
</a>

Then render enemy block and buffs like we render player block and enemy debuffs:

${enemy.block ? `<p>Block: ${enemy.block}</p>` : ''}

${enemy.buffs.length > 0 ?
`<details open>
    <summary>Buffs (${enemy.buffs.length})</summary>
    <ul>
        ${enemy.buffs.map(buff => `<li>${buff.name} (${buff.stacks})</li>`).join('')}
    </ul>
</details>`
: ''}

Save, reload the page - curious, the page fails to render, and we have an error in the console: "Uncaught TypeError: can't access property "length", enemy.buffs is undefined". Turns out I have an old serialied state in the URL where buffs doesn't exist yet. Clearing the query string fixes it.

Now, clicking the test link, it says the Jaw Worm has 6 Block and a 3 Strength. Success! We can commit: "Add enemy block and buffs, add test link for this".

I'm fairly happy with progress this time. We have more maintainable code for serializing and deserializing game state, our action links are easier to keep up-to-date, and a little more of the game state is now representable.

If my counting is correct, the only piece of game state missing to be able to represent any moment in the Jaw Worm fight is the Jaw Worm's next move and its history of previous moves (to determine possible next moves). A good task for next time.

View this app version | Last commit: Set 'enemies' array based on query parameter

There's still a fair bit of game state to make dynamic, namely the enemy. This fight has one enemy, but there can be several enemies, and each of them has:

• A name
• HP
• Armor
• Buffs and debuffs
• Its next move
• A history of previous moves
  • This affects which move it may choose next

All of these need to be made into a variable (an array of "enemy" objects, most likely), and then we need a way to encode it into the query string. Let's save the tricky bit for later, and hard-code the data first:

let enemies = [
    {
        name: 'Jaw Worm',
        hp: 42,
        maxHp: 42,
        nextMove: 'Chomp'
    }
];

Then use the data in our templating:

<h2>Enemies</h2>
${enemies.map(enemy => `
    <h3>${enemy.name}</h3>
    <p>HP: ${enemy.hp}/${enemy.maxHp}</p>
    <p>Next move: ${enemy.nextMove}</p>
`).join('')}

Looks okay, but we're missing the move description now. I don't think this is the long-term solution, but let's make a dictionary of descriptions, just like we did for relics, to keep it out of the dynamic state.

let moveDescriptions = { 'Chomp': 'Deal 11 damage' };
// ...
<p>Next move: ${enemy.nextMove} (${moveDescriptions[enemy.nextMove]})</p>

Oh yeah, this is going to be a problem very soon. The Jaw Worm deals more than 11 damage when it gains strength, so a static dictionary of descriptions is not going to cut it. That's a future problem though, and an interesting one at that. Future us can spend a whole session figuring that out.

Commit: "Render enemies based on 'enemies' array".

Now the difficult part. We need to encode this data, this array of objects, into our query string. We've only handled simple values and lists of simple values to this point. We need a different method for handling a list of objects.

Starting with the simplest thing that will possibly work... Can we just parse it as JSON?

let enemies = JSON.parse(queryParams.get('enemies')) ?? [
    {
        name: 'Jaw Worm',
        hp: 42,
        maxHp: 42,
        nextMove: 'Chomp'
    }
];

Well, the fallback value works correctly when "enemies" is missing from the query string.

Now what if we add ?enemies=[] to it? Aha! No enemies!

Then what about ?enemies=[{"name": "Jaw Worm", "hp": 30, "maxHp": 42, "nextMove": "Chomp"}]? Goodness, me, it works. Didn't even need to deal with URI encoding.

Let's add this query parameter to our sketched action links, so we can finally see our attacks dealing damage:

<a href="?maxhp=80&maxenergy=3&relics=Burning%20Blood&hp=80&energy=1&hand=Defend,Defend,Defend,Strike&draw=Defend,Strike,Strike,Strike,Strike&discard=Bash&enemies=%5B%7B%22name%22%3A%20%22Jaw%20Worm%22%2C%20%22hp%22%3A%2034%2C%20%22maxHp%22%3A%2042%2C%20%22nextMove%22%3A%20%22Chomp%22%7D%5D">
    Play Bash on Jaw Worm
</a>
// ...
<a href="?maxhp=80&maxenergy=3&relics=Burning%20Blood&hp=80&energy=2&hand=Bash,Defend,Defend,Defend&draw=Defend,Strike,Strike,Strike,Strike&discard=Strike&enemies=%5B%7B%22name%22%3A%20%22Jaw%20Worm%22%2C%20%22hp%22%3A%2036%2C%20%22maxHp%22%3A%2042%2C%20%22nextMove%22%3A%20%22Chomp%22%7D%5D">
    Play Strike on Jaw Worm
</a>

Had to URI-encode the array to fit it into the HTML, but the JSON parsing still works. And these links work! We're dealing damage!

Commit: "Set 'enemies' array based on query parameter".

All this URL parsing is very space-inefficient, but I don't think it the URL will grow long enough to cause issues while we're only running the Jaw Worm fight. It's good enough for now.

Hm, I keep excusing design flaws that I imagine we will fix later. I wonder if that's necessary.

Anyway. Next time: enemy armor, buffs, and debuffs.

View this app version | Last commit: Set 'enemies' array based on query parameter

Currently, our page is a bit of dynamically rendered HTML. Some of the content is based on the query string, others are hard-coded. The next logical step is making a little bit less of it hard-coded. Adding armor seems like a nice way to warm up.

Hmm. First I want to do a little refactoring. I want to extract our JavaScript to a separate file. It's not strictly necessary, and has a couple of cons (like adding another round-trip time on first page load, and not being able to throw our whole project around as a single HTML file), but it has several pros that I want right now:

• We can look at all the already-getting-quite-hairy parsing logic and templating without looking at all the HTML wrapping it.
• We can comfortably remove one level of indentation.
• Down the line, we want to be able to test the code, and having a separate file we can import the code from will help us out a lot.

So, creating a file... What's the default name people give JavaScript files now, anyway? script.js? main.js? index.js? index.js lines up neatly with index.html in the file explorer, so let's go with that.

Wow, I've forgotten how to link to external JavaScript files from HTML, it's been so long since I set up a new project without a build system. Quick jump to the MDN <script> element page...

Whew, there's quite a few attributes to choose from nowadays! But after copying and pasting our JavaScript to the new file, it looks like we don't need any of the type or async or defer stuff, all we need to write is:

<script src="index.js"></script>

I'm wondering if we should also add type="module". JavaScript modules are the modern way of structuring code, but a quick scan of the JavaScript modules page reminds me that, yeah, it only really matters for exporting and importing code, and I'm not planning on splitting index.js into multiple files anytime soon. Let's keep it dead simple and omit it.

Commit: "Extract JavaScript to index.js".

Back to armor. Let's start by sketching it up in hardcoded HTML:

<p>Armor: 5</p>

Yeah, that's simple. And when there is no armor, we want to omit that paragraph entirely. Let's make it dynamic by adding a query parameter for "armor":

let armor = queryParams.get('armor');

We're not assigning a fallback value here if "armor" is missing, because a null value is going to work fine the way we'll use it:

${armor ? `<p>Armor: ${armor}</p>` : ''}

JavaScript type coercion is great, actually. If armor is any kind of falsy value, like null, undefined, or 0, it evaluates to false and we render an empty string. If it has a truthy value - in other words, if we have any kind of armor - we render it in a paragraph. This is really handy and terse! But we need to see that it works, first. Let's add &armor=5 to our "Play Defend" query string:

<a href="?maxhp=80&maxenergy=3&relics=Burning%20Blood&hp=80&armor=5&energy=2&hand=Bash,Defend,Defend,Strike&draw=Defend,Strike,Strike,Strike,Strike&discard=Defend">
    Play Defend
</a>

Wow, these URLs are getting terribly long. But it works! We get "Armor: 5" on that page, and nothing on the others. Commit: "Render armor based on query parameter"

Ah, my hour is already up. Small progress, but progress nonetheless.

View this app version | Last commit: Render armor based on query parameter

I've been thinking, for this project, that I want to make things fit into little steps, little sessions. If all I have is a little less than an hour, then I want to be able to fit writing a post and making some progress into that little hour. I have a few minutes to spare this evening, so let's see if we can put something out this week and give this thing a little heartbeat.

I think it's time we set up version control for this. I want to have the file backed up somewhere else, I want to have a version history I can look back through, and I want to be able to link to specific snapshots of the code in these posts. No time better than now to get that set up.

Currently I host all my code on GitHub. I've thought about moving to a different host for anti-GitHub-Microsoft-monopoly reasons, but...

I was going to say I don't have time to set it up elsewhere right now, but do I know that's true? Let's set this project up on another Git hosting service I've been vaguely aware of: Codeberg. It's a "democratic, community-driven non-profit." Sounds neat!

Step 1: Create account

• Took me a couple of minutes, mostly waiting for the "confirm your account" email to show up.

Step 2: Go to settings and set up the SSH keys I expect I'll need

• Oh hey I can set my pronouns for my profile here! Neat.
• I already have an SSH public/private key pair set up locally, so probably I can just add my public key to Codeberg...?
• Yup! Looks like it worked.

Step 3: Create a repository for our project

• Gah, I already have a project named "slay-the-spire-solver" from my 2022 go at this. And naming it generically would be boring.
• I think... I can make a swing for it an pick a name for the project now. What about...
• Crystal Spire?
• It's just unique enough (searching for it online gives me results for a World of Warcraft quest/item, I'm fine colliding with that), and crystal is a sort of material you can see through, but can also split light many, many ways? Sort of like we want to look through battles throughout the Spire?
• That's it, I'm committing to it. cvennevik/crystal-spire created. Description: "A tool for analyzing combat encounters in Slay the Spire."

Step 4: Initialize the repository with our code

• Okay so I want to do something here that will make this step harder. I want to create commits, retroactively, for the state of the code after each of the blog posts that I've written so far. I think it would be fun to follow the evolution of the project step by step like that.
• I'll create a fresh "crystal-spire" directory on my computer and initialize the Git repository there.
• Then, following my old blog posts, copying and pasting, let's see what we get...
  • First post. Create an initial index.html. Commit: "#1: HTML first".
  • Second post. Commit: "#2: Actions and consequences".
  • Third post. Commit: "#3: Introducing links".
  • Fourth post has no code changes.
  • Fifth post. Phew, here I can just copy and paste my latest version. Commit: "#5: Going dynamic".

And... that's it. The project is now version controlled. This is very comforting to me, as I like to use Git to keep track of current changes, and I commit frequently. When something's broken or half-done, it's stressful to me to have a lot of code in the air. I like being able to scrap everything I've done and return to a last known healthy point. Especially for a project like this that I want to make friendly to my short attention spans.

I'm going to go back and put links to these in all the previous posts. Ideally, I'd also want a link to the live version of the code at each version, so you can check it out and play around, but that looks non-trivial. Another time, maybe.

Now. One extra commit. To make the naming consistent.

<title>Crystal Spire</title>

<h1>Crystal Spire</h1>

Commit: "Rename to Crystal Spire".

That's nice.

View this app version | Last commit: "Rename to Crystal Spire"

This morning I read "Learning and Hacking" by Alan Page, which includes a copy of the essay "Always Put Yourself On The Steepest Learning Curve." And now that's bouncing around in my mind too.

Add a shot of recent personal events, shake vigorously, and now I am losing my mind.

This week I crashed headfirst into what I'm being forced to call "burnout," and I've realized that part of what brought it on is being persistently under-challenged. I haven't been doing "hard things" at my job for... hell, over a year now? And it's been grating on me to the point where, now, my soul cannot take it anymore?

And now Chance has it to put phrases like "you can do hard things" and "put yourself on the steepest learning curve" into my head this weekend and now I have too many things on my mind and I have to reconsider my entire work situation.

Today we're going to have some fun. We're going to make our page content dynamic, based on the page URL.

To do that, we have to commit to an approach for rendering dynamic HTML.

I'm a professional web developer. As is the way of things, of modern web development, I've only ever really worked with JavaScript frameworks. My experience with authoring dynamic web pages is mainly by using Vue. Building this project as a Vue app would be familiar and easy to me.

Here's the rub: I don't want to use a JavaScript framework for this project.

There's a mix of reasons for this, some more frivolous than others. If I'm being honest, the core reason is a certain sense of craft snobbishness. I like to author lean web pages that are fast to transfer, fast to parse, fast to run. Wherever possible, I like to build things myself using the features of the platform, instead of introducing dependencies like frameworks and libraries. I like to keep the total technology stack simple, shallow, shelf-stable.

I know, rationally, that it won't make a difference to user experience if I author this using a performant framework like Svelte or Solid. It would probably be less code to write, in total. I might get things done quicker. Be more productive.

But I don't wanna. I don't even wanna install any npm packages. I wanna try doing this all with vanilla JavaScript. Call it a learning experience, because I've never rendered dynamic UI in vanilla JavaScript before. But by God I am going to stumble my way through this and drag you with me.

I did a little bit of research to see what approaches exist for changing the DOM with JavaScript. Of the ones I found, one stood out as being the least fuss to get started with: innerHTML.

Here's what we do: Add a little script to the bottom of our document...

<script>

</script>

...and set document.body.innerHTML.

<script>
    document.body.innerHTML = "<h1>Hello World</h1>";
</script>

Now our page says "Hello World"! We've successfully changed the page content with JavaScript, in one line of fairly uncomplicated code. Sadly, this also replaces all the HTML we've written up to this point, but we're about to fix that.

Bear with me. The next step may not be for the faint of heart.

<body>
    <!-- Cut... -->
</body>
<script>
    // ...and paste.
    document.body.innerHTML = `
        <h1>Slay the Spire solver</h1>
        <h2>Player: Ironclad</h2>
        <p>HP: 80/80</p>
        <p>Energy: 3/3</p>
        <details open>
            <summary>Hand (5)</summary>
            <ul>
                <li>Bash</li>
                <li>Defend</li>
                <li>Defend</li>
                <li>Defend</li>
                <li>Strike</li>
            </ul>
        </details>
        <details>
            <summary>Draw pile (5)</summary>
            <ul>
                <li>Defend</li>
                <li>Strike</li>
                <li>Strike</li>
                <li>Strike</li>
                <li>Strike</li>
            </ul>     
        </details>
        <details>
            <summary>Discard pile (0)</summary>
        </details>
        <details>
            <summary>Relics (1)</summary>
            <ul>
                <li>Burning Blood <i>(At the end of combat, heal 6 HP)</i></li>
            </ul>
        </details>
        <h2>Enemies</h2>
        <h3>Jaw Worm</h3>
        <p>HP: 42/42</p>
        <p>Next move: Chomp (Deal 11 damage)</p>
        <h2>Actions</h2>
        <h3><a href="#">Play Bash on Jaw Worm</a></h3>
        <ul>
            <li>Player: -2 Energy</li>
            <li>Hand: -1 Bash</li>
            <li>Discard pile: +1 Bash</li>
            <li>Jaw Worm: -8 HP, +2 Vulnerable</li>
        </ul>
        <h3><a href="#">Play Strike on Jaw Worm</a></h3>
        <ul>
            <li>Player: -1 Energy</li>
            <li>Hand: -1 Strike</li>
            <li>Discard pile: +1 Strike</li>
            <li>Jaw Worm: -6 HP</li>
        </ul>
        <h3><a href="#">Play Defend</a></h3>
        <ul>
            <li>Player: -1 Energy, +5 Armor</li>
            <li>Hand: -1 Defend</li>
            <li>Discard pile: +1 Defend</li>
        </ul>
        <h3>End turn</h3>
        <ul>
            <li>Player: -11 HP</li>
            <li>Hand: -1 Bash, -2 Defend, +3 Strike</li>
            <li>Draw pile: -4 Strike, -1 Defend</li>
            <li>Discard pile: +1 Bash, +3 Defend, +1 Strike</li>
        </ul>
        <h4><a href="#">End turn 1 (60% chance)</a></h4>
        <ul>
            <li>Jaw Worm: next move Bellow (gain 3 Strength and 6 Block)</li>
        </ul>
        <h4><a href="#">End turn 2 (40% chance)</a></h4>
        <ul>
            <li>Jaw Worm: next move Thrash (deal 7 damage, gain 5 Block)</li>
        </ul>
    `;
</script>

Now - as long as you have JavaScript enabled - the page looks just like before. We've committed a slight crime against HTML by turning it into a JavaScript string, but hey, we're still authoring HTML, just uh, not in the actual HTML itself.

Oh, we should leave a note for visitors with JavaScript disabled...

<body>
    <noscript>
        This application only works with JavaScript enabled.
    </noscript>
</body>

Testing it by disabling JavaScript in the browser devtools. Yeah, it works.

Now what was the point of this crime? Well, now we can do this:

<script>
    let queryString = window.location.search;
    document.body.innerHTML = `
        <h1>Slay the Spire solver</h1>
        <p>Query string: ${queryString}</p>
        ...
    `;
</script>

Opening index.html, and the new paragraph just says "Query string". But if we open index.html?hello=world, we get "Query string: ?hello=world"! We can now use the query string to change page contents!

Okay okay let's roll back that example and do something useful with this. Let's try setting the player HP using ?hp=80.

let queryParams = new URLSearchParams(window.location.search);
let hp = queryParams.get('hp');
document.body.innerHTML = `
    ...
    <p>HP: ${hp}/80</p>
    ...
`;

Visiting index.html?hp=80, it works! Oh, but visiting index.html it now says "HP: null/80". We had better fall back to a default value when it's not set.

let hp = queryParams.get('hp') ?? 80;

There, back to normal. We can do the same for energy:

let energy = queryParams.get('energy') ?? 3;
// ...
<p>Energy: ${energy}/3</p>

For cards in hand it's not as straightforward because it's a list. We could do ?hand=Bash,Defend,Defend,Defend,Strike, and generate the list like this:

let hand = queryParams.get('hand')?.split(',') ?? ['Bash', 'Defend', 'Defend', 'Defend', 'Strike'];
// ...
<details open>
    <summary>Hand (${hand.length})</summary>
    <ul>
        ${hand.map(card =>
            `<li>${card}</li>`
        ).join('')}
    </ul>
</details>

Same for discard pile and draw pile!

let drawPile = queryParams.get('draw')?.split(',') ?? ['Defend', 'Strike', 'Strike', 'Strike', 'Strike'];
let discardPile = queryParams.get('discard')?.split(',') ?? [];
// ...
<details>
    <summary>Draw pile (${drawPile.length})</summary>
    <ul>
        ${drawPile.map(card =>
            `<li>${card}</li>`
        ).join('')}
    </ul>
</details>
<details>
    <summary>Discard pile (${discardPile.length})</summary>
    <ul>
        ${discardPile.map(card =>
            `<li>${card}</li>`
        ).join('')}
    </ul>
</details>

And for completeness, though we won't change them our scenario, let's set maximum HP, maximum energy, and relics.

let maxHp = queryParams.get('maxhp') ?? 80;
let maxEnergy = queryParams.get('maxenergy') ?? 3;
let relics = queryParams.get('relics')?.split(',') ?? ['Burning Blood'];
// ...
<p>HP: ${hp}/${maxHp}</p>
<p>Energy: ${energy}/${maxEnergy}</p>
// ...
<details>
    <summary>Relics (${relics.length})</summary>
    <ul>
        ${relics.map(relic =>
            `<li>${relic}</li>`
        ).join('')}
    </ul>
</details>

Sweet. All the player data can be controlled by query string now. Oh, but we lost one thing in the process: the description for Burning Blood. I think we could write relic descriptions in an object, and look it up from there:

let relicDescriptions = { 'Burning Blood': 'At the end of combat, heal 6 HP' };
// ...
`<li>${relic} <i>(${relicDescriptions[relic]})</i></li>`

Yeah, works fine!

Next up would be enemy state, but I'm running out of time and energy for the day, and it looks tricky enough that I want to make it its own session. Before we wrap, let's make our links do something. We can't set all of the state yet, so we will just set the parts we are able to:

<h3>
    <a href="?maxhp=80&maxenergy=3&relics=Burning%20Blood&hp=80&energy=1&hand=Defend,Defend,Defend,Strike&draw=Defend,Strike,Strike,Strike,Strike&discard=Bash">
        Play Bash on Jaw Worm
    </a>
</h3>
<h3>
    <a href="?maxhp=80&maxenergy=3&relics=Burning%20Blood&hp=80&energy=2&hand=Bash,Defend,Defend,Defend&draw=Defend,Strike,Strike,Strike,Strike&discard=Strike">
        Play Strike on Jaw Worm
    </a>
</h3>
<h3>
    <a href="?maxhp=80&maxenergy=3&relics=Burning%20Blood&hp=80&energy=2&hand=Bash,Defend,Defend,Strike&draw=Defend,Strike,Strike,Strike,Strike&discard=Defend">
        Play Defend
    </a>
</h3>
<h4>
    <a href="?maxhp=80&maxenergy=3&relics=Burning%20Blood&hp=69&energy=3&hand=Defend,Strike,Strike,Strike,Strike&draw=&discard=Bash,Defend,Defend,Defend,Strike">
        End turn 1 (60% chance)
    </a>
</h4>
<h4>
    <a href="?maxhp=80&maxenergy=3&relics=Burning%20Blood&hp=69&energy=3&hand=Defend,Strike,Strike,Strike,Strike&draw=&discard=Bash,Defend,Defend,Defend,Strike">
        End turn 2 (40% chance)
    </a>
</h4>

Now we have it! We have links to different game states! 🎉

There's just a few things left to fix before the scenario is fully-functioning, for some strained definition of "just a few":

1. Controlling enemy state via query string
2. Adding player armor
3. Adding enemy armor and debuffs
4. Generating valid actions based on the current state

The first item will probably be one session of work, and the second and third another session. The fourth might take a little bit longer. Probably longer than all the work to that point put together.

Caveats before closing:

• innerHTML is very simple and fun to work with. Setting it is also a security risk in case of malicious user input. Here, we're interpolating query parameters directly into the HTML, so it's trivial to craft URLs that add anything to the document. It's not ideal, but I'm choosing to accept this risk for now.
• This simple scheme of using query parameters for each part of the state takes a lot of characters, and complex game states may need thousands of characters in the query string. Down the line, we'll want to encode this data in a more compact way.

Mmh. Tired now. Write more later.

View this app version | Last commit: "#5: Going dynamic"

1. My unease with the navigation issue, overriding and re-implementing link behavior.
2. How to dynamically render the HTML based on game state.

I have a good idea for that second issue now, but I just returned from holiday, and lack the time and energy to finish it today. Ideally, I'd like to get a bit of coding done in each post I do, but if I leave this post in the pipes for a third day in a row, I'm going to feel constipated.

Today, we're only talking navigation.

To recap the navigation issue: I concluded that we want to navigate between game states, as if they were pages, and that links are the most appropriate UI control for that. I also concluded that we will have too much state to keep all the data in URLs, meaning we have to override normal link behavior and re-implement it all to work with our application state.

I was aware, at the time, that it would be messy and difficult to do right. Having sat with it for a day, it now looks even worse in my mind.

When pages have state stored outside the URL, and links modify that state instead of navigating to a URL, here are all the affordances I can think of that we lose:

• Page history
• Navigating to the next/previous page
• Opening links in a new tab
• Reloading pages without losing data
• Browser bookmarks
• Sharing page links with others

Some of those items sound like a pain to re-implement to the standard of normal links. The rest of them sound impossible to re-implement to the same standard.

These affordances are useful and expected. Messing them up would make our app kind of crap. I don't want to make this project kind of crap, I want to make it nice. Messing with link behavior would make a mess that we cannot clean up.

However. I was struck with an idea. I think it is possible to fit all the necessary page state in less than a couple thousand characters. And if we accomplish that, the constraint that pushed us down this dark path in the first place is gone.

In other words:

Plain links are back on menu!

View this app version | Last commit: "#3: Introducing links"

Last time, I said we were aiming to explore the branching paths a game of Slay the Spire can take. A key feature - maybe the key feature - would be to view the resulting state of an action's outcome. And I think that means selecting an outcome, then having that outcome's state displayed on the screen, with all of its actions and all of their outcomes. And then you should be able to view a next outcome a level deeper, and again, and you should be able to move back to a previous one you have viewed.

This app needs to let you navigate between states.

That means links. With custom behavior. And messing with the browser history so back/forward buttons work as expected.

I mean, maybe we can avoid that? Maybe the links can have query strings defining the complete next state? But no, no, the page should show you the path from the initial state, dozens and dozens of actions deep, with links to jump back to them. We can't fit all of that data into a query string, because I'm pretty sure browsers won't guarantee what happens when URLs exceed 2048 characters. And there's all kinds of other persistent state we may want.

I think there's no way around it.

Boy, what a can of worms we have in store for us.

Thankfully, to sketch out the HTML, we can leave that can of worms on the table, unopened. That's all implementation details, and we're not implementing anything yet.

So. Every outcome wants a link. Every link wants text that describes the page it leads to. The outcome headings are precisely that. Let's reuse them.

<h3><a href="">Play Bash on Jaw Worm</a></h3>

Yeah, visually, that looks good to me. I'm unsure about the href value - I know that href="#" is safe for links that shouldn't take you off the current page, but href="" seems to have the same effect. Let me look up what the difference is.

Huh. Hard to test on my phone, but some people say that href="" actually reloads the page, while href="#" jumps to the top of the page? The latter seems like less trouble. If it's the wrong approach, it should be easy to fix later.

<h3><a href="#">Play Bash on Jaw Worm</a></h3>

Now for Strike:

<h3><a href="#">Play Strike on Jaw Worm</a></h3>

And Defend:

<h3><a href="#">Play Defend</a></h3>

And end turn... uh oh:

<h3>End turn</h3>
<ul>
    <li>Player: -11 HP</li>
    <li>Hand: -1 Bash, -2 Defend, +3 Strike</li>
    <li>Draw pile: -4 Strike, -1 Defend</li>
    <li>Discard pile: +1 Bash, +3 Defend, +1 Strike</li>
</ul>
<h4><a href="#">60%</a></h4>
<ul>
    <li>Jaw Worm: next move Bellow (gain 3 Strength and 6 Block)</li>
</ul>
<h4><a href="#">40%</a></h4>
<ul>
    <li>Jaw Worm: next move Thrash (deal 7 damage, gain 5 Block)</li>
</ul>

I mean. It works. But "60%" and "40%" seem like terrible link texts, especially when we get more outcomes on the page with the same probabilities. I want link texts, taken out of context of where they are on the page, to give a decent idea of what they lead to, and to be unique.

Maybe if we expand the headings, swallow the cost of duplicating some text, it would be better.

<h4><a href="#">End turn (60%)</a></h4>
<h4><a href="#">End turn (40%)</a></h4>

Yeah. Better. And actually makes the page more readable to me. Still, the links won't be unique in the cases where they have the same probability.

Could we, uh, number them?

<h4><a href="#">End turn 1 (60%)</a></h4>
<h4><a href="#">End turn 2 (40%)</a></h4>

Looks... kind of weird, but I don't have a better idea for making them unique. Now we have two unexplained numbers right next to each other. It reads confusing to me, the meaning of the percentage looks more ambiguous now.

Would adding more text help us, again?

<h4><a href="#">End turn 1 (60% chance)</a></h4>
<h4><a href="#">End turn 2 (40% chance)</a></h4>

It's all subjective, so I don't know if other people finds this clearer, but this is my favorite so far. I'm happy to proceed with this.

Nice! The headings look better, and we now have links that promise us that we can explore all the ways the game can go. I like the look of this!

We actually have enough HTML sketched up now that we could stop it here and start working on implementing the logic, making this skeleton come alive. I think that's the right thing to do. Sketching up more features at this point would help surface design issues we will run into, but I trust our ability to solve them later better than our ability to prepare for them now.

A lovely thing about these blog posts, these dev logs, is that it forces me to put each and every little thing I do into words. It forces me to justify my decisions. As a result, my development so far has been more deliberative, more steady and well-reasoned, than anything I can remember developing in private. I am very happy with every little step we've made along the way, even if - or maybe because - it's very small pieces of work, all in all.

These posts also crystallize my train of thought in a way where it's easy for me to pick up where I left off. If - sorry, when - I stop working on this project for a while, I have enough context made permanent on these pages that I should be able to pick it up exactly where I left off, even if it has been years.

I wonder if I'll have to put that theory to the test someday. Oh well.

Next time, let's write some JavaScript. Let's make things change.

View this app version | Last commit: "#3: Introducing links"

I want to create a "solver" for Slay the Spire which functions as a highly interactive analytical tool. I am imagining it showing the possible actions you can take in any situation, their possible outcomes and their probabilities, and then letting you select an outcome to view and analyze further. I want a tree of past and future game states to move through. I want a search algorithm for optimal actions that is explainable, auditable, and tunable. I want to be able to query for specific outcomes like "highest possible health remaining" and "highest guaranteed health remaining" and "least turns taken."

So, what I want is less a "solver," something that spits out the solution for you to follow, makes you a passive user, and more a tool that invites you to be an active participant in the analytical process.

I think that's a neat vision to work towards.

Today I want to sketch some more HTML and get some essential features in place. Particularly:

• Every possible action you can take in a game state
• Every possible outcome from a given action

Slay the Spire is a card game with a lot of inherent randomness in card draw order, as well as many random card effects, and some randomness in enemy moves. At any time in the game, you likely have many different cards you can play, and you can always end the turn. The game can branch in many different directions depending on the actions you choose, and branches yet again in the random outcomes actions have.

These branching paths are what we are here to explore. We need to display them.

For the opening scenario we've sketched, there are four possible actions we can take:

• Play Bash on Jaw Worm
• Play Strike on Jaw Worm
• Play Defend
• End the turn

One action at a time. Bash is an attack card that costs 2 energy to play, and reads: "Deal 8 damage. Apply 2 Vulnerable." The result of playing it is:

• We go from 3 energy (our starting amount) to 1 energy.
• Bash moves from the hand to the discard pile.
• Jaw Worm goes from 42 to 34 HP.
• Jaw Worm gets 2 turns of the Vulnerable debuff, which causes it to take 50% more damage from attacks.

I realize now I forgot to add energy to the page last time. Better fix that first.

<h2>Player: Ironclad</h2>
<p>HP: 80/80</p>
<p>Energy: 3/3</p>

Now. How do we present the action of playing Bash? I suspect this will be first hard and nuanced problem to solve. Let's be naive and continue to use headings for our first draft (and if we're lucky, the naive solution will be good enough):

<h2>Actions</h2>
<h3>Play Bash on Jaw Worm</h3>

Now the outcome, which is guaranteed:

<h3>Play Bash on Jaw Worm</h3>
<ul>
    <li>Energy: -2</li>
    <li>Hand: -1 Bash</li>
    <li>Discard pile: +1 Bash</li>
    <li>Jaw Worm: -8 HP, +2 Vulnerable</li>
</ul>

I am terribly, terribly unsure about how to present the outcomes of actions.

We could present them as the complete resulting game state, but that would take a lot of space and make it difficult to see what has changed. So presenting the change seems better.

We could present the change in a number of different ways. We could do "Energy: -2" or "-2 Energy" or "3 → 1 Energy" or "Energy: 1/3." We could do "Hand: -1 Bash" or "Hand: -Bash" or "Hand: Defend, Defend, Defend, Strike" or "Bash: Hand → Discard." Enemy damage has yet more possibilities: "Jaw Worm: -8 HP" or Jaw Worm: 34/42 HP" or "Jaw Worm: -8 (34) HP" or Jaw Worm: 42 → 34 HP." And so on and so on.

How in the world are we to pick a single way to present this? Well, I have some preferences:

• It should be concise. Some actions will have many possible outcomes and many effects per outcome, so we may have to fit dozens of outcomes and hundreds of effects on the page. This data should be as digestible and comparable as possible.
• I was going to write a speculative preference about sets of changes being easy to combine and "do addition on," as I'm curious about modeling the data that way, but it sounded less and less important as I tried to write it. Discarding this idea for now.

Let's aim for concise, digestible, and comparable, then. And for that, the first idea I sketched seems... fine. Good enough to sketch some more.

Two more card actions. Playing Strike costs 1 energy and deals 6 damage.

<h3>Play Strike on Jaw Worm</h3>
<ul>
    <li>Energy: -1</li>
    <li>Hand: -1 Strike</li>
    <li>Discard pile: +1 Strike</li>
    <li>Jaw Worm: -6 HP</li>
</ul>

Defend is a skill card that costs 1 energy and reads "Gain 5 Block." Block prevents the next X damage you would take this turn.

<h3>Play Defend</h3>
<ul>
    <li>Energy: -1</li>
    <li>Armor: +5</li>
    <li>Hand: -1 Defend</li>
    <li>Discard pile: +1 Defend</li>
</ul>

Hmm. What if we combined Energy and Armor to one line affecting the player?

<h3>Play Defend</h3>
<ul>
    <li>Player: -1 Energy, +5 Armor</li>
    <li>Hand: -1 Defend</li>
    <li>Discard pile: +1 Defend</li>
</ul>

I kind of like that, "-1 Energy" reads nicer than "Energy: -1." We could make them separate list items instead of bundling them, but enemies can also gain and lose armor, so I like the clarity of writing "Player" and "Jaw Worm" in front of changes to HP, armor, buffs and debuffs.

Let's change the other two actions to match.

<h3>Play Bash on Jaw Worm</h3>
<ul>
    <li>Player: -2 Energy</li>
    <li>Hand: -1 Bash</li>
    <li>Discard pile: +1 Bash</li>
    <li>Jaw Worm: -8 HP, +2 Vulnerable</li>
</ul>
<h3>Play Strike on Jaw Worm</h3>
<ul>
    <li>Player: -1 Energy</li>
    <li>Hand: -1 Strike</li>
    <li>Discard pile: +1 Strike</li>
    <li>Jaw Worm: -6 HP</li>
</ul>

Looks good!

Okay, now for the big one: "End turn." This causes a few things to happen:

• We discard our hand to the discard pile.
• The enemy makes their move, hitting us for 11 damage.
• We draw five cards from the draw pile.
  • We have precisely five cards in the draw pile, so we know which cards we will draw.
• We refresh our energy, setting it back to 3.
• The enemy picks a new next move.
  • This is random. After using Chomp, the Jaw Worm has:
    • 45% chance of using Bellow (gain 3 Strength and 6 Block)
    • 30% chance of using Thrash (deal 7 damage, gain 5 Block)
    • Normally 25% chance of using Chomp again (deal 11 damage), but it cannot use Chomp twice in a row. The wiki isn't clear on this, but I assume this means that Bellow and Thrash become proportionally more likely, to 60% chance and 40% chance, respectively.

This means that ending the turn has two possible outcomes we need to present! How?

Well, headings seem to have been serving us well, so I see no reason to stop now.

<h3>End turn</h3>
<h4>60%</h4>
<ul>
    <li>Player: -11 HP</li>
    <li>Hand: -1 Bash, -2 Defend, +3 Strike</li>
    <li>Draw pile: -4 Strike, -1 Defend</li>
    <li>Discard pile: +1 Bash, +3 Defend, +1 Strike</li>
    <li>Jaw Worm: next move Bellow (gain 3 Strength and 6 Block)</li>
</ul>
<h4>40%</h4>
<ul>
    <li>Player: -11 HP</li>
    <li>Hand: -1 Bash, -2 Defend, +3 Strike</li>
    <li>Draw pile: -4 Strike, -1 Defend</li>
    <li>Discard pile: +1 Bash, +3 Defend, +1 Strike</li>
    <li>Jaw Worm: next move Thrash (deal 7 damage, gain 5 Block)</li>
</ul>

You know, this kind of works? It could be a lot more overwhelming. (It will become more overwhelming as we add more cards.)

Most details of the two outcomes are identical, guaranteed. What if we move the guaranteed bits to right after "End turn," before the probabilities? Would that be better?

<h3>End turn</h3>
<ul>
    <li>Player: -11 HP</li>
    <li>Hand: -1 Bash, -2 Defend, +3 Strike</li>
    <li>Draw pile: -4 Strike, -1 Defend</li>
    <li>Discard pile: +1 Bash, +3 Defend, +1 Strike</li>
</ul>
<h4>60%</h4>
<ul>
    <li>Jaw Worm: next move Bellow (gain 3 Strength and 6 Block)</li>
</ul>
<h4>40%</h4>
<ul>
    <li>Jaw Worm: next move Thrash (deal 7 damage, gain 5 Block)</li>
</ul>

Cons: We've gone from two blocks of changes to three, and need to mentally combine them. Pros: There is less to read, and we can clearly separate between guaranteed effects and random effects.

I think the pros outweigh the cons here. The pro/con calculus might shake out differently as game states get more complicated, but I'm happy to gently commit to this structure.

I'm less sure about how we present large changes to the hand, draw, and discard piles. I find it kind of messy to read. Not so much that I have other ideas I want to try out right now, but enough that I think we should keep an eye on it for later.

The "60%" and "40%" subheadings also look a bit too similar to the action headings with our raw, default HTML style. We will probably want to nest them more visibly under their parent heading very soon.

Our little HTML sketch is getting quite fleshed out now. A little less straightforward, a little less certain, and a little more deliberative than last time, but we're still making forward progress.

I think we need, and I can get away with, one more round of HTML sketching before we can start thinking about implementing functionality. Right now, this is purely a document, with no hint of anywhere to interact. I don't know where the buttons will go! Or links? Are we using links? And what will happen when we click them?

Too many questions. Need more answers.

If you're reading this and these problems are getting your mind going as much as mine, feel free to message me by email or by fedi. I'm not going to chat the project away outside of my blog, but I welcome ideas and suggestions.

Until next time!

View this app version | Last commit: "#2: Actions and consequences"

Right now, all my solver project has to show for itself is a little bit of preamble and a vague idea. I do not have a scaffold to work on. I do not have a plan. I do not even have any clearly defined goals.

Before it's too late, let's get something down on the page, so we can look at it and discuss it. Let's write some HTML, in our first file, index.html.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Page title</title>
</head>
<body>

</body>
</html>

My editor is kind enough to generate an empty HTML snippet for me. Let's replace the title:

<title>Slay the Spire solver</title>

And let's add our first heading to the body:

<h1>Slay the Spire solver</h1>

It's a thoroughly uninspiring name, and I want to find a more unique and identifiable name soon. Let's delay that until we have a bit of functionality, so we can pick a name that captures what our application actually does.

Opening the page, everything seems to display as expected! This is our Hello World. We now have something to start adding to.

At this point, I would consider making our first commit to version control. Alas: I do not have a development machine with me. I am coding this on my phone, using the first Android app I was able to find for web development. I do not have any version control set up, nor any command line available. Until I return home from my vacation, our process and tooling will stay exceedingly simple. So: no commiting anything right now.

Let's proceed to add something interesting. To start analyzing games and available actions and potential outcomes, I will at minimum need to display a game state. Let's start with that.

First, some player data:

<h2>Player: Ironclad</h2>
<p>Health: 80/80</p>

Already, I am forced to decide on how to present the data. I could structure this as a table, or as a list, or lists of lists, or sections, or something else entirely.

I've decided on using headings to separate the game state data into labeled sections for a few reasons:

• Headings are important for screen reader navigation.
• Heading levels let me organize the data into a hierarchy of content.
• Headings do not require any "nesting" of markup elements, compared to tables, lists, and lists of lists.

For simple data like player health, I've opted to keep it to a dead simple paragraph tag. In my first sketches of this (mea culpa, I did try some of this out without you, before I had the space to write), I tried making it a table, or an unordered list. In the end, it all seemed like too much structure. A single-line paragraph for player health will suffice for now.

Now what other game state exists? There's the cards in hand, cards in draw pile, and cards in discard pile. Let's write up some example lists, for a realistic first turn:

<h3>Hand</h3>
<ul>
    <li>Bash</li>
    <li>Defend</li>
    <li>Defend</li>
    <li>Defend</li>
    <li>Strike</li>
</ul>
<h3>Draw pile</h3>
<ul>
    <li>Defend</li>
    <li>Strike</li>
    <li>Strike</li>
    <li>Strike</li>
    <li>Strike</li>
</ul>
<h3>Discard pile</h3>
<p>Empty</p>

Your hand can contain up to 10 cards, and your draw and discard piles can contain any number of cards, so these make sense as lists. Implicitly, I am structuring them as unordered sets, as order in hand does not matter and order in draw pile is typically unknown. Let's sort them alphabetically for consistency.

Though, that draw pile is taking up a lot of screen space for a relatively unimportant piece of information. What if we made it collapsible, in a <details> element?

<details>
    <summary>Draw pile</summary>
    <ul>
        <li>Defend</li>
        <li>Strike</li>
        <li>Strike</li>
        <li>Strike</li>
        <li>Strike</li>
    </ul>
</details>

Hmm, too little information when collapsed. Maybe if we add the card count to the summary...

<summary>Draw pile (5)</summary>

This sits well with me. It also neatly mirrors the game UI, which only shows you the number of cards in draw pile by default.

Let's turn the hand and discard pile into <details> elements, too.

<details>
    <summary>Hand (5)</summary>
    <ul>
        <li>Bash</li>
        <li>Defend</li>
        <li>Defend</li>
        <li>Defend</li>
        <li>Strike</li>
    </ul>
</details>
<!-- Draw pile -->
<details>
    <summary>Discard pile (0)</summary>
</details>

Ah, but the hand should be open by default, because cards in hand are immediately relevant.

<details open>

That looks alright. In the future, I think I will want to add a little extra information to the cards, like energy cost, card type, effect, and such. For the "sketching" I'm doing now, I think it's better to skip it and add more essential things.

One more piece of player data: relics, which grant passive effects.The Ironclad's starting relic is Burning Blood, which heals 6 health at the end of every combat.

Ah, correction: It heals 6 HP at the start of every combat, according to the Slay the Spire wiki. I forgot the game uses the term "HP," not "health." Let's fix our display:

<p>HP: 80/80</p>

And now, another <details> list for relics:

<details>
    <summary>Relics (1)</summary>
    <ul>
        <li>Burning Blood (At the end of combat, heal 6 HP)</li>
    </ul>
</details>

You know, I think the description would work well in italics. And though the <i> tag doesn't mean "italic" anymore, based on MDN's usage notes, I think I can swing it as semantically valid.

<li>Burning Blood <i>(At the end of combat, heal 6 HP)</i></li>

I think that's every bit of player information. It's enough for our UI to start taking shape, at least.

Let's add the second half of the game state: the enemy. I want to start with the Jaw Worm, one of the three enemies you can encounter on the first floor.

<h2>Enemies</h2>
<h3>Jaw Worm</h3>
<p>HP: 42/42</p>

We nest the "Jaw Worm" heading under an "Enemies" heading, since encounters can have more than one enemy.

Other than HP, we also know our enemies' intention, what move they will make when we end the turn. The Jaw Worm has three possible moves, but always starts with Chomp.

<p>Next move: Chomp <i>(Deal 11 damage)</i></p>

Huh, I don't really like the italics here. Somehow I like it for relics, but not for enemy moves. Maybe because relics are more memorable and their descriptions are longer.

<p>Next move: Chomp (Deal 11 damage)</p>

That's better.

It's growing late, so we wrap the post here.

So far, I am happy with how smooth the process is. We've gone from "nothing" to "something," which is major progress. I'm much more comfortable with the default, unstyled HTML look than I expected. At some point I will want to improve the presentation for clarity and usability, but the raw look will serve us well until the document structure stabilizes.

I'm also very happy I started drafting the HTML first instead of diving into JavaScript and writing logic. My C# version of the solver started with game logic, and the UI never graduated beyond printing game state to the console. It's very satisfying to me that this version is already more visually interesting than my last attempt.

More than that, I realize that starting with the HTML is extremely helpful for clarifying what I am making. It takes all my fuzzy, loose thoughts, and puts them in concrete terms on the page. It helps me see them better. It frees up my mind to think of next steps. It lets me start planning what features I want, see where they will fit in, start seeing friction and flaws where I need to adapt the design.

I feel very prepared to expand on this tomorrow. Probably writing more HTML, still: actions and outcomes. Until then!

View this app version | Last commit: "#1: HTML first"

For the uninitiated: Slay the Spire is a video game where you fight your way through floor after floor of enemies until you face the Heart of the Spire. To get there, you have to defeat the enemies in turn-based battles by playing cards from your deck, of which there are dozens and dozens of different kinds - ones that hurt the enemy, ones that protect you, ones that power you up or weaken the enemy, and so on. At any point in a run, if you run out of health, you die and the run is over.

If you want to understand the game better and have a bit more context for what I'll be working with here, I suggest watching somebody playing a full run of the game - my favorite Slay the Spire streamers are Baalorlord and Jorbs. Here's a video of Baalorlord playing a run with the Ironclad that I quite like.

If you would rather not spend time on that, but still want to see how I write a solver for the game, that’s fine too! I will have to implement each and every one of the mechanics of the game as I go, so it should be possible to follow along without too much prior knowledge.

Back in 2022, I started a side project, just for fun, to write a program that would find the best possible moves to take in Slay the Spire. It was a C# project, I spent… a couple of months on it, I think? I got it to the point where it could simulate one of the first combat encounters of the game and pick reasonably good moves. It was a lot of fun to make.

Now, in 2024, I want to do it again, but different. I'm really interested in web development at this time, and I'm planning to write it as a single web page, using plain HTML, CSS, and lots of JavaScript.

Why? I want to place more emphasis on the UI and visualization, which is easier for me out-of-the-box with a web app. It is easier for people following along to check out the code themselves, play around with it, and maybe hack it a bit themselves - you only need your web browser. It's good practice for my web development job. And I get to publish it on my site.

There are several good reasons for me not to build it as a web app, the main one for me being that JavaScript gives poor performance for the kind of search algorithms I’ll be implementing, and performance is quickly going to become a bottleneck for the problems I'm looking to solve. I'm choosing to accept this - combinatorial explosion will cause me issues at some point no matter how much power and efficiency I throw at the problem, and I do not mind it coming to bite me slightly sooner. Learning more about JavaScript performance and optimization sounds fun, anyway!

Oh, and maybe the biggest reason for doing it this way: I figured out how to write HTML on my phone, so I can get this project started now, while I'm on holiday, away from my computer. 🙂

I want to thank Ron Jeffries for inspiring me to write this. He’s written some lovely and entertaining series of blog posts of his own coding projects, and is currently writing a Sudoku solver (first post here). It looked fun enough that I was reminded of my old solver and wanted to do something similar myself.

I could get into what my goals with this are, what I am prioritizing, what I am deprioritizing, what to expect - but I'm growing tired of writing preamble. I'd rather my next bit of writing to actually get into it. We can figure all that big-picture stuff out as we go.

Onwards!

The first result I found was the Curved Text Along a Path tutorial by Geoff Graham on CSS Tricks. It demonstrates how to add curved text to a web page using an inline SVG.

It was perfect.

About half an hour of experimenting and browsing the MDN Web Docs later, I was looking at the end result. It's the most beautiful thing I've made in years.

Now, unless you have an above-average interest in HTML, CSS and vector graphics, you may want to tap out of this page now, because the rest of this will be me nerding out over how the sausage is made.

...

Still here?

Good! Let's jump in.

Where we're going, we don't need Photoshop

<header>
    <svg viewBox="0 0 500 500" xmlns="http://www.w3.org/2000/svg">
        <title>Welcome to my website</title>
        <path id="top-curve" d="M 100 100 C 100 90, 250 -40, 400 100" stroke="transparent" fill="transparent"/>
        <path id="bottom-curve" d="M 100 400 C 100 410, 250 540, 400 400" stroke="transparent" fill="transparent"/>
        <text aria-hidden="true" textLength="340">
            <textPath xlink:href="#top-curve">Welcome to</textPath>
        </text>
        <text aria-hidden="true" textLength="340">
            <textPath xlink:href="#bottom-curve" dominant-baseline="hanging">my website</textPath>
        </text>
    </svg>
    <img src="/img/logo-500px.jpg" alt="A seal in a wine glass">
</header>

This is the complete HTML for the front page header image and text. It is made up of two main elements:

• The <img> element, which draws the circular photo in the middle.
• The <svg> element, which draws the text around it.

A side note on screen readers

The word "draw" can be a bit misleading here, because it may lead you to believe the text is purely graphical.

Yes - the SVG text functions pretty much like regular text! You can select it, copy it, and screen readers will even read it!

That last point is a problem. When testing how the SVG reads with the built-in screen reader on Windows 11, it was... bad. It just does not read well. It may be that other screen readers handle SVG text better, but I do not want to rely on it.

To improve on this, I went with the most robust-looking solution I could find: I added a <title> element with equivalent text to the SVG, and hid the text elements from screen readers with aria-hidden="true". This made the reading experience significantly more pleasant.

(If you know of better, more accessible ways to do this, please contact me so I can update this post.)

Styling

To reliably wrap the text around the photo, I needed some reliable styling, and I needed that styling to be responsive across different screen sizes.

I solved this using a CSS grid where:

• The <img> and <svg> elements are always perfectly square.
• They are always the same size.
• They shrink on smaller screens.
• They are placed directly on top of each other.

.home-page header {
    display: grid;
    margin: 40px 0px;
    max-width: 500px; /* Will shrink, but keep height proportional if the screen is narrow */
}

.home-page header * {
    /* Place all child elements in the same, single cell of the grid */
    grid-column: 1;
    grid-row: 1;
    /* Ensure identical height and width */
    height: 100%;
    width: 100%;
}

.home-page header img {
    z-index: 1;
    border-radius: 100%; /* Makes the image circular */
    padding: 10%; /* Clears space for text around the image */
}

.home-page header svg {
    z-index: 2;
}

The image is made square by, well, being a square image. The SVG is made square by the viewBox="0 0 500 500" property, which defines the internal dimensions of the SVG - the draw positions range from (0,0) to (500,500).

And while we're in CSS world - the actual SVG text is also styled using CSS!

.home-page header svg text {
    fill: #89cff0;
    font-family: babycakes; /* Balloon font! https://www.fontspace.com/babycakes-font-f20531 */
    font-size: 36px;
    text-transform: uppercase;
}

Text, paths, and text paths

Let's look at the contents of the <svg> again, and remove <title> and aria-hidden for brevity.

<path id="top-curve" d="M 100 100 C 100 90, 250 -40, 400 100" stroke="transparent" fill="transparent"/>
<path id="bottom-curve" d="M 100 400 C 100 410, 250 540, 400 400" stroke="transparent" fill="transparent"/>
<text textLength="340">
    <textPath xlink:href="#top-curve">Welcome to</textPath>
</text>
<text textLength="340">
    <textPath xlink:href="#bottom-curve" dominant-baseline="hanging">my website</textPath>
</text>

The <text> elements draw text. The textLength attributes say how many pixels long the text should be, and squishes or stretches the text to make it so. I gave both the top and bottom text elements textLength="340" so they would stretch evenly left-to-right.

Inside them are the <textPath> elements, which draw text along a given path. The xlink:href attributes say which path they should follow. The dominant-baseline="hanging" attribute places the bottom text below the path, instead of above it.

Finally, the transparent <path> elements supply the curves, as defined by their d attribute.

Can we talk about the curves? I need to talk to you about the curves.

Bézier, you beautiful man

Okay, so I've been in the rough vicinity of graphics and animation long enough to have heard "Bézier curves" referenced a few dozen times in my life. I never took the time to look up what they were. I assumed they were complicated and slightly magical, only taught in spellbooks sourced from the Graphics Wizards' tower.

To draw my text exactly how I wanted it, I needed Bézier curves. So I had to up look how they worked, and what all of the coordinates in the code samples meant.

It turns out I was bang on the money. They are magical.

I cannot hope to give a servicable tutorial for how they work - try the Bézier curve tutorial and SVG Paths tutorial on MDN for that.

In short, they consist of some number of control points, and move from the first control point to the final control point via the fun math-y thing the animation demonstrates. Two control points makes a linear curve (a line), three makes a quadratic curve, four makes a cubic curve, and so on.

This gave me just enough to go on to make a symmetric pair of cubic curves that gently curve around the image.

<!-- Cubic curve from (100,100), via (100,90) and (250,-40), to (400,100) -->
<path id="top-curve" d="M 100 100 C 100 90, 250 -40, 400 100"/>

Now, uh. In the middle of writing this, while reading the linked SVG Paths tutorial, I realized I could have made this using a simpler quadratic curve instead.

<!-- Quadratic curve from (100,95), via (250,-25), to (400,94) -->
<path id="top-curve" d="M 100 95 Q 250 -25, 400 95"/>

And. I also realized there's a non-Bézier "arc" curve. For drawing arcs. Like around a circle.

<!-- Arc from (100,100), in a 210 px radius with sweep-flag enabled, to (400,100) -->
<path id="top-curve" d="M 100 100 A 210 210 0 0 1 400 100"/>

It turns out arcs are a little bit complicated so for this use case I'm happy keeping it a Bézier curve.

Though... throwing a couple of arcs together is a simple way to draw a full circle path... so maybe...

I've already written up everything I learned so far, so let's close on this.

<path id="curve" d="M 100 100 A 210 210 0 0 1 400 400 A 210 210 0 0 1 100 100" stroke="transparent" fill="transparent"/>
<text aria-hidden="true" textLength="1320">
    <textPath xlink:href="#curve">
        Imperial futures are only ever stolen presents.
    </textPath>
</text>

Boy howdy, I do not enjoy this at all.

There is one critical issue I did not consider in my original post: whether or not the different parts of review were any enjoyable or engaging. As it turns out, by trimming out every "non-essential" concern from my reviews, I have trimmed away every bit of the activity that was somewhat enjoyable and engaging. My slimmed-down review process is fast, efficient, and insufferable.

Evaluating and discussing design choices, suggesting renames and refactorings, and taking the time to find and point out things I like - these were all things that engaged the parts of my brain that I enjoy using. It was inefficient and slow and occasionally tiring, but at the end of a review session, I was satisfied with my work.

Now, code reviews come in two variants: the small and easy ones that I can knock out quickly and get out of my sight, and the large and difficult ones that drain the soul out of me. 1000 line diffs used to be tough, multiple-hour review sessions where at the end I would be happy with my effort. This has been replaced with me stumbling away from the monitor trying to reawaken the parts of my brain that shut down halfway through after refusing to process any more of the code that I was jamming through my eye sockets.

At least there is a fun irony in all of happening because I made my reviews "less demanding."

Now that I've subjected myself to my own suggested experiment, my feelings on pull requests reviews have cooled significantly. I do not want to do any more of these "efficient" reviews than I absolutely have to. Yet despite not enjoying it, I do not want to go back to the way I reviewed code before. Even if it is more bearable, it is still slow, inefficient and tiring.

Honestly, at this point, I just want to be subjected to as little code review possible, both as a reviewer and a author. This is something I am working on!

I'm a big fan of the Ship / Show / Ask model, which makes pull request reviews something authors explicitly opt into. To start pushing the needle away from "ask for review on all changes all the time," I have asked for and received permission to merge low-risk changes without review. And if you haven't tried it before, let me tell you, being able to merge refactoring and test work straight into mainline feels so very freeing. I highly recommend it.

Yes, I didn't spend time improving the design before I went to work. I slotted my change right into the design that was already there. It fit okay! With some slight cruft, duplication, and clunky call chaining, but still! Don't look at me like that - even Kent Beck says "making the change easy" is the hard part, and my job is hard enough!

And yes, yes, I didn't write any tests first. I know it would have made my work easier, and refactoring less error-prone. And it would have helped me out in the design process. But I knew what I needed to do (mostly)! And I could just boot up the app and test it manually - it was familiar and convenient!

What's that? Did I write any tests after, then? Oh, no, I didn't do that either. I'd, uh, already tested all the use cases manually by the time I finished. It felt like a waste of time not to merge the work and move on. Yes, I have no cheap way of catching regressions now, I know, I know. Can we move on?

Because there's so much to move on to. I can't afford to feel like I'm slow. There's so many more things to do! Important things! Features! Stories! Bugs! Pull requests! The board is so long and the days are so short and I need to do my part.

...

I just... I know it's better to move slowly and deliberately. I know it's a matter of practice. And I know it relieves stress in the end.

But there's just so much code, so many loose threads, and so much work to do. I can only bear so much of it in my head.

Can you fault me for going along with the flow?

The "technical debt" metaphor is used to explain that we accrue design flaws as we work. These design flaws make it harder to change the system - the more flaws we have, the more we "pay interest" in increased time and effort to make new changes. To make the system easier to change again, we need to "pay down the debt" by fixing the design flaws. If we do not keep our "technical debt" in check, we risk accumulating so many design flaws that it is no longer economic to develop the system any further - we hit "technical bankruptcy."

While this is a useful model, I've come to find it insufficient. It frames "cost of change" as something developers harm by introducing design flaws, and repair by removing design flaws. It is centered on the negative case.

The lessons I have learned about managing cost of change from the Extreme Programming community clashes with this framing, because the "technical debt" metaphor does not support the possibility that the cost of change can go down as you add changes to your system.

Eric Evans touches on this phenomenon through the lens of "supple design":

To have a project accelerate as development proceeds - rather than get weighed down by its own legacy - demands a design that is a pleasure to work with, inviting to change. A supple design.

— Eric Evans, Domain-Driven Design, Chapter Ten: "Supple Design"

Eric compares the system design to a leather jacket that is initially stiff, but over months of use becomes comfortable and flexible in the joints. Similarly, when you keep making changes to the design as you work with the system, the parts you repeatedly need to change will become flexible and easy to change, while the rest of the design stays simple and firm.

Another way this phenomenon emerges is through the "evolutionary design" strategy. By building your design in small increments, keeping it as simple as you can, and reflecting and improving on the design with each and every change, you can manage to reduce the cost of change as you expand your system.

When James Shore describes this design strategy in The Art of Agile Development, he gives the example of a JavaScript project he did for one of his screencasts. As he added more and more features related to networking, each feature took less and less time to implement - from 12 hours, to 6 hours, to 3 hours, to under an hour - despite the later features being no less intricate than the earlier ones!

By improving the design with each and every change, the design does not merely stay out of our way. The design actively supports and enables new changes. By keeping the design clean while extending it with more functionality, we can make the system do more and more things with less effort. The codebase becomes a precious asset that accelerates our development, speeding us up instead of slowing us down.

These ways of reducing the cost of change are ill described as "paying down technical debt." Instead, it is more accurate to say we are building technical wealth.

I cope with it.

I muster the energy I have for the day. I devise elaborate techniques to focus myself. I work pomodoros. I meditate. I put on white noise. I journal. I break the work down into little digestible steps.

And so I manage being alone.

Yet sometimes, all the efforts in the world are not enough. Sometimes, I require that precious fruit: Another human's attention.

I carefully leave the confines of my desk, and I slink around the office to see what I can scavenge. Could there be a quick little question somewhere? A second opinion? A clarification? Oh, lucky day, a full discussion!

On this morsel, I return to my seat-burrow and savor my prize. My back straightens. My mind clears. I have been sated enough to function, for now, until I next need to go foraging.

How I long for the revitalizing presence of another human's company.

Some days these little morsels are not enough. Some days, I am starved.

My eyes glaze over the monitor. My arms are heavy. My body cannot sustain itself on table scraps of human interaction. It howls for collaboration.

When I get up from my seat, and look around, I see other humans. Alone at their computer. In peace and quiet. Each with their own well-defined problem in front of them, with their headphones on, with no need to talk to another human.

The air in the office is still. And I would do well not to disturb it.

I sit back down in my seat. I look at the time.

It is winter, yet.

• This parameter must be a string.
• This return value cannot be null.
• This object must have a username property.

Constraints like these are typically common and easy to express in statically typed languages.

Sometimes (actually a lot of times) I am working with data that should follow stricter, more complicated constraints.

• This user-submitted application cannot have the approvedTime value set.
• This username must be non-empty and cannot have special characters.
• This from value must be before the to value.

These constraints can be more tricky to express in a type definition, and I rarely see it attempted. Instead, I see functions either assume the data is valid, or run validation checks on the data that throw an error if it breaks a rule.

Following the advice of "parse, don't validate" (see the wonderful post by Alexis King), I would rather that the type itself is able to enforce its own constraints. This guarantees and preserves the validity of the data as you pass it on to other functions, and reduces the risk of insufficient and redundant validation checks around your codebase.

With a few tricks, most constraints you can imagine can be enforced with a type definition. In this case, I'll be showing how to use classes to guarantee constraints on TypeScript data that simple type and interface declarations are unable to. (This technique also works in any statically typed language that supports classes.)

The technique

1. Define a class containing the values you want to wrap.
2. In the constructor, check for any constraints you are interested in.
3. Throw an error if any of the constructor checks fail.

Key to this technique being widely applicable is that you are allowed to write class wrappers for single values. You incur some overhead for having to instantiate each value as a class, and having to access the instance's value to use it, but in return you can enforce any constraint you can imagine in its constructor. Make this tradeoff at your own discretion.

To illustrate the technique, I've spun up a few examples showing what you can do with it.

A palindrome type

class Palindrome {
    readonly value: string;

    constructor (value: string) {
        const reversedValue = value.split('').reverse().join('');
        if (value !== reversedValue) {
            throw new Error(`"${value}" is not a palindrome`);
        }

        this.value = value;
    }
}

To ensure the string is a palindrome, we reverse it and check if the reversed string is equal to the original string. If not, we throw an error. Then we save the string to the value field.

In practice, usage looks like this:

const palindrome = new Palindrome('())(');
console.log(palindrome); // Output: Palindrome { value: '())(' }
console.log(palindrome.value); // Output: '())('

const invalidPalindrome = new Palindrome('(())');
// Error: "(())" is not a palindrome

The Palindrome class guarantees that every instance of Palindrome contains a string that has passed the constructor validation. If you have any functions that must have a palindrome, the Palindrome type is an effective way to enforce it.

If you would rather not throw an error, but check if the string is a palindrome and handle the invalid case another way, you can create a parse method that wraps the palindrome creation in a try block, and return undefined if it fails:

class Palindrome {
    // ...

    static parse (value: string): Palindrome | undefined {
        try {
            return new Palindrome(value);
        } catch (error) {
            return error;
        }
    }
}

console.log(Palindrome.parse('())(')); // Output: Palindrome { value: '())(' }
console.log(Palindrome.parse('(())')); // Output: undefined

A sorted array

A constructor does not have to throw errors to ensure a constraint. It can also do the work to transform data to a desired form, then pin it in place.

For instance, you can create a SortedArray class that sorts your array for you:

class SortedArray<T> {
    // Mark as ReadonlyArray to ensure contents stay sorted
    readonly contents: ReadonlyArray<T>;

    constructor (contents: T[]) {
        // Copy the array so we do not reorder the original array,
        // and prevent changes to the original array from affecting our sorted array
        const copy = [...contents];
        copy.sort();
        this.contents = copy;
    }
}

const sortedArray = new SortedArray([0, 5, 3, 4, 4, 2]);
console.log(sortedArray.contents); // Output: [ 0, 2, 3, 4, 4, 5 ]

This may be useful if you are working with algorithms that expect a sorted array, like search.

A range with an estimate

Classes can, of course, also enforce constraints for multiple values. While I was experimenting with a game-playing traditional AI, my search algorithm used an EstimateRange data type to describe the minimum, estimate, and maximum value of a given game state. To make sense, the minimum cannot be greater than the maximum, and the estimate must be between them.

Here is how this can be enforced in TypeScript:

class EstimateRange {
    readonly minimum: number;
    readonly estimate: number;
    readonly maximum: number;

    constructor (minimum: number, estimate: number, maximum: number) {
        if (minimum > maximum) {
            throw new Error(`Minimum (${minimum}) is greater than maximum (${maximum})`);
        } else if (estimate > maximum) {
            throw new Error(`Estimate (${estimate}) is greater than maximum (${maximum})`);
        } else if (estimate < minimum) {
            throw new Error(`Estimate (${estimate}) is less than minimum (${minimum})`);
        }

        this.minimum = minimum;
        this.estimate = estimate;
        this.maximum = maximum;
    }
}

console.log(new EstimateRange(0, 7, 10));
// Output: EstimateRange { minimum: 0, estimate: 7, maximum: 10 }

console.log(new EstimateRange(10, 7, 0));
// Error: Minimum (10) is greater than maximum (0)

The point I am trying to make with the variety of examples is that there is a lot you can do with classes. The constraints you can enforce are mostly limited by your imagination.

A warning

This trick comes with a caveat: If possible, you are better off enforcing constraints with simpler alternatives. I prefer using more concise type system features when I can. For TypeScript, you can browse the Everyday Types, Object Types and Creating Types from Types pages of the TypeScript handbook for inspiration.

When simpler alternatives for type checks are insufficient, class constructor validation is a powerful alternative to fall back on.

After venting about this on Mastodon, another user asked me what I thought about static types. They were mostly experienced with dynamically typed languages, and prefer the flexibility they offer.

It turns out this question was all I needed to focus and get my writing back on track - you may take this blog post as my longform answer.

In short: I think static types are a useful tool to prevent us from making very common mistakes. Like, really common. Like "half of the bugs I investigate in JavaScript applications are caused by this" common.

Here's a few examples to illustrate the types of mistakes I'm talking about, and how adding static types with TypeScript helps prevent them.

Mistake #1: Accessing undefined property names

Say we are working with an object containing user profile data, and we want to send an email to that user. To do this, we access the user's email address via user.emailAddress and pass it to sendEmail.

function sendEmailToUser (user) {
    sendEmail(user.emailAddress);
}

But what if we are mistaken? What if the user object's property is actually named emailaddress, or address, or username, or - gasp - it does not actually have a property for email address at all? Well, then this code will instead attempt to send an email to undefined. That's no good.

To check for this potential issue, let us say we found the UserProfile type that describes the user data we expect, and specify that user is of type UserProfile.

interface UserProfile {
    // ...
    contactInfo: {
        // ...
        emailAddress: string
    }
}

function sendEmailToUser (user: UserProfile) {
    sendEmail(user.emailAddress); // Causes a build error!
}

Oops! It turns out the user.emailAddress property does not exist. Now, because we are trying to access a property that does not exist on UserProfile, the TypeScript compiler produces an error.

The UserProfile type instead tells us that a user.contactInfo.emailAddress property exists. This is likely what we actually wanted to use, and replacing user.emailAddress with this will make the error go away.

Mistake #2: Passing invalid data

Say we are working with a map, and want to place an icon at the spot where the user's mouse pointer is:

function getMousePosition () {
    // ...
}

function setIconPosition (position) {
    // ...
}

function placeIconAtMousePosition () {
    const mousePosition = getMousePosition();
    setIconPosition(mousePosition);
}

What can go wrong here? Well, we do not know the structure of the data getMousePosition returns, nor what setIconPosition accepts. Even if we already know we are working with longitude and latitude positions in the same coordinate system, the position could be represented as a { lon, lat } object, or an { x, y } object, or a [lon, lat] array (or even a [lat, lon] array!).

Without type annotations, this code looks perfectly valid, even if the data structures may be incompatible. Now, if we add the correct types to the functions using TypeScript, the incompatibility comes to light:

function getMousePosition (): { lon: number, lat: number } {
    // ...
}

function setIconPosition (position: { x: number, y: number }) {
    // ...
}

function placeIconAtMousePosition () {
    const mousePosition = getMousePosition();
    setIconPosition(mousePosition); // Causes a build error!
}

With the function types specified, TypeScript reports that we made a mistake passing mousePosition directly into setIconPosition. Instead, we should convert the { lon, lat } object to an { x, y } object.

function placeIconAtMousePosition () {
    const mousePosition = getMousePosition();
    setIconPosition({
        x: mousePosition.lon,
        y: mousePosition.lat
    });
}

Mistake #3: Not handling undefined values

The third common mistake TypeScript can prevent is the famed "billion dollar mistake": null undefined values!

Let's reuse the map position code example and see what happens when we modify it. Say we change the implementation of getMousePosition so it returns undefined when the mouse is outside the map. TypeScript will not permit this since this does not match the return type of getMousePosition, so we change the return type so it can also be undefined:

function getMousePosition (): { lon: number, lat: number } | undefined {
    // ...
}

function setIconPosition (position) {
    // ...
}

function placeIconAtMousePosition () {
    const mousePosition = getMousePosition();
    setIconPosition({
        x: mousePosition.lon, // Causes a build error!
        y: mousePosition.lat
    });
}

Oh no! This change actually breaks placeIconAtMousePosition, because it was written with the assumption that getMousePosition always returns a valid position. When it instead returns undefined, the code will throw a runtime error when trying to access mousePosition.lon.

If we were working with untyped JavaScript, this mistake may have managed to sneak in. Luckily, TypeScript caught this error for us. It refuses to compile until we have correctly handled the case where mousePosition is undefined. If we add a check for it, the error disappears:

function placeIconAtMousePosition() {
    const mousePosition = getMousePosition();
    if (mousePosition === undefined) return;
    setIconPosition({
        x: mousePosition.lon,
        y: mousePosition.lat
    });
}

I like to set up development environments so it is easy to write correct code and hard to write incorrect code. Static types are only one of several tools I use for this, but they are one of my favorites. They tell us what we can and cannot do with our data, and they are effective for catching very common mistakes. Because of this, I find the overhead of opting into static typing with TypeScript well worth it.

Code reviews are effective for uncovering bugs. We have multiple large studies backing this claim, estimating that the bug-detection rate of code reviews is in the ballpark of 50%. This is better evidence than we have for most software development practices. From the Wikipedia article on code review:

Capers Jones' ongoing analysis of over 12,000 software development projects showed that the latent defect discovery rate of formal inspection is in the 60-65% range. For informal inspection, the figure is less than 50%. The latent defect discovery rate for most forms of testing is about 30%. A code review case study published in the book Best Kept Secrets of Peer Code Review found that lightweight reviews can uncover as many bugs as formal reviews, but were faster and more cost-effective in contradiction to the study done by Capers Jones.

In addition to their primary value in discovering bugs, they can also be used to assess and improve many other aspects of the code. Design, readability, maintainability, code quality, test quality and coverage, consistency with project style guidelines and documentation are all areas where reviewers can find issues and suggest improvements. The act of reviewing and giving feedback can even help transfer knowledge between developers and be a tool for mentoring and learning.

On account of these benefits, code reviews have become wildly popular, and most software projects mandate that all changes must be approved by one or more reviewers. This virtually always means a pull request based workflow, where developers branch out from mainline, make some changes, then open a pull request that requires approval from a reviewer to merge back into mainline. At time of writing, this is the predominant way of working in our industry.

Branching causes problems

In projects using pull requests, the most popular strategy for branching is feature branching, creating a branch for a single feature and opening a pull request when the feature is complete. This is a convenient and intuitive way of organizing changes. However, these feature branches tend to be long-lived (on the order of days or weeks), and long-lived branches cause some serious issues.

In part four of Thierry de Pauw's article series On the Evilness of Feature Branching, he goes into the problems of feature branching. The article is worth reading in full, but to summarize some of its points:

• It delays feedback on how well changes integrate with other team members' work and how it runs in production.
• It causes rework through merge conflicts.
• It discourages refactoring as they have a high risk of causing merge conflicts.
• It introduces batch work and inventory, trapping valuable work in the system and worsening the throughput, quality, stability and lead time of changes.
• It increases risks by batching changes into large sets which are more likely to break, and harder to find the cause of when they do.

Key to these issues is that they are more frequent and more severe the longer the branches live and the larger the changes are. Conversely, shorter-lived branches and smaller changes cause less issues. We can nearly eliminate the branching issues by pushing this all the way to continuous integration, where everyone's work is merged into mainline every day, potentially even multiple times an hour.

Code reviews make this infeasible for most software teams.

Mandatory code reviews encourage long-lived branches

When merging your work requires another developer to review and approve it, merging will happen less frequently, and pull requests will not shrink beyond a certain size. Dragan Stepanović explains this best in his article From Async Code Reviews to Co-Creation Patterns.

In short, code reviews introduce long wait times to the integration process. First, after a pull request is opened, the author waits for a review. Then, if the reviewer discovers any issues they think the author should handle, the reviewer waits for the author to respond to the feedback. This cycle repeats some number of times until the reviewer is satisfied and approves the pull request.

These wait times encourage developers to start new work in the meanwhile (increasing work-in-progress), and to batch their changes into larger pull requests. This, again, makes each review take longer, making it harder for developers to find time to review them, and increasing the odds of multiple rounds of review - increasing wait times even more! This vicious cycle results in pull requests often taking multiple days before they are able to be merged.

If a team still tries to make a push for continuous integration in this environment, they are fighting against the stream. The more frequently team members try to integrate, the more often they have to interrupt each other to review and respond to reviews. Developer attention bounces between multiple tasks, flow efficiency (time spent working to time spent waiting) plummets, and productivity drops. Every team will hit a point where the pain of this is too high and will stop integrating their changes any more frequently - typically stopping well short of continuous integration.

Code reviews are hard to replace

Many developers who recognize these problems assert that this kind of code review is a net negative and should be done away with altogether. Dave Farley, co-author of Continuous Delivery, insists that you are better off not branching at all:

• Don't Branch!
• Don't Branch!
• Don't Branch!

Instead of doing after-the-fact code review, he and others recommend that you support the quality of your software through other practices. The top recommendations are pair programming and mob/ensemble programming, which function as a sort of continuous code review while boosting the flow of work and knowledge sharing within your team. Test-driven development and a "No Bugs", root-cause eliminating attitude help reduce bug rates even further. By employing these practices, you may achieve better results than relying on code reviews. And I want to believe this.

However, in teams that frequently catch serious errors in code review, this is hard to sell. Most developers do not use these alternative practices, and asking people to change the way they work and spend time practicing new skills is a big ask for most teams. Without these changes, slashing code review will in all likelihood lead to more defects being pushed to mainline and escaping to production. Software teams have very reasonable motives for not wanting to do this.

This leaves me conflicted. I cannot in good conscience say that most teams should drop mandatory code reviews and that this will not cause major issues. Yet, I am thoroughly convinced that continuous integration is a better way of working.

Trapped in the middle, I am here to suggest a compromise: Code reviews should be reduced to their bare essentials.

Code reviews hurt more the more they try to do

Here is my line of reasoning:

1. When you look for more things in a code review, it becomes more demanding and time-consuming.
2. When code reviews get harder, developers will put them off, and wait times will grow.
3. When wait times grow, branches will live longer and pull requests will get larger, feeding the cycle and causing integration pain.

Conclusion: The more things you look for in a code review, the more you will experience integration pain. Conversely, if you reduce the number of things you look for in a code review, you will be able to integrate your work more frequently. If review gets easy enough, you may even find continuous integration feasible!

With this in mind, it becomes clear that we have made the review process very hard for ourselves. The most common thing to do is to include every possible thing worth having an opinion on in the scope of review. For instance, take Google's sumary of what a reviewer should look for:

In doing a code review, you should make sure that:

• The code is well-designed.
• The functionality is good for the users of the code.
• Any UI changes are sensible and look good.
• Any parallel programming is done safely.
• The code isn’t more complex than it needs to be.
• The developer isn’t implementing things they might need in the future but don’t know they need now.
• Code has appropriate unit tests.
• Tests are well-designed.
• The developer used clear names for everything.
• Comments are clear and useful, and mostly explain why instead of what.
• Code is appropriately documented (generally in g3doc).
• The code conforms to our style guides.

This is a lot! A lot of things to pay attention to while reviewing, a lot to write feedback on, a lot of comments for the author to respond to. Several concerns like code quality and design (and without an authoritative style guide, code style and formatting) are highly subjective, and have a higher chance of causing disagreements, discussions, and multiple rounds of review - skyrocketing wait times.

Not only does this bucket list of concerns make review harder, but discussions of fuzzier, less critical issues drown out discussion of bugs. Quoting the Wikipedia article again:

Empirical studies provided evidence that up to 75% of code review defects affect software evolvability/maintainability rather than functionality [...] This also means that less than 15% of the issues discussed in code reviews are related to bugs.

Despite our primary motivation for mandating code review being bug reduction, we spend the majority of our attention on other, less critical issues. Combining this diluted focus with its influence to make pull requests larger, it is likely that trying to improve more things with code review actually makes matters worse.

Limit your code reviews to the most important concerns

Since mandatory code reviews cause more issues the more concerns they look for, they should be stripped down to the bare minimum of concerns that must be improved before merge. This will reduce the costs of review while improving its effectiveness for the concerns you do look for. What this bare minimum set is may vary from project to project, and you are free to decide what this is for yourself.

Personally, I am convinced that you should cut any concern from your list that is not externally visible and can be improved later. This includes:

• Formatting and code style
• Code quality and internal design details
• Comments and documentation
• Test coverage and quality

All of these things are (more or less) valuable, and we want to do them well. However, none of them are externally visible, meaning it does not matter to our users if we merge and deploy them to production. Additionally, all of them can be improved later, and frequent low-friction integration makes it easier to make such improvements. Including them in review would harm integration frequency, which makes it harder to improve the quality of our codebase when we discover these issues while working.

If a developer opens pull requests that aren't up to snuff on any of these points, you have a couple of alternatives instead of checking it during review:

1. Talk to the developer about it. Make sure you agree to a common set of standards, and that they have the environment and resources to learn how to fulfill them. This is a longer term solution that will save you frustration in the long run.
2. Fix it yourself. If you see room for improvement beyond your team's common set of standards, do it yourself instead of asking the author to do it. It is more effective and efficient, and it contributes to your team's sense of collective code ownership - you all have the right and responsibility to make improvements when you see them. And, since this change is to an issue that should be ignored by reviewers, it should be quick and easy to approve and merge back into mainline.

Conversely, changes that are externally visible, or cannot be improved later, are more worth reviewing:

• Bugs and security issues. We should ideally never introduce any of these, and we want to minimize the chance of any of them escaping to production.
• Design decisions that are hard to undo. This includes both external API designs (which are very hard to change once they are public), user interface designs, and any changes to functionality. The cost of getting these wrong is high, so it is worth spending extra effort getting them right.

By limiting your review scope to these core concerns, you minimize the cost of mandating code reviews, while maintaining quality control on the issues you care the most about.

(Limiting and focusing the objective of code review like this also makes it easier to see when code reviews become obsolete - when bug rates drop to acceptable levels pre-review, and when you discuss and refine your irreversible design decisions outside of review. It is very easy to imagine high-performing teams working like this.)

This is a suggested experiment

While this strategy of cutting the scope of review makes a lot of sense to me, I cannot predict how it will play out for you, in your team, in your circumstances. I do not know to what degree it will make reviews easier and reduce integration pain, and I do not know what unexpected side effects it will have.

What I do believe is that this experiment is low risk, it is not very disruptive, and the potential rewards are great enough that you should try it out. Talk it out with your team, find a scope of review to try, trial it for a week or two, then reflect on how it went. If you do not like the results, you can always go back to your old way of working afterwards.

If you try this, or have already tried it, please message me to share your experience! Contact me on Mastodon at @cvennevik@hachyderm.io (so I can share it further, if you like!), or email me at cvennevik@gmail.com.

Edit, April 14th 2023: I wrote a post describing my experience following this idea.