5th page of the posts archive.

For a WordPress (classic) theme using get_template_part generally provides a good level of organization. But for a large, enterprise-level website, I organize my server-side rendered UI elements into what I call "HTML Components". It's somewhat inspired by React.

Components let you split the UI into independent, reusable pieces, and think about each piece in isolation.

Since we prefer OOP for this project, there's an interface for the components:

interface Component
{
    public function render(): string;
}
interface Component
{
    public function render(): string;
}

A component could be as simple as this one, but typically there's more to it:

class Infobox implements Component
{
    public function render() {
        return '<div class="infobox">...</div>';
    }
}
class Infobox implements Component
{
    public function render() {
        return '<div class="infobox">...</div>';
    }
}

There's a template renderer to avoid mixin HTML in the PHP class and achieve a better separation of concerns:

interface TemplateRenderer
{
    public function render(string $templateName, array $data = []): string;
}
interface TemplateRenderer
{
    public function render(string $templateName, array $data = []): string;
}

Besides passing the data to the template files, components can retrieve icons, derive state from props (React jargon), etc., do what's needed.

Here's a stripped-down but "real" component:

class Component {
    use ResourcesDirTemplateFileTrait;
    
    public function __construct(
        readonly private Props $props,
        readonly private TemplateRenderer $templateRenderer,
        readonly private Svg\Loader $svgLoader
    ) {
    }
 
    public function render(): string
    {
        return $this->templateRenderer->render(
            $this->templateFile(),
            [
                TemplateArgs::TITLE => $this->props->title,
                TemplateArgs::CONTENT => $this->props->content,
                TemplateArgs::DEFAULT_IS_OPEN => json_encode(!$this->props->title),
                TemplateArgs::ICON_TOGGLE => $this->props->title
                    ? $this->svgLoader->byName('arrow-caret-down')
                    : '',
            ]
        );
    }
}
class Component {
    use ResourcesDirTemplateFileTrait;
    
    public function __construct(
        readonly private Props $props,
        readonly private TemplateRenderer $templateRenderer,
        readonly private Svg\Loader $svgLoader
    ) {
    }

    public function render(): string
    {
        return $this->templateRenderer->render(
            $this->templateFile(),
            [
                TemplateArgs::TITLE => $this->props->title,
                TemplateArgs::CONTENT => $this->props->content,
                TemplateArgs::DEFAULT_IS_OPEN => json_encode(!$this->props->title),
                TemplateArgs::ICON_TOGGLE => $this->props->title
                    ? $this->svgLoader->byName('arrow-caret-down')
                    : '',
            ]
        );
    }
}

While these components do not contain "too much logic", I strive to provide tests for them.

Testing

When testing these components, I'm interested in two things. First, if the components are rendering the output (HTML) I expect. Second, if the data passed to the template files is what it should be.

Testing the output also tests the data indirectly. There's an overlap between the two types of tests, but they can't be exchanged, and they focus on different aspects.

I made the rule to always write tests "for the HTML", but only test the data directly for more "complex" components.

"Snapshot" testing

PHPUnit had the assertEqualXMLStructure method, which made it easy to compare two DOM structures. There are plans to reintroduce it.

Until then, I'm comparing two "HTML" strings. This has its shortcomings. For example, the order of the attributes has to match; spacing can cause problems, etc.

// This fails
$this->assertEquals(
    '<div class="infobox" id="infobox-alpha"></div>',
    $infobox->render() // <div class="infobox-alpha" class="infobox">...</div>
);
// This fails
$this->assertEquals(
    '<div class="infobox" id="infobox-alpha"></div>',
    $infobox->render() // <div class="infobox-alpha" class="infobox">...</div>
);

To overcome this, I have a custom assertion method that does some normalization before comparing the strings:

class InfoboxHtmlSnapshotTest extends HtmlSnapshotTestCase
{
    public function testDefaultOutput()
    {
        $infobox = new Infobox(...);
 
        $this->assertHtmlEquals(
            file_get_contents(__DIR__ . '/snapshots/default.html'),
            $infobox->render()
        );
    }
}
class InfoboxHtmlSnapshotTest extends HtmlSnapshotTestCase
{
    public function testDefaultOutput()
    {
        $infobox = new Infobox(...);

        $this->assertHtmlEquals(
            file_get_contents(__DIR__ . '/snapshots/default.html'),
            $infobox->render()
        );
    }
}

I'm doing something similar to what Jest calls snapshot testing but the "snapshots", in my case, are created and maintained manually.

Testing the $data with mocking

My initial approach for testing the passed data to the template renderer was mocking it and setting up expectations.

public function testNoIconAndIsOpenWhenNoTitle()
{
    $templateRendererMock = $this->createMock(TemplateRenderer::class);
 
    $templateRendererMock->expects($this->once())
        ->method('render')
        ->with(
            $this->stringContains('index.php'),
            [
                'title' => '',
                'content' => 'In 2009, the International Air Transport Association (IATA) ...',
                'initialIsOpen' => 'true',
                'iconToggle' => '',
            ]
        );
 
    $infobox = new Infobox(
        ...,
        $templateRendererMock,
        ...
    );
 
    $infobox->render();
}
public function testNoIconAndIsOpenWhenNoTitle()
{
    $templateRendererMock = $this->createMock(TemplateRenderer::class);

    $templateRendererMock->expects($this->once())
        ->method('render')
        ->with(
            $this->stringContains('index.php'),
            [
                'title' => '',
                'content' => 'In 2009, the International Air Transport Association (IATA) ...',
                'initialIsOpen' => 'true',
                'iconToggle' => '',
            ]
        );

    $infobox = new Infobox(
        ...,
        $templateRendererMock,
        ...
    );

    $infobox->render();
}

This approach started to be messy when I created components that rendered child components.

In those cases, the render method was called multiple times. Switching and using the withConsecutive turned out to be hard to reason about and follow.

Using a test implementation

The contract of the TemplateRenderer had to be satisfied, so there was no way around returning something else than a string.

But the option to create a test implementation for the template renderer was open. So that's what I did.

$customImplTemplateRenderer = new class implements TemplateRenderer
{
    public function render(string $templateName, array $data = []): string;
    {
        return json_encode($data);
    }
};
$customImplTemplateRenderer = new class implements TemplateRenderer
{
    public function render(string $templateName, array $data = []): string;
    {
        return json_encode($data);
    }
};

This implementation simply returns the data in a JSON encoded string format, which, once decoded, allows for good old array comparison:

$infobox = new Infobox(
    ...,
    $customImplTemplateRenderer,
    ...
);
 
$this->assertEquals(
    [
        'title' => '',
        'content' => 'In 2009, the International Air Transport Association (IATA) ...',
        'initialIsOpen' => 'true',
        'iconToggle' => '',
    ],
    json_decode($infobox->render(), true)
);
$infobox = new Infobox(
    ...,
    $customImplTemplateRenderer,
    ...
);

$this->assertEquals(
    [
        'title' => '',
        'content' => 'In 2009, the International Air Transport Association (IATA) ...',
        'initialIsOpen' => 'true',
        'iconToggle' => '',
    ],
    json_decode($infobox->render(), true)
);

When nesting HTML Components, it's just a matter of comparing a multidimensional array, and there's no need for writing the boilerplate for creating a mock.

Electrosystems (ELS) specializes in importing, developing, and distributing electronic security systems in the B2B sector. They have been selling the most advanced technological products at competitive prices in Greece since 2007.

Background

Since it's a long-standing company, they have a robust, established workflow with an ERP system at its core to manage customers and orders.

ELS has an online shop that is used only for creating preliminary orders without asking for payment. The finalization of orders happens offline.

Since they have various partnership deals, their customers get a customized pricing offer for the products. When customers log in to the shop, they see those prices. (They do now!)

Problem

While the previous team of developers was able to set up WooCommerce and the data importing and synchronization, they failed to implement the pricing logic.

The ERP has the option to expose the customer and product data. It does not offer an endpoint to retrieve a product price based on a customer, only the underlyinushg raw rules data that is used for the different discount policies.

The partial and failed pricing policy implementation created more confusion for the customers than helped them.

With customers complaining about seeing different prices than in their final offers, ELS wasted countless hours in ad-hoc verifications and debugging that seemed to go nowhere.

Mistrust and high response time started to characterize the communication with the original developers.

Solution

...