DEV Community: Jonathan

We’re all full stack now

Jonathan — Wed, 19 Aug 2026 07:17:27 +0000

I've noticed a recent trend toward traditionally more specialised developers (including my own area, front end) working more full stack.

Working full stack doesn't necessarily have to mean writing back end or platform code, but it might mean:

Being aware of, and understanding, systems further up the stack
Knowing enough about the whole stack to understand other engineers and "speak their language"
Being able to debug back end or platform issues or isolate issues to any part of the whole stack

One tricky thing about software development is that work doesn't necessarily come in neat little packages that can be handed off to front end or back end. For example, a task that seems to be targetting user experience might end up involving a config change on the back end. Or a task that seems to be aimed at reducing server utilisation might end up involving a change to a front end API calling pattern.

It's very helpful for an engineer to be able to "jump in" to another part of the stack to make a code change or "jump on" a call with a engineers of a different specialisation.

This is quite a change from the very clearly demarcated front end vs. back end divide that I observed in the 2010s.

What explains it? A few factors from what I can gather:

Tightened budgets. Thanks to the end of ZIRP and other factors, organisations want to do more work with fewer people and thus may demand more flexibility from their engineers.
Increasing complexity and coupling of systems. Application features often require tight front end and back end coupling. For example, quickly filtering and visualising very large data sets stored on the server.
Blurring of the lines. React Server Components (RSC) and associated frameworks such as NextJS involve code executing on both server and client, while HTMX focuses on markup and emphasises use of full-stack/backend templating engines to generate code targetting the browser. Working with these new tools blurs the distinction between the front end and back end skill set.
Security issues that cross boundaries. Hackers don't care about our engineering specialisations! Exploits have increased in recent years and some of them (for example, CVE-2025-55182) touch on the whole stack.
Maturation of the industry. As the current crop of front end engineers (including myself) mature and develop in their abilities, they are both able and expected to handle a broader set of problems.
Increasing efficiency of tools. Spending less time fighting tools frees up engineers to focus on broader problem solving, across the stack.

With quite a few independent factors seeming to be involved, this seems like a pretty robust trend, which is likely to continue.

That said, I don't think the specialisations will disappear. I think there will continue to be distinct roles: front end, back end, platform, data, etc. But I think individuals in these roles will be expected to have knowledge beyond their area and be flexible about contributing in other areas.

Living systems blueprint

Jonathan — Wed, 12 Aug 2026 02:35:00 +0000

Imagine you're a new joiner in a corporate environment.

You are faced with a complex network of systems: databases, servers, platforms, logs, etc. They're all scattered around various wiki pages, chat messages, etc.

You have the challenge of trying to get your head across everything fast enough to be useful to the team.

You need a map of where to find everything.

When you get hit with a new code review, bug report, prod support ticket or just regular task, you need to quickly see a map of the whole ecosystem, locate the specific systems that matter for the problem at hand, and jump into them instantly.

This is not about conceptual or theoretical knowledge. It's about being able to actually navigate and access real, running systems.

Read actual logs
Query actual databases
Push actual code changes

Here is where a "living systems blueprint" might come in handy.

What it is

Borrowed from the service blueprint, famous in the world of UX design, this is a diagram of services.

Pull-quote: A service blueprint is a diagram that visualizes the relationships between different service components — people, props (physical or digital evidence), and processes — that are directly tied to touchpoints in a specific customer journey.

However, for our purposes as software engineers, it focusses on technical systems and services.

And it has an important additional feature: links. Crucially, you want this to be more than a diagram. It should link you to the real systems so you can actually ... you know ... do stuff!

You can create a diagram like this yourself, for your own use. Its sole purpose is to help you navigate your digital work environment. To diagrammatically represent all the important systems you might work with and how they connect to each-other.

Diagram format

Here's an example of such a diagram:

Notice the links. One click (or copy and paste into a tool) can take you directly to the system.

Say, to a CloudWatch log in Prod. Or a Postgres database in UAT. Or an API request in Postman.

Here is a breakdown of the elements of the diagram:

Components	Depicted by a rectangle	Components of the system, such as services, databases, log storage, blob storage, mobile apps, web front-ends and more.
Dependencies	Depicted by a line and arrow	Dependencies between components, so that one "depends upon" another, such as a service depending on a database.
Compositions	Depicted by a line and circle	Compositions of components, such as parent/child or container/contained.

Within each component rectangle, we have:

Icon	Quickly identify the type of the service.	Simple shape, such as a Material Design icon, or one of the standard vendor or cloud provider icons, say for AWS, Azure, Google Cloud, etc.
Title	Title of the service, as referenced in code, docs, etc.	Text in a larger font.
Type	Type of service. E.g. Web Service, Log, Database, Mobile App, etc.	Text in brackets, in a smaller font.
Links	Links to access the entity or related to the entity. For a web application, it might include links to environments. For a database, it might include links to a console or a URI that can be plugged into a database client.	Text with underlined links, in a smaller font.

Within the "Links" row, you might put links to the system itself, including multiple environments (also known as "stages") such as Development, Staging and Production.

Development | Staging | Production

Now imagine someone comes to you with the following request:

Help! Panic! I need to find out why Transfer from customer #098238 are failing in UAT!

You can check your living blueprint, locate the Transfer service, see that it's connected to the Transactions database and follow the link to the Console in UAT to query recent transactions.

How it helps

Of course, you probably won't need a diagram if you're working with only a small number of systems or services on a regular basis. Likely your brain has already memorized the systems and you have browser bookmarks and the like to navigate to them quickly.

But suppose you're working with many services (too many to memorize all their names), with non-trivial integration patterns, which you might need to access unexpectedly at a moment's notice. Then a living systems blueprint might help you out.

A living systems blueprint can serve as a form of Long Term Memory (LTM). Its spatial and connected form enables you to jump through a complex of network of interconnected systems and quickly locate just the resources you need via links, whether they are logs, consoles, dashboards, code files or anything else.

Systems blueprint sketches

Portions of systems blueprints can be split into "sketches".

You might want to do this if your main systems blueprint gets too crowded with components or if you want to depict a group of interrelated components on their own.

You could share a sketch with a colleague via a link, as part of a discussion in, say, a chat thread, pull request discussion thread or ticket comment thread.

Sources

Where might you acquire the knowledge to build a living systems blueprint?

Anywhere and everywhere...

Ask your colleagues and managers
Search chat and wiki
Ask AI agents
Analyse code and configuration files
Analyse logs and output
Analyse the applications(s) themselves

Resources

Here are some templates you can use to create your own living systems blueprint diagram:

And some system icon sets, depending on which (if any) vendors/providers you are using:

Thoughts on Tailwind

Jonathan — Fri, 24 Jul 2026 03:45:31 +0000

I have mixed feelings about Tailwind, having used it on a client project, built a Typescript adapter for it and my own website for a time, before switching to Vanilla Extract.

On one hand, it seems to have been overhyped and targeted to developers who want to throw stuff together fast, with the predictable result of messy, unmaintainable code. (But I guess the same could've been rightly said about HTML/CSS back in its early days, not to mention Java, VB, etc.)

On the other hand, I think Tailwind does sit on structurally sound foundations. It implements most or all of the core features of the CSS spec, while providing shortcuts in a careful and consistent manner. In this way, it forms a nice abstraction layer above plain CSS.

For example, this:

<span class="foo hover:bg-violet-600"></span>

Is shorter and arguably more readable than this:

.foo:hover {
    background-color: var(--violet-600);
}

So in the right hands, Tailwind can be used to produce clean, maintainable code.

I think a few best practices can go a long way:

Decompose complex HTML structures. Into either smaller nested elements or your framework's flavour of components (React, VueJS, Web Components, etc). Reduce the number of classes you need to deal with at once.
Group and order classes in a consistent and sensible way. For example: 1. Layout, 2. Background, 3. Border, 4. Foreground, 5. Animation, 6. Cursor. And order defaults before overrides: :hover, :focus, etc then defaults.
Use custom theme variables for your custom brand-specific values. Colours, fonts, etc. Rather than repeating the values throughout the code-base. This is similar to how variables are used in CSS.

Overall I think developers should use the framework/language they and their team are strongest in and be cautious about rapidly adopting any new framework/language.

We should especially avoid buying into hype but consider realistic trade-offs and pivot when necessary.

Front end development checklist

Jonathan — Thu, 09 Jul 2026 13:22:00 +0000

I thought I would share my front end development checklist.

Why I use a checklist

Many who worked with me will know I'm a big fan of checklists. I think a good checklist can benefit you in several ways.

It helps you get started. When the task ahead seems overwhelming, such as reviewing a giant pull request, you can just start with the first checklist item and keep going from there.
It helps you organise your thinking. Quickly get clarity on what matters and doesn't matter. Avoid overwhelm and mental fog by following a predictable process.
It helps you identify blind-spots. Common human biases (such as confirmation bias) and also your own individual biases (from past experiences).

Professional software construction and code review are complex tasks involving many elements. Research shows that the human mind is limited and can only work with a finite number of concepts at a given time.

“the working memory is only capable of processing two to six things at a time ... When you are trying to solve a problem that involves too many elements ... your working memory will become “overloaded.””

– Felienne HERMANS • The Programmer's Brain (brackets mine)

Additionally, research shows the human mind can be affected by cognitive flaws and biased thinking. While we are capable of thinking rationally, our minds, in an attempt to conserve energy, often default to a shortcuts and heuristics, leading to critical errors. In Thinking, Fast and Slow, cognitive psychologist Daniel Khaneman describes several of these errors, such as the anchoring effect and the availability heuristic.

Checklist can help you overcome these biases and errors. Surgeon and author Atul Gawande famously wrote a book about this, demonstrating the use of checklists in mission-critical contexts from passenger flights to hospital operating rooms.

“Checklists seem to provide protection against such failures. They remind us of the minimum necessary steps and make them explicit. They not only offer the possibility of verification but also instill a kind of discipline of higher performance.”

– Atul GAWANDE • The Checklist Manifesto

Similar points about checklists have been made by Michael Mauboussin and Charlie Munger.

How to use a development checklist

You can use a development checklist in the following ways:

Self review, prior to submitting changes. Check your work against the list. This gives you an opportunity to anticipate and address any issues in advance, which reduces the code review burden on team mates and helps you to get faster approvals.
Code review, on others' changes. Check others' work against your checklist. You can deliver useful feedback and mentor colleagues.

When scanning the list and picking items to check, you can factor in what makes sense for your current team and project. In this article I provide a general front end development checklist. But you can create your own variants of the checklist, such as one for each project.

Automation and AI

Checklist reviews can be partially or fully automated using AI assistants.

You can feed a checklist and code changes into an AI assistant, using a prompt like this:

Please review the code changes in the current branch.

Look at the checklist in the file: `≪~/Downloads/front-end-development-checklist.md≫`.

Identify which checklist items are relevant for this change.

For each relevant checklist item:
- Review the code change and evaluate whether complies or not.
- List any checklist items for which the code change is not compliant.
- For each non-complied checklist item, provide an explanation and recommendation on how to address it.

Tip: If performance is poor or costing you a lot of tokens, one solution is to break down the checklist into smaller sub-lists. Each sub-list can have a "description" section, specifying the conditions under which the AI assistant read and use it. Following progressive disclosure in this way minimises context and streamlines AI performance and cost.

There are other ways a checklist can be used with AI to boost productivity, such as:

When vibe-coding, include instructions for the AI assistant to self-review its work against the checklist, either in the prompt or in context files.
When using the AI assistant to generate a solution design, prompt it to self-review the solution design against the checklist.
Prompt the AI assistant to go review the whole code-base against the checklist and list cases where the items are not complied with.

Continuous improvement

Feedback you receive in code reviews can be incorporated back into the checklist.

This creates a cycle of continuous improvement, making the checklist a dynamic adaptive system.

Other high quality resources that can be used as sources for checklist items include books, online courses, podcasts, open-source code-bases and code review feedback from past projects

Precedent-based model for code reviews

For team projects, where I add/modify a checklist item in response to feedback, I like to include a link to specific feedback comment.

In subsequent code reviews, if a similar issue is being discussed, I can simply locate the closest matching guideline in the checklist and mention it in the discussion thread, with a link back to the original discussion. The linkage to the prior discussion helps to ground the discussion and provides a precedent for my decision in that specific case.

I found success with this approach, in the following ways:

In some cases, the team agree to stay consistent with the approach suggested by the link to the prior discussion. This agreement helps to drive consensus and move the pull request toward approval.
In other cases, a different approach is proposed. Agreement is found. I can improve the checklist by updating it with a link to this more recent discussion. Additionally, the team benefits by gaining more clarity over the reasoning behind the decision and also a sense of the broader approach being followed.
In a few cases, there is lively debate about which approach to follow. Here, the "precedent model" helps us to organise our thinking and to keep the discussion on-track. In the worst case, I can at least demonstrate effort, think clearly, disagree and commit and maintain forward momentum.

Organising and filtering the checklist

With a checklist of 575 items and growing, you well might wonder how I have the time to go through that many items. 😂

The truth is that I only use a subset of checklist items per situation. The checklist items are grouped into headings and tags which can be filtered. Using the filters, I can quickly narrow down the list to a much more manageable size.

For example, when reviewing a code change that only affects styling, I can filter by styling-related tags.

Front End Development Checklist

Here is the link to the checklist:

👉 Front End Development Checklist

You're welcome to download the whole checklist and re-use it for your own purposes. I also welcome you to suggest improvements. Or you could even fork your own version – I might look to make this easier in future, if requested.

Self-similar: a versatile folder pattern for code

Jonathan — Thu, 07 May 2026 00:46:19 +0000

“The word 'isomorphism' applies when two complex structures can be mapped onto each other, in such a way that to each part of one structure there is a corresponding part in the other structure, where "corresponding" means that the two part play similar roles in their respective structures.”

– Douglas HOFSTADTER

Gödel, Escher, Bach • Meaning and Form in Mathematics • pp. 57

I've seen various trends come and go in code folder and file structure.

The two big ones in the front-end space seem to have been:

Function-focussed.
- 📁 controllers
- 📁 views
- 📁 models
- etc...
Feature-focussed.
- 📁 posts
- 📁 comments
- 📁 likes
- etc...

There have been various efforts to combine them, such as the feature-sliced design.

For example, we can have:

📁 posts
- 📁 controllers
  - 📄 list.ts
  - 📄 detail.ts
  - 📄 create.ts
  - 📄 delete.ts
- 📁 views
  - 📄 list.tsx
  - 📄 detail.tsx
  - 📄 create.tsx
  - 📄 deleted-message.tsx
- 📁 models
  - 📄 post.ts
📁 comments
- 📁 controllers
  - ...
- 📁 views
  - ...
- 📁 models
  - ...
📁 likes
- ...

Overall I like the above strategy. But I wanted to take it one step further.

You see... sometimes I feel I want to have the best of both worlds. A bit of functional and a bit of feature.

Some kinds of things seem to fit neatly into a single feature.
- 📁 posts
- 📁 comments
- 📁 likes
Other kinds of things seem to make more sense as functional pieces.
- 📁 hooks
- 📁 utils
- 📁 mixins

What I've settled on is: consistency in naming with freedom in ordering.

Rules

Here are the rules of the self-similar folder pattern:

Any word can be pluralized: comment => comments.
Any word can be combined with any other word (or combination of words) by a dash: delete, comment => delete-comment.
Any word (or combination of words) can be used to name a folder or file, at any nesting level.

Process

First we start with listing all of the unique "naming words" or tokens in our present file/folder structure (non-pluralized):

border	comment	controller	create
delete	deleted	detail	fetch
get	hook	like	list
local	mixin	model	post
recessed	relieved	storage	use
util	view

Then we group similar words, based on how they seem to be used in the system and how they seem to naturally fit together. (Note that words can be re-used as many times as needed.)

Aside: This technique has long been known in UX design as card sorting.

border, recessed, mixin
comment, list, create, delete
post, detail, list, create, delete
like, list, create, delete
etc...

It becomes clear that certain functions cluster around a single feature. For example, post has detail, list, create and delete. For these cases, we adopt feature grouping.

It becomes similarly clear that certain functions stand alone or group with other similar functions. For example, border variants recessed and relieved are each a kind of mixin, which I consider a function not a feature. For these cases, we adopt function grouping.

Based on the groupings, we order the words by priority:

And then nest them in order.

The end-result:

📁 posts
- 📁 controllers
  - 📄 list.ts
  - 📄 detail.ts
  - 📄 create.ts
  - 📄 delete.ts
- 📁 views
  - 📄 list.tsx
  - 📄 detail.tsx
  - 📄 create.tsx
  - 📄 deleted-message.tsx
- 📁 models
  - 📄 post.ts
- 📁 hooks
  - 📄 like-post.ts
📁 comments
- 📁 controllers
  - ...
- 📁 views
  - ...
- 📁 models
  - ...
📁 likes
- ...
📁 hooks
- 📁 local-storage
  - 📄 hook
📁 utils
- 📁 fetch
  - 📄 get.ts
  - 📄 delete.ts
  - 📄 post.ts
📁 mixins
- 📁 border
  - 📄 recessed.ts
  - 📄 relieved.ts

Notice that this folder structure exhibits a kind of self-similarity.

For example:

detail can appear within either controllers (as a controller) or views (as a view).
controllers, views and models can appear within features posts, comments and likes.
hooks can be grouped together with other hooks, such as local-storage/hook.ts, but alternatively, they can be grouped with a feature, such as posts/hooks/like.ts.

This self-similarity makes the folder structure extremely powerful yet flexible. Any word can be a unit of re-use, but no word is "locked in" to only appearing in one part of the structure. The form is extremely flexible, yet also extremely rigorous.

When to use

It requires effort and teamwork to keep this kind of folder structure well organised. Card sorting is a high-energy, collaborative activity. So this folder structure is probably not a good fit for all scenarios.

If you are a team of, say, Ruby engineers, in a medium-sized corporation, who want to play it safe and follow an established pattern, there's nothing wrong with going function-based. The enemy here is risk of losing control.

If you are a startup, who need to move fast, and don't have time for any hand-wavy card-sorting UX nonsense, there's nothing wrong with going feature-based. The enemy here is time.

Where I see the sweet-spot for this kind of structure is a long-term cleanup operation in a fairly complex project but a small team of very experienced polyglot programmers. Lots of collaboration, lots of care, but also lots of autonomy. The enemy here is complexity of the code itself, and a technique that accepts complexity without succumbing to it is probably the right tool for the job.

There’s no rule that Agents, Skills, Tools or Commands must be LLM-based. Some use cases require 100% accuracy and determinism – for those cases, we can apply these patterns to regular code.

Jonathan — Fri, 13 Mar 2026 23:43:31 +0000

Dealing with flaky tests

Jonathan — Tue, 10 Mar 2026 23:21:54 +0000

Flaky tests are tests that produce inconsistent and non-deterministic results, sometimes passing and sometimes failing. They can undermine the reliability of testing processes and complicate software development by masking real issues and wasting time.

Flaky tests are particularly difficult to debug and fix because of their non-determinism. We cannot simply go through the usual development cycle of test → modify → re-test. This is because we cannot reliably reproduce the error on each re-test, and thus, cannot know whether any single modification has corrected it.

Rather than going all in on one tactic, for flaky tests, I prefer to have a grab-bag of techniques at my disposal. I'll pick and choose one or tactics from this grab bag, based on the situation and context.

In this article I'll share my grab-bag of techniques. These are tactics I've used myself or seen used by others with success.

First we try to reproduce and diagnose the flakiness.

Then, once we have a (hopefully firm) notion of the cause, we can apply solutions or mitigations.

Solutions: actually fixing the flaky tests
Mitigations: minimising harm, impact, cost, etc. for flaky tests we cannot fix

The examples are in Jest and Playwright, as that is what I use in most of my work environments, but similar principles likely apply to other tools.

But before diving into tactics, let's take a brief step back and look at first reproducing the flakiness.

Reproducing flakiness

Fundamental to addressing any kind of software bug is reproducing it.

But how do you reproduce a flaky test? As discussed above, flaky tests are difficult to reproduce consistently because their failure is non-deterministic: sometimes they fail sometimes not.

There are a couple of options here:

Running the test repeatedly to generate a mass of failures
Observing prior test failures in logs

Running the test repeatedly to generate failures

We cannot reproduce the failure on a single run but we might have a chance on multiple runs.

Assuming Jest and a test script, we can use a command like this to repeatedly run a test:

for i in {1..20};
do (
  npm run test -- '{test_file}' --no-watch ||
  (echo "Failed after $i attempts" && break)
);
done

(Replace {test_file} with your test path and filename).

Some test frameworks provide this re-running capability out-of-the-box. Here's how to do it with the Playwright CLI:

npx playwright test {test_file} --repeat-each=20 --fail-on-flaky-tests

To increase the failure rate for reproduction purposes, we can simulate failure conditions.

For example:

Simulating slower CPU and/or fewer cores
Simulating lower available memory
Simulating slower network speeds

These failure conditions will give us more failures, which may hopefully resolve in faster diagnosis of the cause.

Some technologies for enacting these simulations include:

Virtual machines: Running the tests in a Virtual Machine with slow configuration.
Containers: Running the tests in a container, such as a Docker container, with slow configuration.
Test runners: Configuring the test runner itself to run tests slower.

Virtual machine

Using VirtualBox or similar, we can configure limited resources. VirtualBox allows limiting CPU count and processing cap.

Container

Using Docker or similar, we can configure limited resources. Docker allows this via CPU arguments.

For example, we could create a Dockerfile for our app:

FROM node:22.12.0-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .

And use it run our tests, with constrained CPU, like this:

docker run --cpu-shares 2048 tests npm run test

Test runner

In Jest, we can try one or more of:

Turning off the cache using --no-cache
Turning off multiple workers using --runInBand
Increasing the worker count, using --maxWorkers

Aside: By running a higher number of workers than CPU cores, we effectively add more workload to our machine, causing it to run slower. This can help create conditions that will reproduce a test's flakiness.

Observing prior test failures in logs

Alternately/additionally, we can try to gather information about the failures we have had so far.

For example, if a test is being flaky in CI, we can gather log output from the CI environment and examine it to search for clues.

Maybe we can learn something about the cause of the failures by observing phenomena related to the failures.

👀 Phenomena	🚨 Implications
Test fails at a certain time of day	Issue with date/time logic Issue with resource in a particular availability zone
Test fails only when modified	Issue with caching
Test fails when the CI server is being heavily utilised	Issue with test being vulnerable to resource availability

Aside: Tip: Structured logging with detailed information about resource usage, date/time and other data can help to expose more information about test failure in logs. Such info can be logged on test failures. For example, in Jest, we can handle the afterEach hook in a setupFile and inspect [testInfo.failed]. Structured logs can be generated using a library such as structured-log.

Diagnosing flakiness

Once we are able to reproduce flakiness, we can move to diagnosis, to uncover the root cause.

Similar to diagnosing regular bugs, we can diagnose flaky tests by making small changes and measuring the results. With flaky test rates, rather than a single pass/fail, we measure the overall pass/fail rate. A significantly lower percentage of failures can be correlated with a code change to help uncover the cause of the failure.

Aside: Warning: It's important here to emphasise failure of the test to run properly rather than just failure of the test. A flaky test might give false-positives, passing intermittently when it should be failing.

Some of the usual diagnostic techniques can be applied:

Debugging: using console logging statements to observe behaviour of the test and/or application code during test execution
Comparing recent versions: using git bisect or similar to compare results between recent versions of the branch
Process of elimination: removing parts of code and measuring results, to "eliminate" irrelevant parts and identify parts that are actually causing flakiness

Solving flakiness

This section covers possible solutions to flaky tests.

Some solutions might become evident from examining output after reproducing flakiness. In other cases, it might be worth experimenting with various solutions in a "try-and-see" approach.

Await your elements
Keep your promises
Reduce test size
Reduce test file size
Reduce the number of workers
Clean up at the end
Optimise the application under test
Disable resource-intensive application features when running in tests
Increase timeouts

Await your elements

Problem: Operations occur before the DOM has completed loading. For example, the test tries to click a button inside a dialog before the dialog has loaded.

Solution: Wait until elements have been rendered before performing operations that depend on them.

❌

const deleteButton = screen.getByText("Delete");
await userEvent.click(deleteButton);

const confirmButton = screen.getByRole("button", { name: "Confirm" });
await userEvent.click(confirmButton);

✅

const deleteButton = screen.getByText("Delete");
await userEvent.click(deleteButton);


await screen.findByRole("dialog");

const confirmButton = await screen.findByRole("button", { name: "Confirm" })
await userEvent.click(confirmButton);

Keep your promises

Problem: Test operations are being done before Promises on which they rely have been completed. For example, an async API call is made, but the test runs an operation that depends on the API result before the promise has completed.

Solution: Wait for calls to have been made, using, say, a "completed" flag.

❌

jest.spyOn(accountsApi, "getAccounts").mockResolvedValue([{
  accountId: 1234,
  isPrimary: true,
}]);
jest.spyOn(accountDetailsApi, "getAccountDetails").mockResolvedValue({
  accountId: 1234,
  balance: 10,
  accountName: "Jack's Primary Account",
});

render(<PrimaryAccountDetails />);

const heading = screen.getByRole("heading", { level: 2 });
expect(heading).toHaveText("Jack's Primary Account");

✅

jest.spyOn(accountsApi, "getAccounts").mockResolvedValue([{
  accountId: 1234,
  isPrimary: true,
}]);
jest.spyOn(accountDetailsApi, "getAccountDetails").mockResolvedValue({
  accountId: 1234,
  balance: 10,
  accountName: "Jack's Primary Account",
});

render(<PrimaryAccountDetails />);

await waitFor(() => {
  expect(accountsApi.getAccounts).toHaveBeenCalled();
});
await waitFor(() => {
  expect(accountsApi.getAccountDetails).toHaveBeenCalled();
});

const heading = screen.getByRole("heading", { level: 2 });
expect(heading).toHaveText("Jack's Primary Account");

Reduce test size

Problem: A test is very long and, thus, times out before being completed.

Solution: Reduce test size.

Even if we prefer longer integration-style tests, as recommended by Kent C. Dodds in [Write fewer, longer tests], there can still be ways to reduce the size of our tests while preserving their scope.

For example:

Remove operations that are incidental and not really required for the test to exercise the code.
Remove operations that are already covered by other tests.
Simplify operations. For example, retrieve a DOM element directly where possible, rather than traversing multiple parent/child elements unnecessarily.

Reduce test file size

Problem: Test files are large. Processing each large file ties up system resources (especially processor usage), causing other tests to time out.

Solution: Reduce test file size.

One way is to split up test files by function or component.

orders-pending.test.tsx

orders-delivered.test.tsx

orders-cancelled.test.tsx

orders-previous.test.tsx

Or we could use numbering or lettering system.

small-test-01.test.tsx

small-test-02.test.tsx

small-test-03.test.tsx

small-test-a.test.tsx

small-test-b.test.tsx

small-test-c.test.tsx

Reduce the number of workers

Problem: Test runners such as Jest may be greedy and fail to balance resource usage between tests when running many tests in parallel on resource-constrained environments such as CI

Solution: Check the CPU configuration of the CI if possible. Try to reduce the number of simultaneously running tests by configuring the test runner.

Contrary to our human intuition ("more is better") it may be better to reduce the number of simultaneously running tests. This is because test runners can be greedy and consume as many resources as possible at any given time (CPU, memory, etc). Running multiple tests at once can cause resource usage to become imbalanced, as tests compete with eachother for resources.

The solution may be to reduce the maximum number of workers. Jest allows this to be configured via the maxWorkers setting. However, if this exceeds the number of CPU cores on the machine, the processor may be forced to split execution time between multiple threads. This may cause tests to take longer than expected to execute, resulting in timeouts. This problem may only occur on CI environments, where CPU resources may be more limited, making it tricky to identify. Try reducing the maxWorkers setting or even eliminating it. (Jest defaults to the number of cores available on the machine, which is usually the safest bet.)

Clean up at the end

Problem: Tests leave behind "uncollected garbage", such as memory usage, threads, promises, etc. This slows down the test suite as a whole, making some tests flaky.

Solution: Cleaning up after each test reduces resource demand on the test runner, which reduces the occurrence of flakiness.

Note that the flaky test itself might not be the culprit here, but rather, some or all other test(s) as a whole generating garbage. This uncollected garbage might only be noticeable when all tests are run together in CI, not when running an individual test on its own. This can make the "uncollected garbage" issue tricky to detect. It might only be detectable by trial-and-error – say, observing resource usage on the whole test suite over repeated runs.

Increase timeouts

Most test frameworks provide allow timeouts to be configured.

Increasing the timeout allows tests to run longer without failing, which may solve flakiness.

Jest has testTimeout configuration and the timeout parameter
Playwright has timeout configuration and test.slow() (called within a test)

Downside: Increasing timeouts too much or globally might allow performance issues to creep into the application. Timeouts should be increased only on flaky tests if possible, and we should find ways to enure those features continue perform adequately for end-users.

Optimise the application under test

Problem: The application we're testing is itself buggy or just slow. If the application itself is slow, then the automated tests that exercise it will probably also be slow, leading to flakiness.

Solution: Find slow points in the application under test and optimise their performance.

To find slow points, we can add timer statements to different parts of the test or application.

console.time("Fetch user details");
const userDetails = await fetchUserDetails();
console.timeLog("Fetch user details");

We can also try rigorous manual testing, combined with performance tooling, such as Chrome Devtools Performance tab.

Techniques to improve performance can then be applied – see: improving performance in React apps.

Mitigating flakiness

So maybe we've tried all the above and nothing has worked. In that case, we can consider mitigation – approaches that reduce the impact of the problem without solving it entirely.

These might be used temporarily as an emergency resort or permanently if considered a reasonable compromise.

Disable resource-intensive application features when running in tests
Reconfigure test runners
Tag known flaky tests and configure accordingly
Use a different kind of test
Use a different method of verification

Disable resource-intensive application features when running in tests

Problem: Some features of our application may be resource-intensive, causing flakiness, while not offering much value in an automated testing context.

Mitigation: Disable resource-intensive features for test environment only.

Certain application features may be inherently resource intensive and not needed to verify correctness for a given automated test.

Common examples:

Animations (even when implemented with CSS transitions only can create drag)
Graphics (large complex DOM-heavy graphics and loaded as part of a page, such as 3D sprites in Canvas or complex SVGs)
Event Subscriptions (say, to backend events via WebSockets)

These features can be disabled only for test execution, via, say, feature flags.

Reconfigure test runners

Problem: Flakiness produced by resource-constrained environments is not worth the cost savings of the resource constraints.

Mitigation: Increase resources to get better value for investment, such as higher developer productivity during a critical period.

Depending on the cause, test flakiness might be drastically reduced in the short-term by simply beefing up resources on the test runners. Depending on the organisation, business context, timeframe, etc. this might be an optimal approach.

For example, suppose a legacy system is scheduled to be decommissioned in a few weeks, with a newer, totally re-written version already performing well in canary testing and ready to be rolled out next week. If the legacy system has a lot of flaky tests, blocking developers from deploying changes during that short space of a few weeks, it might make sense to increase resources just to unblock developers. Engineer time is more valuable and costly than brute resource usage.

Or suppose the business context is seasonally sensitive, such as an online retailer experiencing very high demand during holiday periods. During this period there is a high velocity of new feature releases, requiring a large number of automated tests of varying quality to run smoothly. Here, trading off resource cost for feature velocity might be worthwhile, at least during the peak period.

Tag known flaky tests and configure accordingly

Problem: Flaky tests block the whole pipeline, interfering with delivery velocity.

Mitigation: Separate flaky tests from non-flaky tests, to ensure that they run correctly or at least do not disrupt other tests.

Many test frameworks allow tags to be applied to tests, allowing those tests to be grouped and treated as a unit, for separate execution, separate configuration, or some other kind of separation.

Flaky tests, once identified, can be grouped in this way for special treatment.

In Playwright, test tags can be included in the test name:

test('test full report @flaky', async ({ page }) => {
  // ...
});

In Jest, a similar effect can be achieved by passing a carefully written regex to the testNamePattern config setting:

package.json:

"scripts": {
  ...,
  "test": "jest --testNamePattern='^(?!.*\@flaky).*$'",
  "test-flaky": "jest  --testNamePattern='^(.*\@flaky).*$'",
  ...,
},

Once separated, flaky tests might be treated in various ways:

Separate environment: for example, run flaky tests on an instance with more resources (CPU, memory), faster network connections, etc.
Separate lifecycle: for example, run flaky tests periodically, so that they are still useful but do not block non-flaky tests.
Separate execution style: for example, re-try the flaky test more times than other tests so that they don't fail

Use a different kind of test

Full end-to-end browser tests are known to be more flaky than traditional unit or unit-style integration tests. This is due to the performance overhead of loading a whole browser, loading the whole application at once, triggering interactions with whole DOM elements and waiting for feedback.

We could instead shift some of these tests to integration-style unit tests. Described in Kent C. Dodd's famous article Static vs Unit vs Integration vs E2E Testing for Frontend Apps, these tests can cover entire user flows (such as logging in) while mocking the calls that could otherwise call flakiness, such as server-side API calls.

Another option, for tests target intermittent but approximately deterministic behaviour, is to use fuzzy logic to verify that behaviour. For example, suppose we need to exercise some behaviour that operates on the current date and time, but for some reason cannot control the current date and time by mocking. If the test assertion does not need to have millisecond-level precision, perhaps we could instead assert against a range considered correct.

❌

  expect(timeAfterClickPause.getTime())
    .toEqual(new Date(2026, 3, 1, 13, 1, 1).getTime());

✅

  expect(timeAfterClickPause.getYear()).toEqual(2026);
  expect(timeAfterClickPause.getMonth()).toEqual(3);
  expect(timeAfterClickPause.getDate()).toEqual(1);
  expect(timeAfterClickPause.getHours()).toEqual(13);
  expect(timeAfterClickPause.getMinutes()).toEqual(1);
  expect(timeAfterClickPause.getSeconds()).toEqual(1);

Use a different method of verification

If our automated test is trying to exercise something that is inherently prone to intermittent failure, within no acceptable margin of error, perhaps we need a different method of verification altogether.

For example, there is probably no good way to write an automated test for generating the next Bitcoin hash on the official fork. (Until/unless we get quantum computing in the cloud, in which case, any crypto-based business model might be in jeopardy!) For this case, we would probably need to wait until we have a large and engaged enough user base and then apply observability.

Various methods of verification that might fit the scenario:

Local browser tests: tests that are run locally and manually by engineers, not in CI.
Monitoring / observability: simply provide observability into a feature without necessarily testing it. Failures can be surfaced in a dashboard or alert. Downside of this method: we risk catching a failure too late, after it has already affected a significant number of users before being discovered.
Manual testing: periodically manually test a feature in a prod-like environment.
Visual diff testing: automatically capture screenshots of the application or component, raising alerts when differences are detected. Causes of differences can be sought by, say, comparing versions of the code base (using git bisect or similar).

Conclusion

Flaky tests undermine testing processes, developer morale and ultimately product reliability. So it's important to address them. Unfortunately fixing flaky tests can be more difficult than consistently failing tests, due to their non-determinism.

Difficulties reproducing flaky tests can be addressed by:

Running the test repeatedly to generate failures
Observing prior test failures in logs

Flaky tests can be dealt with by:

Solutions: Optimising async or time-sensitive code, optimising test or file size to smooth test runner execution, configuring the test runner itself (workers, timeouts) or optimising the application under test.
Mitigations: Disabling application features that tend to induce flakiness, increasing test runner resources (temporarily or permanently), separating flaky tests (say, by tagging) or opting for a different kind of test or verification.

How I built my designerly CV

Jonathan — Sat, 28 Feb 2026 05:43:00 +0000

As a Front End Engineer – a weird yet oddly common cross between software engineer and designer – I made three self-discoveries early on:

I am often looking for work
I care about aesthetics
I can hack almost anything

Thus, necessity proved the mother of invention, and I found myself striving to produce a CV worthy of my profession.

Selecting a word processor

This might seem like a problem of the 90s, but even now in an age of free browser-based apps, I still found it a non-trivial question.

My requirements:

Free & open-source (I'm well off enough, but just allergic to subscriptions to big tech firms)
Minimal dependency on web connectivity (I want to be able to edit my CV at short notice with limited Internet connectivity)
Able to save as a regular file in the file system and share easily (say, as an email attachment, in a LinkedIn message, etc.)
Able to export to common formats – both PDF and Word (in case a recruiter needs to edit in their logo)
Compatible with Mac and Windows (I sometimes work on a Windows box)

With a very small learning curve LibreOffice ticked all the boxes nicely.

Layout design

Before jumping into the word processor, I first developed a very simple pen & paper sketch, followed by a simple block diagram in Draw.io. This allowed me to experiment and tweak the design at a high level until I reached something I was comfortable with.

I ended up with a vertically stacked set of blocks for the jobs, with each block having a two-column layout with duties on the left and details (such as start/finish dates, tech and testimonials) on the right.

The design also includes a big header with some upfront features such as the tech I mainly focus on and my formal education. And an end section with side projects and short courses.

Implementation

Tables are supposed to be anathema to web developers, aren't they? Well, this design is intended for a static document format (Word, PDF) or printed paper. It is not intended for the browser. Those who prefer or need to use a browser are welcome to peruse my Work section on conwy.co or my LinkedIn profile.

It was quite easy to use the native Table, Paragraph, Bullets and Style & Formatting facilities of LibreOffice, which play nicely with Word and PDF. Margins, padding and bullet style are all fully configurable, so I was get a close to perfect design.

To be sure, as I was building the CV, I frequently exported to PDF and Word to check the results.

Dancing with content

Content writing for static documents is surprisingly different than for web, especially when working with a carefully crafted layout. You can't rely on the user's scroll bar so much, so text needs to be carefully crafted to fit inside the container.

I found myself going back and forth between Sublime Text and LibreOffice – the former to craft source material, the latter to edit it down to fit within the "real estate" of a formal document.

A few tricks in no particular order:

Shortening month names (~~Jan~~ → Jan, etc)
Abbreviating date intervals (~~year~~ → yr, etc)
Reducing font size on whole lines (like testimonial author and date)
Combining multiple details onto one line (like start/finish dates, period, industry)
Removing unnecessary verbosity and non-essential grammar (trading off minor grammatical correctness for visual appeal)

Finishing touches

For a finishing touch, I wanted to use a nice fancy font for headings.

After some exploration I settled on Sweden Sans, kindly made available in the public domain by the generous tax payers of one of the most liveable countries on Earth.

Web developers have it easy when it comes to interesting non-standard fonts. We just package the WOFF/TTF/ODF with our website and link to it. Or better yet, use Google Fonts and just grab a link there.

A quirk of word processors like LibreOffice, when exporting an editable format like Word/DOCX, is that you cannot rely on the end-user having installed all the required fonts.

But there's a hack! You can embed fonts in Word files. And it turns out LibreOffice fully supports font embedding. Simply go to File → Properties → Font tab and check Embed fonts in the document. This worked nicely, both for exported Word/DOCX and, of course, PDF files.

Download my template

In the spirit of Christmas I thought I'd share my CV, accompanied by a re-usable template.

My CV • Download: conwy-cv.zip
Designerly CV Template Package • Download: conwy-designerly-cv-template-package.zip

Generic HOC creator pattern for React

Jonathan — Fri, 24 Jan 2025 02:11:00 +0000

I've recently developed a pattern that allows me to compose two React components together in a highly decoupled way, using a generic HOC creator.

In this article I'll motivate and outline the pattern, provide an example, and discuss my own implementation, createWithHOC.

Motivation

Suppose we have an extremely general component, which we want to widely re-use by connecting it to other components in our component library.

This component is so general that most of its end-consumers will not know it even exists.

However, its end-consumers will need to customize its behaviour, by means of props.

Pattern

The pattern here is to create a HOC (Higher-Order Component) creator function, which can be applied to the general component by the combined components and exported for re-use by the consumer components.

The HOC creator function is called and passed the general component as a parameter, along with a string descriptor (more on that later).
Its result is a HOC, which is exported. This exported HOC allows the general component to be combined with another component.
One or more other components call this HOC, to combine themselves with the general component.
Its result is a component which has almost identical props as the combined component, except that it includes one additional prop. This additional prop, named by the string descriptor from step 1, contains the props to be passed to the general component.

Example

Let's look at a realistic example to see how this pattern can be applied.

Suppose we have a Tooltip component, which takes a children prop and a contents prop. The children prop will have the component that triggers the tooltip. The contents prop will have the component that should be shown inside the tooltip.

interface TooltipProps {
  readonly children: ReactNode;
  readonly contents: ReactNode;
}

export function Tooltip(props: TooltipProps) {
  // ...
}

Now in our component library, there are several different components that might all need to have a tooltip.

For example:

Button
Checkbox
Image

For each of the above three components, we want to allow their consumers to provide an optional tooltip. But we don't want to couple these three components too closely to the Tooltip component. And we want the re-use of the Tooltip component to be as easy and straight-forward as possible.

First, in our tooltip.tsx file, lets create and export an HOC that exposes Tooltip in a re-usable manner:

export const withTooltip = createWithHOC(Tooltip, "tooltip");

Notice that createWithHOC doesn't know much about Tooltip. It just receives its definition and a string descriptor - "tooltip". However, what it returns - withTooltip - is very useful.

Here's a simple implementation of our Button component:

interface ButtonProps {
  readonly children?: ReactNode;
  readonly onClick: VoidFunction;
}

export const Button_ = (props) => {
  return (
    <button onClick={props.onClick}>
      {props.children}
    </button>
  );
};

export const Button = withTooltip(Button_);

If we were to consume Button directly, without the withTooltip wrapper, it would have the children and onClick props, as we would expect.

However, with the withTooltip wrapper call, Button is now augmented with an additional tooltip prop. (Named by the string "tooltip", which we originally passed to the createWithHOC call in our tooltip.tsx file).

So now the props of Button_ look like this, from a consumer's point of view:

// Note: Fictitious interface name.
// This is just the un-named type of the props parameter of the
// `Button` component exported in the previous code sample.
interface ButtonProps { 
  readonly children?: ReactNode;
  readonly onClick: VoidFunction;
  readonly tooltip?: TooltipProps;
}

So when we consume Button, our code can look like this:

const Item = () => {
  return (
    <Button
      onClick={handleDeleteClick}        // <-- <Button_> props
      tooltip={{ contents: "Delete" }}   // <-- <Tooltip> props
    >
      🗑️
    </Button>
  )
}

This will have the same net effect as if we had consumed Button_ directly, wrapped in Tooltip, passing the appropriate props to each.

const Item = () => {
  return (
    <Tooltip contents="Delete">
      <Button_ onClick={handleDeleteClick}>
        🗑️
      </Button_> 
    </Tooltip>
  )
}

Advantages

I found three advantages of using this pattern, where applicable:

Smaller consumer code
Aesthetically pleasing consumer code
Ability to constrain re-use of general components

Smaller consumer code

Consumer code is significantly smaller and less indented, as we are relying on props rather than nesting. This benefit can add up quickly when, say, rendering multiple instances of the same component type side-by-side.

Here's an example of multiple buttons with tooltips:

const Item = () => {
  return (
    <>
      <Button onClick={handleDeleteClick} tooltip={{ contents: "Delete" }}>
        🗑️
      </Button>
      <Button onClick={handleEditClick} tooltip={{ contents: "Edit" }}>
        📝
      </Button>
      <Button onClick={handleCopyClick} tooltip={{ contents: "Copy" }}>
        📑
      </Button>
    </>
  )
}

Aesthetically pleasing consumer code

Consumer code is also more aesthetically pleasing, when relying on props. It presents as a cleaner, more compact and concise list of components.

Here's an example, in which we render different kinds of form controls side-by-side.

Using the generic HOC pattern, each form control is passed a prop to configure one or more of:

A label
A default
Validation logic

const Item = () => {
  return (
    <>
      <TextInput
        name="firstName"
        label={{ contents: "First name" }}
        validation={{ required: true }}
      />
      <TextInput
        name="lastName"
        validation={{ required: true }}
      />
      <DateInput
        name="dob"
        label={{ contents: "Date of birth" }}
        validation={{ required: true, maxDate: nowMinus18Years }}
        default={{ value: nowMinus20Years }}
      />
      <Checkbox
        name="registerForUpdates"
        label={{ contents: "Register for updates" }}
      />

      <Button type="Submit">
        Submit
      </Button>
    </>
  )
}

All controls appear at a consistent level of indentation and so do their props. This is easier to read and more aesthetically pleasing than if each control was nested in a different set of containers (validation, etc) and appeared at inconsistent levels of indentation.

Aside: This could be viewed as a variant of the principle of "cleaning up irregularity", discussed in Dustin Boswell's book The Art of Readable Code, under Aesthetics (Chapter 4, pp. 37).
The code follows a regular pattern, making it easier to visually scan and add/remove similar items (in our example, form controls).

Ability to constrain re-use of general components

An additional advantage of this pattern is that we could, if desired, constrain the re-use of our general component.

For example, we could keep the Tooltip itself private to its module folder and only export the withTooltip HOC. Then we could only apply withTooltip to components that we are confident will work well with the Tooltip.

As a consumer, it would be easy to determine whether a given component supports the tooltip or not – we could simply examine the available pops via our IDE's auto-suggest feature.

Here's an example with Visual Studio Code IntelliSense:

Implementation

Here's the createWithHOC function I developed in Typescript for creating the with* HOC creator.

import { get, omit } from "lodash";
import { ComponentType } from "react";

export function createWithHOC<THOCProps, THOCName extends string>(
  HOC: ComponentType<THOCProps>,
  hocName: THOCName,
) {
  return function withHOC<TLOCProps extends JSX.IntrinsicAttributes>(
    LOC: ComponentType<TLOCProps>,
  ) {
    return function ComponentWithLOC(
      props: TLOCProps & Partial<Record<THOCName, THOCProps>>,
    ) {
      const hocProps = props[hocName] as THOCProps;
      if (hocProps) {
        const hocPropsWithoutKey = omit(hocProps, "key") as THOCProps;
        const hocKey = String(get(hocProps, "key"));
        const locPropsWithoutHocProps = omit(props, hocName) as TLOCProps;
        return (
          <HOC {...hocPropsWithoutKey} key={hocKey}>
            <LOC {...locPropsWithoutHocProps} />
          </HOC>
        );
      } else {
        return <LOC {...props} />;
      }
    };
  };
}

I also published it as a Github Gist: create-with-hoc.ts.

Please feel free to re-use, tweak and/or share as desired. I hope someone out there finds it useful!

Diagramming React code

Jonathan — Sat, 18 Jan 2025 10:37:00 +0000

After working on a Typescript diagram format I wanted to focus on a React equivalent.

Diagrams can be useful for various purposes:

Quickly sketching ideas with pen & paper or a diagramming too such as Draw.io
Designing a solution at a high-level before writing any code
Comparing different designs with eachother to decide which one is best
Understanding an existing code-base by diagramming it
Working out a refactoring strategy

In this article I'll describe a UML-influenced diagramming format for React.

Overview

The format consistent of the following elements:

Component - rectangle with title and list of props
Component call - caller to callee connected with solid-arrow-terminated line
Component call with props - caller to props and props to callee connected with solid-arrow-terminated line
Component render props - render prop rectangle connected to component with dot-terminated line
Function - rectangle with title and list of parameters
Type or interface - rectangle with title and list of props

Component

A component is depicted with a depicted with a rectangle with <<Component>> descriptor and title at the top and, optionally, props underneath.

Component call

A component can render another component – here this is referred to as a "component call".

A component call is depicted with a line from the caller component rectangle to the callee component rectangle, terminating in a filled arrow symbol.

Component call with props

A component can pass props to another component – here this is referred to as a "component call with props".

A component call with props is depicted with a line from the caller component rectangle to a props rectangle and another line from the props rectangle to the callee component rectangle, terminating in a filled arrow symbol.

The props are depicted in a props rectangle, in which each prop has its own rectangle. This allows any individual prop to be linked to a type, function or component rectangle.

Component render props

Render props are props for which we pass a React component, a function which renders a component or a React node.

A render prop is depicted with a line from the prop box to a Component or Function rectangle, terminating in a dot symbol.

Function

Same as in the Typescript diagram format, a function is depicted with a rectangle with <<Function>> descriptor and title at the top and, optionally, parameters underneath.

Type or interface

Same as in the Typescript diagram format, a type or interface is depicted with a rectangle with <<Type>> or <<Interface>> descriptor and title at the top and, optionally, fields underneath.

A composition relationship between types or an inheritance relationship between interfaces is depicted with a line from the composer/inheritor to the composed/inherited type/interface, terminating in an empty arrow symbol.

A reference relationship between two components, functions, types or interfaces is depicted with a line from the referencer to the referenced, terminating in an arrow symbol.

Example: contacts list

Here's an example of a React diagram depicting components that make up a contacts list.

ContactsList component
ContactsList -> ContactListItem component call with render props
ContactsListItem component
ContactPhone component
ContactEmail component
Contact interface
getContacts function

Downloads

To make it easier to use this format, I've implemented downloadable templates for common diagramming tools:

Mermaid • Download: diagramming-react.mermaid.md
Draw.io • Download: diagramming-react.drawio
Figma • Download: diagramming-react.fig

AI for developers

Jonathan — Thu, 09 Jan 2025 03:00:00 +0000

Over the last couple of years, I've sprinkled AI usage through various typical software engineering activities.

The most common tools (and what I tend to use) have been Copilot and Copilot Chat, but some free tools such as Llama Coder are beginning to become more mainstream.

In this article I'll summarise the scenarios where I found AI useful.

Writing code faster with autocomplete
Getting help with error messages
Getting help with technical problems
Writing bash scripts
Generating unit test code
Summarising conversations
Code reviews

Writing code faster with autocomplete

AI-powered autosuggest was a great help when I had to write a chunk of code that's necessarily verbose, but not unique to my problem.

A perfect example is given on Copilot extention homepage.

Getting help with error messages

Pasting an error message into Copilot Chat, prefixed with /fix, can provide good guidance on the cause and fix for a given error.

When the responses given aren't suitable, follow-up prompts such as "can you suggest some other alternatives" can help.

Getting help with technical problems

Similar to error messages, I found that expressing a technical problem in an AI-powered chat can yield some good ideas and solutions.

This worked even better when I followed up the initial question with clarifications and/or challenged the AI to think of additional ideas or alternatives.

Writing bash scripts

Bash scripts can perform many kinds of general tasks. Once you have a script that does what you want, you can re-use it any number of times.

A specific need I had was to see all the authors who had edited a particular file in a Git repository. With the help of ChatGPT I was able to write a script that achieved what I wanted.

Here's the prompt I used:

Copyable: Please write a bash script which finds and lists all the unique authors who have edited the given file in the current Git repository. The given file will be specified as the first parameter to the bash script.

I've published the resulting script as a Github Gist: list_authors.sh.

The script takes as an argument the path to a file in that repo. It then uses git log on the current repository to find all the authors who have edited the file, sorts and uniqs them and outputs them to stdout.

Here's a sample of the output from running it on a file in the NextJS repository:

$ list_authors packages/next/src/shared/lib/head.tsx
Authors who have edited 'packages/next/src/shared/lib/head.tsx':
Adam Stankiewicz <sheerun@sher.pl>
Filipe Medeiros <filipesilvamedeiros@gmail.com>
Gerald Monaco <gerald@gmonaco.me>
JJ Kasper <jj@jjsweb.site>
...

Generating unit test code

I sometimes use GitHub Copilot to generate unit tests for a particular code file I am working on.

This can be done by opening the file under test, pressing Cmd+I and asking Copilot to write a unit test for the current file.

I would use a prompt like: "Please write a unit test for this file".

I use this is mainly to set up the scaffolding, such as describe and it blocks and basic assertions. Usually I need to tidy up a few things here and there, but the AI is surprisingly good at generating decent test code.

Another technique is to provide just the code for one function or code block and ask AI to generate test code for it, listing a few test cases.

Here's an example of a prompt I might use:

Copyable: Please write a Jest unit test for a Typescript function.

The unit test should have the following it blocks:

returns a list of dates between the two dates passed

returns an empty array if two identical dates are passed

throws an error if null is passed

Please write tests that satisfy the above it blocks.

Here is the Typescript function:

\`

function calculateDaysBetweenDates (begin, end) {

var beginDate = new Date (begin) ;

var endDate = new Date(end) ;

var days = Math. round (endDate - beginDate) / (1000 * 60 * 60 * 24) ) ;

return days;

}

`\

Summarising conversations

Some colleagues and I had a long back-and-forth about code reviews in a Github discussion.

When it came time to summarise all these in a meeting, I found that AI-powered chat was a great way to summarise the discussion and get everyone's thoughts on what we had discussed.

It looks like ChatGPT now has a quick Summarise button for this purpose.

Code reviews

When reviewing pull requests I've been experimenting with various ways of asking AI help me.

One way I found useful was to have AI review and summarise the changes and overall quality.

Here are the steps I took for doing this with Copilot Chat:

Generate a diff between the pull request source and destination branches.
- git checkout <source-branch> to checkout the branch
- git diff <destination-branch> | pbcopy to run the diff and copy the output
Paste the whole diff into a new empty tab in VS Code
Press Cmd+I and prompt Copilot: "Please review these code changes"

Here's a sample of the kinds of results I tended to get (anonymised):

The code changes introduce several new features and modifications to the healthcare application. Here are the key points:

Localization Updates:

Added new localization strings for transfer confirmations in en-AU.json.

Removed Mock Initialization:

Removed the conditional import of mock initialization in layout.tsx.

New Patient Transfer Form Submission Logic:

Created a new file submit.ts to handle the patient transfer form submission logic.

This includes creating a Ward object, making a patient transfer request, and handling different states of the transfer (success, delay, error, no-response)

Transfer Form Tests:

Updated transfer-form.test.tsx to reflect changes in patient name and ward number and added tests for the new patient transfer form submission logic.

Overall, these changes enhance the patient transfer functionality by providing detailed feedback on the transfer status and improving the test coverage for various scenarios.

Not as good as a human reviewer, but not useless either.

And not bad given the tiny effort on my part!

Conclusion

While I feel AI might have been a little over-hyped, I think there's still merit in becoming familiar with it and using it where it fits.

It seems likely that AI adoption among software engineers will grow, so it will be advantageous to be familiar and conversant with the tooling.

AI user interface patterns

Jonathan — Fri, 04 Oct 2024 03:01:52 +0000

As AI capabilities become increasingly available to everyday development teams, it might be useful to explore way to surface these capabilities to end-users.

This article describes some user interface patterns for surfacing AI.

Using "treat it like a person" as a core principle, I provide patterns, examples (including in-the-wild cases) and how they mimic humans.

Principles

As the definition of "AI" is still somewhat in flux, I want to assume a definition for the purposes of this article:

The capability of software/machines to do things that are normally thought of a human, in a rational way.

The fact AI mimics human thinking/behaviour suggests that we user interfaces should expose AI capabilities in a human way.

As Ethan Mollick puts it in the book Co-Intelligence (bold mine):

AI doesn’t act like software, but it does act like a human being. I’m not suggesting that AI systems are sentient like humans, or that they will ever be. Instead, I’m proposing a pragmatic approach: treat AI as if it were human because, in many ways, it behaves like one. This mindset, which echoes my “treat it like a person” principle of AI, can significantly improve your understanding of how and when to use AI in a practical, if not technical, sense.

The patterns I've encountered are:

Inline suggestion
Single-agent chat
Multi-agent chat
Prompting and nudging controls

Let's look at them in detail...

Pattern: Inline suggestion

While performing a task, relevant ideas are displayed nearby in text or even imagery.

The user might be invited to provide input, such as selecting between variants or filling in a blank. (See Fill-in-the-blanks pattern)

Example: As a product owner enters a story into a task tracking system, the AI suggests edge cases they didn't yet consider.

In the wild: Code assistance plug-ins in IDEs (such as Genie AI, Amazon Q, CodeGPT, Codeium and Llama Coder) and dedicated IDEs (such as Cursor). Email and text message completion, as seen in Gmail, LinkedIn messaging and Apple Messages.

Mimics: 🧍 Colleague, mentor, friend, etc. sitting nearby verbally offering a suggestion and/or physically pointing to a part of the screen.

Pattern: Single-agent chat

A specialised chat bot is available for back-and-forth discussion.

Example:: Customer on an e-commerce website starts entering a question about a product. A specialised chat-bot replies with a detailed response. An input box allows the customer to respond with a follow-up question.

In the wild: "Have a question?" feature on Hotels, "QnaBot" on Amazon.

Mimics: 💬 Colleague, mentor, customer service, etc. communicating with the user via chat.

Pattern: Multi-agent chat

Multiple chat bots appear in the same chat window. Each bot has a different persona and perspective, and only contributes where applicable.

By splitting AI responses among multiple bots, rather than just one, it's easier for the user to mentally divide the AI output into different "buckets".

Also, because this is analagous to real human-human team-work, it's intuitive for people.

Users can address individual bots by name, to ask for further assistance on a specific topic or aspect covered by just that bot.

Example: Financial advisor tool for recommending products to customers. Agents representing analysts and compliance each offer a perspective. The advisor uses these insights to prepare for a meeting with the client.

In the wild: Slack automation bots such as Trello for Slack, ThreadReaderApp on Twitter and dedicated chat platforms such as Symphony.

Mimics: 👭 Group of people working together, such as a team meeting.

Pattern: Fill-in-the-blanks

A stencil is displayed, with some areas for user input and some ares for AI generated content.

As the user fills in the inputs, the AI uses contextual information to generate more of the content. User and AI both work together until the full output has been generated.

Example: Writing a CV for a job. You start to fill in work history items. The AI suggests additional bullet points, which you accept or refuse. The AI suggests shorter more focussed descriptions and word removal, which you accept or refuse.

Mimics: 📈 Collaborative white-boarding with colleagues (virtually or physically), collaborative card sorting exercises with a team.

Pattern: Nudging controls

A "work in progress" is displayed in the center while command-buttons for "nudging" are displayed around the edges or off to the side. By clicking the buttons, you can ask the AI to change the work along some dimension.

Example: 3D image manipulation. We ask the AI to make the shape more or less rounded, more or less flat, etc.

In the wild: Dall-E image generator.

Mimics: 💺 Pairing with a designer, where the designer is tweaking this or that based on your input.

DEV Community: Jonathan

We’re all full stack now

Living systems blueprint

What it is

Diagram format

How it helps

Systems blueprint sketches

Sources

Resources

Thoughts on Tailwind

Further reading

Front end development checklist

Why I use a checklist

How to use a development checklist

Automation and AI

Continuous improvement

Precedent-based model for code reviews

Organising and filtering the checklist

Front End Development Checklist

Further reading

Self-similar: a versatile folder pattern for code

Rules

Process

When to use

There’s no rule that Agents, Skills, Tools or Commands must be LLM-based. Some use cases require 100% accuracy and determinism – for those cases, we can apply these patterns to regular code.

Dealing with flaky tests

Reproducing flakiness

Running the test repeatedly to generate failures

Virtual machine

Container

Test runner

Observing prior test failures in logs

Diagnosing flakiness

Solving flakiness

Await your elements

Keep your promises

Reduce test size

Reduce test file size

Reduce the number of workers

Clean up at the end

Increase timeouts

Optimise the application under test

Mitigating flakiness

Disable resource-intensive application features when running in tests

Reconfigure test runners

Tag known flaky tests and configure accordingly

Use a different kind of test

Use a different method of verification

Conclusion

Further reading

How I built my designerly CV

Selecting a word processor

Layout design

Implementation

Dancing with content

Finishing touches

Download my template

Generic HOC creator pattern for React

Motivation

Pattern

Example

Advantages

Smaller consumer code

Aesthetically pleasing consumer code

Ability to constrain re-use of general components

Implementation

Diagramming React code

Overview

Component

Component call

Component call with props

Component render props

Function

Type or interface

Example: contacts list

Downloads

AI for developers

Writing code faster with autocomplete

Getting help with error messages

Getting help with technical problems