Temple of the Ruby Sands

A year ago I published a Dungeons & Dragons adventure titled The Stonecutter Samurai which was written to share with my friends and co-workers at Automattic. This year I wrote another adventure, Temple of the Ruby Sands!  As it has now been played a total of seven times and I’ve cleaned up the stats and wording, I’d like to share it with you.

The game is a one-shot adventure for a group of 2nd-level characters and runs in about 3-4 hours (I’m getting better at making them short!). It was designed to be fun for brand new players and experienced die rollers alike. It should even have enough info be run by new DMs (although you may want to get to know the D&D 5e rules a bit first)!

Here is the teaser text:

An ancient temple, buried deep in the desert, has recently been excavated by an eccentric Dwarven archeologist. Unfortunately, the excavation site is surrounded by blood-red sand that many locals claim to be cursed, and the archaeologist’s last team was killed when they discovered a series of deadly traps within. Now he desperately wants to hire a new team to return and claim the temple’s treasure, but is there something more to this ancient ruin than meets the eye?

If you feel like braving the Temple of the Ruby Sands, you can download the adventure here.

(Awesome formatting courtesy of The Homebrewery.)

Higher Order Components and Pie Recipes

Higher Order Components (“HOCs”) are the latest hotness to come out of the JavaScript idea world and land in our apps. React apps, anyway.

I really want to write: Higher Order Components are just wrappers, but that would be simplifying the concept too much. Wouldn’t it? Maybe.

Anyway, they’re wrappers. Keep your actual Component simple as pie – it takes ingredients as props and turns them into rendered flaky crust – and have the wrapper handle getting the data from wherever, massaging it, and jamming it in.

This makes the underlying Component simpler to understand, debug, and ultimately reuse elsewhere if needed. Also testing! It’s way easier to test when the data piece is separate.

After thinking about it for a while you may realize that this concept is not new. Keep a pie-making machine abstract and separate from the ingredient machine? Where have we seen this before? Functions! (Ok, other places too.) And lo, this seems to be where React is heading (has already arrived?): Components as functions.

A Component, ideally, should take its props, nothing else (except maybe more Components) and turn those props into output. The output should be the same no matter what as long as the props are the same. It can use libraries to process the data it already has, but not get new data. I mean, that was an idea that React was built upon. But hey, I’d say that’s also the definition of a good function.

So if we think about our Components as functions, then we can apply function strategies to them. Mine basically boil down to: can this be done in fewer lines by extracting logic into a sub-function? Repeat as necessary until my functions are thin little beautiful pancakes. Maybe you have different strategies. Try them on Components!

Usually I see HOCs being talked about in reference to Redux and the global state tree, but my favorite thing is: who cares where the data comes from? Nest those Components and let them remain simple. The HOC could pull data from many sources, even just from a JSON file.

My new rule of thumb is: whenever my Component starts getting too many props (that are not directly related to its concept), when I am pulling data into my Component from a library, or when I find myself caching data in a Component’s state, there’s a strong chance I could use an HOC to smooth things out.

Give it a try! You may be surprised at how fun it can be.

Power and Love

Here’s a quote by Martin Luther King Jr. that I learned today and I really feel compelled to share:

Power without love is reckless and abusive, and love without power is sentimental and anemic. Power at its best is love implementing the demands of justice, and justice at its best is power correcting everything that stands against love.

Test spies in PHP

I think that I wrote my first unit tests in Ruby with RSpec, back in the day. But I learned most of my testing knowledge from working with mocha and chai in JavaScript. One of the things that I learned from these tools is that being able to express your test logic in clear, nearly-natural language brings a real comfort to the often complicated life of the test-writer.

For example, here’s a line straight from the chai home page:

expect(tea).to.have.property('flavors').with.length(3);

It’s so lovely.

When writing tests to follow the flow of code from one module to the next, it’s often useful to have Test Spies around to “spy” on the code and tell you what’s happening when. To borrow the definition from my favorite test spy library, sinon:

A test spy is a function that records arguments, return value, the value of this and exception thrown (if any) for all its calls. A test spy can be an anonymous function or it can wrap an existing function.

When brought together with sinon-chai, this allows for very expressive syntax:

expect(mySpy).to.have.been.calledWith("foo");

Because I work a lot with WordPress, I also write a lot of unit tests in PHP. There, the defacto standard is PHPUnit, which has… less natural language. That’s fine, though, its assertions are usually perfectly readable. What it seems to be lacking, for me anyway, is Spies.

Certainly there are some great ways to use PHPUnit’s built-in mocking tools, like this (hidden) behavior, but Spies are hardly a first-class citizen. And besides, even writing this feels confusing to me:

$target = $this->getMock('TargetClass');
$target->expects($spy = $this->any())->method('doSomething');

$target->doSomething("foo");
$target->doSomething("bar");

$invocations = $spy->getInvocations();

$this->assertEquals(2, count($invocations));

I would much rather write:

$target = mock_object_for('TargetClass');
$spy = $target->spy_on_method('doSomething');

$target->doSomething("foo");
$target->doSomething("bar");

expect_spy($spy)->to_have_been_called->twice();

So I ended up writing a Test Spy library for PHP. I call it Spies. My intent was to have an easy and readable way to create Test Spies, Stubs, and Mocks, and also a clear way to write expectations for them.

Creating a Spy is as simple as calling \Spies\make_spy(); (although there’s many other ways to create them). You can then call the spy and ask it questions, like this:

$spy = \Spies\make_spy();
$spy( 'hello', 'world' );

$spy->was_called(); // Returns true
$spy->was_called_times( 1 ); // Returns true
$spy->was_called_times( 2 ); // Returns false
$spy->get_times_called(); // Returns 1
$spy->was_called_with( 'hello', 'world' ); // Returns true
$spy->was_called_with( 'goodbye', 'world' ); // Returns false
$spy->get_call( 0 )->get_args(); // Returns ['hello', 'world']

Here’s a more complete example of using Spies to mock an object and test its behavior:

You can install Spies using Composer by typing composer require sirbrillig/spies in your project.

I owe quite a lot to the great library WP_Mock by 10up. Many of the concepts in Spies were inspired directly by the way that WP_Mock works, like creating global functions. WP_Mock serves a slightly different purpose, though. It’s a layer on top of Mockery, which in turn is a layer on top of PHP’s own testing tools. Also, it mocks a few things by default, like filters and actions.

Spies is intended to be more generally useful, and also to make the distinction between mocking and setting expectations more clear by breaking away from PHP’s built-in mocking concepts.

I welcome comments and suggestions at the Github page! As always, I hope it ends up being useful to other people.

An iframe without a url

Sometimes you need to display html inside an iframe, but it’s not at a URL. Perhaps you got the markup from an API endpoint or generated it yourself. Maybe the markup is from a different domain and you need to be able to manipulate its DOM without cross-origin errors. For all these reasons, I created MarkupFrame.

A React component to display raw html markup inside an iframe

In several projects I’ve worked on recently I’ve wanted to treat the contents of an iframe as data, fetching it from an API, manipulating it directly using cheerio, and directly reaching into the iframe’s DOM to adjust the elements inside without hitting cross-domain errors.

Normally iframes are set up in such a way that these things are difficult, but there’s a trick:

iframe.contentWindow.document.open();
iframe.contentWindow.document.write( content );
iframe.contentWindow.document.close();

Those three lines allow us to inject html markup directly into the iframe, where the browser will render it: CSS, scripts, and all.

MarkupFrame takes those three lines of magic and wraps them in a React component to use in your application. You can install it using npm:

npm install markup-frame

Then just use the markup prop like this (JSX syntax):

<MarkupFrame markup={ '<h1>hello world</h1>' } />

There’s also a prop called onLoad which is a function that will be called when the markup is finished loading. The callback will be passed a reference to the document object of the iframe, which lets you directly manipulate the DOM (I know: isn’t that what React is supposed to prevent? Yes, but inside the iframe it’s a whole other world.)

...
render: function() {
  var onLoad = function( previewDocument ) {
    previewDocument.querySelector( 'h1' ).innerHTML = 'hello markup-frame';
  };
  return <MarkupFrame markup={ '<h1>hello world</h1>' } onLoad={ onLoad } />;
}
...

This has certainly been helpful to me. I hope it’s helpful to you too! The GitHub repo is here if you want to report any issues or contribute!

Caveat Lector:

Some JavaScript rendered inside an iframe like this doesn’t work correctly since it often makes assumptions about the page having a URL.

Following (clicking) on a link inside an iframe like this will load the resulting page inside the iframe, but then the iframe contents will probably no longer be accessible via its contentWindow.document object without throwing a cross-domain error. For this reason it’s recommended to disable clicking on links using the onClick prop.

Declarative vs. Imperative Soup

I remember not too long ago (I think this was about the time that React first came out) I was trying to understand what people meant when they said that it was “declarative” vs. “imperative”. Looking up the terms at the time didn’t enlighten me much. Mostly articles seemed to focus on the difference between Object-Oriented or Procedural languages and Functional languages. Since I was looking for an explanation within one (Procedural) programming language, that answer was not helpful.

Since then I’ve become a proponent of many functional programming concepts which, I think, have made my code easier to read and understand. If I had to summarize my progress, I would probably say that I’ve learned to to program more declaratively. So even if my definition is slightly different, here’s what Declarative programming means to me.

If I were to ask a chef to make me some soup, I might ask:

Could you make me some roasted butternut squash soup, please?

The chef would likely have little trouble cutting, peeling, roasting, blending, and spicing that dish. On the other hand, if I asked the same question to a past version of myself when I was in university, I would have had absolutely no idea what to do. Why? Because I’d never roasted a squash before.

On the other hand, what if I prepared a full recipe?

Could you make me some roasted butternut squash soup as described in these 10 steps?

The chef would probably look at the recipe and be able to follow it with just a glance. My teenaged self would have to examine each and every line, but he’d probably also be able to make the soup without burning anything.

The difference is that the first question is Imperative; it implies a whole subset of knowledge about cooking that not everyone will have. The second question is Declarative; it makes far fewer assumptions about the knowledge of the person on the other end and thus is more universal. Even if the chef was the one preparing the dish, it’s more likely that the soup will turn out the way I want if I provide a recipe. Because who knows? Maybe the chef likes to add heavy cream to all their soup, and that’s not something I want to eat!

Writing declarative code involves a lot of dependency injection and “pure” functions; you provide the computer all the data it needs to perform a calculation, rather than assuming it will go find that data on its own. For me, this leads to fewer bugs and easier modifications, not to mention more readable code. If you’ve ever had to trace the path of a variable around ten different files, you know what I mean.

I’m still writing imperative code; I still use classes and objects, but I also use immutable data, dependency injection, and partial application. There’s no wrong way to use a programming language, but there is always room for improvement. I can’t wait to see what I’ll learn next.

JavaScript: Mocking Window

When I code in JavaScript I try to avoid using the window or document objects as much as possible, but sometimes there’s just no getting around them. Bootstrapping data from a server (eg: WordPress’s wp_localize_script), manipulating the DOM directly (eg: jQuery), or listening to viewport resize events all require touching the global window object.

Why is this trouble? Because it makes testing a real challenge. The easiest code to test is a pure function, which generally means a function without side-effects, but it also means a function which gets all its data from its arguments and not from some overarching state. Any global variable, like window, is effectively global state.

Fortunately for us, it’s relatively easy to mock a window object. If you’re bootstrapping data, you can just use a plain object. If you’re doing DOM things, you can use a library like jsdom. But let’s say you have a bunch of modules all accessing window in different places? As soon as we start requiring those modules in our tests, we’ll see failures because window will be null.

My answer, as seems to be the case a lot these days, is dependency injection. That is, directly providing our window object to the code before it runs. It might be awkward to pass window to every function which might want to use it, so instead we can create a module something like the following:

var windowObj = null;

module.exports = {
    setWindow: function( newWindowObj ) {
        windowObj = newWindowObj;
    }

    getWindow: function() {
        if ( ! windowObj && ! window ) {
            throw new Error( 'No window object found.' );
        }
        return windowObj || window;
    }
};

Now in other modules that need a window we write:

var getWindow = require( './helpers/window' ).getWindow;

function getSomethingFromTheDOM() {
    return getWindow().document.querySelector( '.something' );
}

By itself, that will work just as well as using window directly, and when we want to test the code, we can write this in a test helper:

var jsdom = require( 'jsdom' ).jsdom;
var setWindow = require( './helpers/window' ).setWindow;
setWindow( jsdom().defaultView ); 

Now all the calls to getWindow() will use our mock window object instead.