DEV Community: Erik Pukinskis

How to "own" a project if you're an engineer

Erik Pukinskis — Fri, 31 Jan 2025 16:55:38 +0000

We're working through the Four roles your software team can't function without.

Last time we talked about the Bug Warden, but perhaps the most important is the "Epic Owner".

Why engineers should own epics

A software project goes through many phases with different collaborators involved in each phase:

Requirements gathering — PM leads, with user researcher supporting
Design — Designer leads with PM supporting
Technical planning — Engineer leads, designer supporting
Prioritization — PM decides when projects are ready to go into production
Development — A team of engineers lead, designer providing clarification and PM providing making strategic calls
Testing — QA leads, with engineers supporting and PM validating
Release & validation — PM leads, with engineers supporting

In theory, anyone could be the central coordinator throughout this process... you could make an argument for a PM doing it (to shepherd the business goals), a designer (to shepherd the user experience), or even a project manager.

And frankly, if someone else on your team is already doing a great job coordinating all of this stuff, let them.

But it's much more common that the individual contributors around you are focused on their... individual contributions. And there's a void for someone to step up and do some leadership.

If you're an engineer, and you want to show that you're more than just a grunt, that you're taking responsibility, and owning the outcome then you might want to take on the Epic Owner role.

Six process touchpoints the Epic Owner owns

Fundamentally, owning an epic means being there at key moments when work is handed off. We listed 7 phases of product development and not coincidentally there are 6 key handoffs that need to happen for a project to go smoothly.

1. User Story Workshop

When: The designer is picking up the project

Who: PM, Designer, Epic Owner

The designer's job is to get into the weeds of how a problem will be solved for a user. But before Engineering can start implementing a design, it's crucial that the team is aligned on what problem is being solved.

User Story Workshop Checklist:
☐ Distill project brief into concrete user stories (as a [persona] I want [scenario] so that [motivation])
☐ Propose simplifications
☐ Separate stories into P0 (hard requirements) and P1, P2, etc

Engineers can provide huge value at this stage, and get massive value in return:

✨ Engineers can propose simplifications of a concept, to avoid wasting Design time mocking up features that don't need to be built.

✨ Engineers can use stories later on to resolve ambiguities in the mockups, and to help decide between tradeoffs.

2. Design Review

When: A new set of designs is ready for feedback

Who: Designer, Epic Owner

Most engineers pride themselves on being able to build anything that is specced out for them. But Design Review is one of the places engineers ever create the most "value per hour":

Design Review Checklist:
☐ Point out any gaps in the flows that the designer may have missed
☐ Propose simplifications

The value engineers get from Design Review...

✨ Engineers save their own time avoiding building unnecessary features

✨ Engineers make sure the designs represent the full scope of work, so projects don't slip later on due to "scope creep"

3. Task-out

When: Before development starts or a firm estimate is needed

Who: Epic Owner

Task-out means taking all of the User Stories, specifications, and mockups and planning out the sequence of tasks that need to be done for the feature to be delivered.

Task-out checklist:
☐ Break work into bite-sized tasks
☐ Ensure tickets have acceptance criteria
☐ Indicate which tickets are blocked by others
☐ Add priorities to tickets (blocker/high/low)
☐ Document questions to be resolved & decisions made
☐ Schedule additional design review if needed

Task-out provides...

✨ A way for Engineers to make reliable estimates. The simplest thing you can do is divide the number of stories by how many stories a dev typically does per week and get a pretty reasonable number of dev weeks to allocate.

✨ Proper sequencing of tasks avoids bottlenecks that cause delays and make Engineers look bad.

✨ Writing acceptance criteria often surfaces some remaining open questions. Answering those questions before development means Engineers avoid throwing away work halfway through development.

4. Kickoff

When: Engineers are ready to start development

Who: Epic Owner, Designer, implementation team

Kickoff is when you bring the implementation team into the fold and start actually building.

☐ Walk through designs
☐ Walk through task list and point out which work is out of scope for each task
☐ Talk through who will do what
☐ Move stories onto the board or into an iteration
☐ Assign a start and end date for project
☐ If questions come up, schedule additional design review

Value for Engineers:

✨ Avoid having engineers go down rabbit holes trying to do too many tasks at once.

✨ Make sure everyone understands the full scope of work.

5. Technical Design Discussion

When: Substantial questions pop up as to how to implement something

Who: Implementation team, Epic Owner

Once development has begun, one of the best things an Epic Owner can do is to pull the team together to resolve questions that come up.

Typically, there will be a specific dev who is charged with implementing something that could be done in a few different ways.

As Epic Owner, you should ask that dev to start a document with a brief overview of the problem and possible solutions.

Technical Design Discussion Checklist:
☐ Document open questions
☐ Document possible answers to those questions
☐ Document pros and cons for each possible answer
☐ Document decisions made
☐ Surface any new scope that has been added to the PM

Value for Engineers:

✨ Save time finding better, easier solutions to challenges.

✨ Avoid having the same discussions over and over again (decisions are documented!)

6. QA handoff/Bug Bash

When: A project is ready for QA

Who: Epic Owner, QA lead, PM

Finally, it's time to get a project out to your users, so we need to ensure quality. Having a Bug Warden will help, but as Epic Owner you also need to facilitate QA.

Your job as Epic Owner is to make sure important details about the changes get to the people who will be doing QA and onboarding customers.

This is also a great time to bring the PM back into the fold, when there's time to allocate final project resources and make final adjustments to scope, quality bars, etc.

QA Handoff Checklist:
☐ List new behavior that is in the release
☐ Note refactors that were done and what areas of the product they might affect
☐ List known issues

Value for Engineers:

✨ A good list of known issues means fewer duplicate bug reports the team has to triage

✨ If QA knows the full scope of changes they'll find more bugs for you sooner.

✨ Better QA means fewer embarrassing bug reports coming from customers, product demos, etc.

Quick, focused meetings

That's a lot of meetings! (you might be thinking)

And it is. But in my experience you ignore these key handoffs at your own peril. Every one of these checklists comes from actual projects that went off the rails.

But it's also important to remember that meetings don't have to be heavy or even lengthy.

To keep meetings light...

Invite as few people as possible—Try to keep out people who are "just going to listen." These meetings are for specific people to answer questions so they can get work done.

Use the checklists—I've given you a ready-made agenda for each of these handoffs.

Cut people off—If folks start discussing something that's not on the agenda, praise them for bringing up something important and tell them to put their own time on the calendar to work out the details.

Finish early—You might have 50 minutes on the calendar, but if you can let everyone go in 15, do it!

Delete process—If a meeting is not feeling critical for your team, consider removing it. And remove items from the checklists that don't feel essential too.

The goal is for these meetings to feel like like no brainers to everyone involved. I've laid out what I think is are some good starting points, but for your team to really buy in to this kind of structure, they need to feel like they are continuing to author the process.

It's better to do fewer of these meetings, but have your team really bought into the ones you do.

Be patient

Lastly, don't worry if you can't do all of these things right away.

The best time to introduce new process is when your team is struggling with a specific challenge.

Is your team struggling with buggy releases? Add QA Handoffs. Do you find your timelines keep slipping? Start doing more thorough Task-outs.

Rather than feeling like you're putting onerous process on people, it will feel like you're saving the day.

If it's still January 2025, and you are looking for an experienced Engineering Manager in San Francisco or remote... Hire me!

Part of a multi-part part series on "Software Engineering Roles"...

Follow me on LinkedIn or Twitter/X to hear when the next part is posted!

Part 1: Four roles your software team can't function without
Part 2: If you have bugs, you need a Bug Warden
Part 3: How to "own" a project if you're an engineer
Part 4: The Release Warden
Part 5: The Program Manager

Cover image © Evgenii Naumov

User story workshop illustration © Ladadikart

Design review illustration © Burlesck

Task out illustration © Eamesbot

Kickoff illustration © Applikbeats777

Technical design discussion Illustration © Rogerothornhill

QA handoff/Bug Bash illustration © Ernest Akayeu

If you have bugs, you need a Bug Warden

Erik Pukinskis — Mon, 20 Jan 2025 18:02:52 +0000

Last time, I introduced the Four roles your software team can't function without.

These roles are the four areas where I think software engineers need to go beyond just writing code and take on some broader responsibilities.

One of the busiest of these is a rotating role called the "Bug Warden".

What does a Bug Warden do?

The Bug Warden's core responsibility is triaging bug reports. This doesn't need to be a heavy, time consuming task. It can be as simple as delegating the investigation to another engineer:

However in practice there are a number of things the Bug Warden might need to do:

Ask the reporter for more details
Create a ticket in a project tracker
Try to reproduce the issue
Find a duplicate ticket, for issues that were previously reported
Figure out which engineer should be assigned the bug, assign them, and @-mention them so they're aware of it
Assign a Severity, a Release Status, and any other metadata your company is tracking

This is critical work which often falls through the cracks on teams, with Engineering assuming QA will do it, and QA assuming Product will do it, and Product assuming Engineering will do it!

What you need to track

There are a million ways to organize your bug reports, but in my experience there are two pieces of information that are critical to track:

1) Severity — A S0 bug should be worked on immediately, an S1 bug should be worked on in this release cycle, and an S3 can wait for the next cycle.

2) Release Status — Fixes often move through several environments on their way to production. So this status will either be the target environment (for a known issue) or the release environment (for issues that have been fixed):
- Fix in an upcoming release (dev)
- Fix in the current release (staging)
- Hotfix (production)
- Fixed on dev
- Fixed on staging
- Fixed on prod

These two pieces of information allow the Bug Warden and other stakeholders to make a variety critical decisions:

Should an engineer stop what they're doing and focus on a bug?
Does a release need to be delayed?
Are there fixes that needs to merged into the right environment?

If an S0 was a hotfix that went out to production, it may need to be back-merged to staging for further integration. If an S1 has been tested in the development environment, it may need to be pushed to staging.

These decisions can only be made correctly if you track the status!

Beyond bug reports

In addition to the core job of triage, the Bug Warden is also responsible for running three meetings each cycle:

Bug Warden Handoff (near the start of the release cycle)

The primary purpose of this meeting is to there are no lapses in coverage; that when your rotation is done another engineer picks up the baton.

Invitees: The incoming Bug Warden, and the outgoing Bug Warden

Checklist:
☐ Add the new Warden to a @bug-warden team handle in Slack, and remove yourself
☐ Make sure the new Warden is invited to the Cherry Pick and Retro
☐ Invite the next Warden to the next handoff
☐ Review any S0 or S1 bugs that might affect the next release
☐ Note any outstanding bug reports that still need to be triaged

Bugfix Cherry Pick (towards the end of the release cycle)

This meeting is a last chance opportunity to reallocate resources to fixing critical bugs before a release goes out. A product owner is invited so they can help the engineers understand what features are critical to ship in this release, and what issues are critical to fix before they can ship.

Often this is just a rubber stamp, but sometimes there is a critical bug that is blocking a release and at this meeting the team can raise a flag if more resources are needed to squash it.

Invitees: Bug Warden, Release Warden, and a product owner

Checklist:
☐ Quickly review any un-triaged bug reports
☐ Make sure all issues that need to be S1 are tagged as S1 and Fix in the current release
☐ Review all S1 issues to check if they have owners + will be ready for the release
☐ If the release is at risk, post in #releases-and-testing to let the team know what's going on.

Bug Retro (after a release cycle)

The last thing the Bug Warden will do is run a retrospective on some of the issues that came up. You figure out what needs to improve in your release process, testing, tooling, bug reporting, and triage.

This is a crucial feedback loop that drives your software quality up to where it needs to be.

Invitees: The Bug Warden, at least one engineer, a representative of the customer, and a product owner

Checklist:
☐ Choose a couple bugfixes from the release to retro
☐ Run through "5 why's"
☐ Note any action items

The Warden is busy

Although these handful of meetings might only amount to an hour or two per week, the actual bug triage process can take up a LOT of time for the engineer who has that responsibility.

Because of that, we always want to reassure the Bug Warden that their other development work can take a back seat while they occupy this critical role.

And it also means we don't want to assign someone who is under the gun to ship a critical feature as the Bug Warden. If someone is up for the job, and there is higher priority work for them to do, they should swap with someone else!

We can relax

Although it's real work for the engineer doing this job, the real benefit is that everyone can relax because they know someone is responsible for handling bugs.

When they're busy, the other engineers can safely ignore the #bug-reports channel knowing someone will ping them if they're needed.

Management can rest easy knowing that incidents are being investigated and the stability and reliability of the product is getting better every week.

Stakeholders from across your team know exactly where they can fire off a critical bug report to get immediate attention. And they know where to put more minor bug reports without causing a distraction.

In other words: we can all relax knowing the product is solid.

If it's still January 2025, and you are looking for an experienced Engineering Manager in San Francisco or remote... Hire me!

Part of a multi-part part series on "Software Engineering Roles"...

Follow me on LinkedIn or Twitter/X to hear when the next part is posted!

Part 1: Four roles your software team can't function without
Part 2: If you have bugs, you need a Bug Warden
Part 3: How to "own" a project if you're an engineer
Part 4: The Release Warden
Part 5: The Program Manager

Cover image ID 337353589 ©
Minirhenyx | Dreamstime.com

Four Roles Your Software Team Can't Function Without

Erik Pukinskis — Fri, 13 Dec 2024 18:37:31 +0000

We've all seen it go both ways:

Company A: Has no real structure in place, just a bunch of stuff that tends to happen because individuals make it happen.

Company B: Documents structure around everything. Everyone has strictly defined responsibilities. Doing anything across multiple roles requires navigating a byzantine maze of personalities and processes. Because of that, people just focus on their job description and block everything else out.

One of the pieces of feedback I got at Spaero Bio made me incredibly proud. A dev told me: this is the first company I've worked at that struck the right balance between process and freedom.

So let's talk about the structure that a software engineering team can't do without.

Solid engineering, every time

When you look closely at the key contributors at companies in that "Company A" category, you will see passionate people taking responsibility for critical work:

An engineer who was driven to drive out bugs
A tech lead who made sure that estimations were done reliably
A designer who sought out blunt feedback from engineers, business, and sales people
A PM that diligently tracks progress against key product milestones
And so-on...

But in the end, you can't clone these people. And statistically, any given team will be missing some of these passions. All the key skills are represented in your organization, and yet these critical work pieces of "side work" are not done consistently.

I have found that the way to turn a team of productive, passionate engineers into a steady, trusted unit that the entire organization can rely on, is to introduce rotating roles that go beyond the core engineering responsibilities.

"Roles" = people know what today's job is

The foundational role on an engineering team is of course "Engineer". Every engineer knows the basics of what this job entails: You grab some kind of spec, you write the code, and you deploy it.

But left to their own devices, software engineers will run into a number of classic roadblocks:

A smart engineer spends lots of time building beautiful code that wasn't necessary in the first place.
"Trickle requirements" cause expensive rebuilds of the same features over and over again.
Bug reports pile up with Product thinking Engineering will handle it and Engineering thinking Product will handle it.
Releases are going out but the sales team never knows when a feature will go live.
Embarrassing bugs appear during a key demo or customer onboarding.
Projects have "two weeks left"... for two months.

And most of us know some ways to avoid these problems. It's not that we want these things to happen.

The challenge is the typical engineer has so many demands on their time, it's impossible for them to do everything at once.

That's where my four roles come in.

The four roles

👉 If you know you're taking the Release Warden role for the next release, you know to focus on the work that is wrapping up, not upcoming work.

👉 If you are the Epic Owner for an epic that's about to have a kickoff next week, you know to focus on planning that work, not fixing bugs.

👉 If you're Bug Warden for the current release, you know that triaging bug reports quickly takes precedence over finishing that new feature.

👉 If you're the Program Manager you know that shipping is not your first priority. You're make sure information is flowing between stakeholders so the best possible decisions are getting made.

... and if you are not in any of those roles this week, you know that it's the perfect time to be heads down on a project, cranking out that sweet, sweet engineering.

Roles the rest of the organization can trust

I won't pretend these came out of a principled analysis—they didn't.

But they did come out of a decade or two of trial and error... Seeing projects get jammed up, adding process to smooth things out, removing process that was being skipped, refining responsibilities in response to retrospectives, and so-on.

And in hindsight, I think this kind of heavier process works best near key inputs and outputs between Engineering and other parts of the organization:

Inputs to Engineering:

Bug reports (from QA)
Product specifications (from PMs)
Designs (from designers)
Business priorities (from PMs)

Outputs of Engineering:

New features (for QA, Sales)
Bug fixes (for QA)
Roadmaps (for PMs)
Status updates (for Management)
Design feedback (for Designers)

These are moments where some information has been generated that is either going to inform the engineering work, or will inform the decisions the rest of the organization is making around that work.

As few roles as possible, as little process as could work

One final note, on taking in too far...

It can be tempting to just document "all the roles!" and give people a checklist for every situation. But there's a very specific reason why this post is four roles your team can't function without and not ten roles.

If you introduce too much process, it starts to feel very heavy. People start skipping steps, and you lose the whole "trusted unit that the entire organization can rely on" thing.

If you're a senior engineer, or an engineering mananger, or a product manager who is trying to introduce this kind of process to your team, you can only introduce one process step at a time.

Your team needs time to digest these processes. To integrate them into their existing habits. And to begin to trust that 1) they're really necessary, and 2) they're really going to be happening from now on.

There will be areas where your team is limping along, and you know how to fix it, and you don't. Because you are still building trust somewhere else in the process.

Let's do the work

We can talk all day about roles and responsibilities in the abstract. But these are production-oriented roles with very specific things for an engineer to do, and specific things they won't do.

So in the next series of posts, I'll dive into each one of these roles in detail: The decisions that each role gets to make, the meetings that need to happen, the communication that needs to occur.

Follow me on LinkedIn or Twitter/X to hear when the next part is posted!

If it's still January 2025, and you are looking for an experienced Engineering Manager in San Francisco or remote... Hire me!

Part of a multi-part part series on "Software Engineering Roles"...

Follow me on LinkedIn or Twitter/X to hear when the next part is posted!

Part 1: Four roles your software team can't function without
Part 2: If you have bugs, you need a Bug Warden
Part 3: How to "own" a project if you're an engineer
Part 4: The Release Warden
Part 5: The Program Manager

What is a Pro Web Engineer?

Erik Pukinskis — Tue, 13 Aug 2024 16:00:25 +0000

Terms like "professional" and "engineer" are bandied about in the software world. A lot of us are engineers by title, and most of us would like to think of ourselves as professional.

But what do these two words really mean?

I think the answer to that question can help you understand how to proceed in lots of tricky work situations:

Should I be cutting corners on the quality of my work?
Is it OK to express strong emotions in the workplace?
When can I get my way?
When do I compromise?

This blog will lay out what it means to be both "professional" and an "engineer" for those of us building software for the web.

We'll go into detail on each of these, but at a high level here's what I think makes for a professional web engineer...

An engineer:

Knows the materials — You understand the properties of different materials, tools, and patterns, and can choose options which are fit to purpose.
Documents the decisions — Numbers are crunched and shared, reasons for decisions are made clear. Available tradeoffs are presented.
Works within a code of ethics — You don't design a bridge you think is dangerous.

A professional:

Is efficient — You don't waste your time, and you don't waste other peoples' time.
Is accountable — When you screw up, you make it right.
Works well with different kinds of people — You don't just have one specific kind of person you can work with. You do the work to allow folks from many backgrounds to be comfortable working with you.

The web:

Is whatever software you can deliver in a web browser.

Follow @erikpuk on Twitter to follow as we learn how each of these goals plays out in practice.

Image credit: Dave Lauretti

Big, scary, and ignored: Are backlogs even worth it?

Erik Pukinskis — Fri, 15 Sep 2023 22:28:12 +0000

Let's start with some observations about backlogs:

1. Backlogs Want To Be Scary

Maybe we'll call that the "Halloween Law of Backlogs". A backlog's favorite day of the year is Halloween.

To understand why, let's think about the reasons you'd put something into a backlog:

It's not strictly necessary to hit your immediate goals
You're not sure how it should be designed
It's a "big bite" and not quite ready to be a Story
It's been requested by one user, and you're not sure how broadly useful it is

All of those things are scary.

On the flip side of that, there are some tasks which are not scary at all:

It's clearly necessary
You know how to design it
It's a "small bite"
It's going to be useful to many users

Those kinds of tasks don't get dumped in a backlog, they go into production. Everyone is aligned on those kinds of tasks.

So a backlog is made of at least semi-scary items. But one additional factor makes backlogs very scary:

2. Backlogs Want To Be BIG

It's a lot faster to add something to a backlog than it is to remove it.

Removing it requires either A) deleting it, which might be disappointing to a user, disappointing to one of your colleagues, or disappointing to you. Deleting backlog items often requires some conversation and hand-wringing.

Or, B) moving the item into production. That requires overcoming the scary reasons the item was put in the backlog in the first place, and marshaling resources to get it done.

So backlogs want grow and grow.

3. Backlogs Want To Be Ignored

By design, they are where tasks go to avoid distracting the team. They live in a corner of your workspace that few people visit. It's not a Kanban Board that people are seeing every day. It's not on a Google Calendar, or in a list of Pull Requests.

Backlogs want to have as few eyes on them as possible. That's their job.

The big, scary, important thing you've been ignoring

And yet, we wouldn't put things in a backlog if they weren't important. But that just makes backlogs even scarier.

The big, scary, important thing we've all been ignoring.

What are backlogs useful for

It's worthwhile considering how a backlog can function in the product development pipeline.

In Scrum, the place a backlog would be used is for CREATE PROJECT VISION. That's the place where you are considering all the potential projects you might invest in, looking at the business case, marketing, costs and profits, etc.

That points us at some interesting criteria for what makes a good backlog:

What makes a good backlog

1. Ideal backlog items address the business case, marketing, and costs and profits behind the work

These are the things you'll be thinking about when you are reviewing your backlog so they should be the things you document when deciding an item should go in there.

If any of these concerns are obvious misses, don't put it in the backlog.

And speaking of not putting things in the backlog...

2. Don't put things in the backlog you won't do soon

Since Backlogs Want To Be BIG, and a big backlog is more difficult to review, it's important to find ways to keep your backlog small.

An easy rule is "If you don't think you'll get to it this quarter or next, don't put it in the backlog".

3. Delete backlog items mercilessly

Understand that it's going to hurt. If it was truly unimportant, it never would've landed in your backlog in the first place. So know that you're going to be deleting important things out of your backlog.

One thing to keep in mind which can make this easier is...

The Boomerang Rule

Important things will come back to you.

If something is truly a broad concern for many of your colleagues, or many of your users, someone will mention it again.

And eventually someone will mention it in a less scary time, when

It's clearer how necessary it is
You have a better sense of how design it
You can see a "smaller bite" to take
More users have made it clear they need it

So, as important as it is today, remember that the important stuff will only get importanter.

The Small, Helpful, Important Thing You Keep Tabs On

With just those few small changes to your workflow, your backlog can transform from the Big, Scary, Important Thing You've Been Ignoring to something you actually want to keep tabs on.

If you are careful about adding things, brazen about removing them, and stay focused on backlog items that contribute to your project vision, hopefully your backlog will be something folks want to spend time in.

The Persistent Test Factory Pattern

Erik Pukinskis — Thu, 20 Jul 2023 04:06:58 +0000

I've worked on many codebases that used what I consider to be one of the worst patterns in automated test architecture:

Fixtures.

Yuck.

Fixtures are a set of statically defined objects which might be injected into your database during your test run, or might just be passed to various functions in your tests. They'll either be raw .json files, or they could be defined in code, looking something like this:

export const REPOS = [
  {
    id: "1",
    slug: "use-firestore",
    starCount: 100,
    owner: "erikpukinskis",
  },
  {
    id: "1",
    slug: "codedocs",
    starCount: 0,
    owner: "erikpukinskis",
  }
]

They will often be associated with one another, so that when they're injected into your database there will be some referential integrity. So in the example above we might also have fixtures like:

export const USERS = [
  {
    id: "1",
    username: "erikpukinskis",
  }
]

The problem is these fixtures will tend to be used to set up many different tests. And so the fixture suite gets bigger and bigger, with lots of relationships between fixtures. It either gets really complicated to get the database into a "good" state, or you end up with a function like this:

import { setUpAllTheThings } from "~/test/helpers"

describe("my new test suite", () => {
  beforeAll(async () => {
    await setUpAllTheThings()
  })
})

That's easy enough, but it misses out on one of the Properties of a Good Test:

A Good Test describes its preconditions
A Good Test describes its expectations
A Good Test only fails when things are broken

The problem with setUpAllTheThings() is it doesn't tell you what the conditions for success were. It just gestures at a big pile of fixtures that you have to dig through and guess what was important.

The solution

Instead of static fixtures, your data-dependent tests should use functions called factories. Over the years I have come to identify some important features for great test factories.

This post will teach you those patterns in three parts:

What makes a factory
What my factory functions look like
Additional factory patterns I love

What makes a factory?

1. Factories are imperative

Unlike "fixtures" which are set up once, globally for all tests, factories are called imperatively during test setup:

import * as factory from "~/test/factory"

test("should render a repo heading", async () => { 
  const { repo } = await factory.setUpRepo(testApp)

  const { findByRole } = render(<Repo id={repo.id} />)

  await findByRole("heading", repo.name)
})

This means that your test can specify the smallest number of records that need to be set up for the test to work. When the test fails, you can immediately see what the specific conditions being tested were, eliminating a bunch of guesswork.

2. You can override everything in a factory

When you use record from a test fixture, it has every single field set. It also probably has every possible association specified. And so it's never clear which fields or associations are required for the test to make sense.

With factories, you can specify exactly which fields are preconditions for the test's success:

This lets us make a small improvement on the test above, making it more explicit that we're testing a repo with a specific name:

import * as factory from "~/test/factory"

test("should render a repo heading", async () => { 
  const { repo } = await factory.setUpRepo(testApp, {
    name: "My Test Repo"
  })

  const { findByRole } = render(<Repo id={repo.id} />)

  await findByRole("heading","My Test Repo)
})

3. Factories auto-generate associations

One of the key jobs of a factory is to ensure data consistency by creating any and all associations needed for the database schema to be happy.

This allows you to specify only the objects needed for your test preconditions without having to bootstrap a bunch of context:

import { User } from "~/server/data"

test("repos should have owners", async () => { 
  const { repo, owner } = await factory.setUpRepo(testApp)

  expect(owner).toBeInstanceOf(User)
  expect(repo.ownerId).toBe(owner.id)
})

This gives you all the ease-of-use of a giant setUpAllTheThings() function, without over-specifying your preconditions.

Factories let you override associations

But even better, factories can pick and choose when to do automatic setup and when to set up relations manually.

For example, you might want to test some aspects of how repos and and users work together. The setUpRepo factory can automatically create a user for you, but if your test depends on a user with some specific traits you can also do it yourself:

test("only owners can see repo details", async () => { 
  const { user: owner } = await factory.setUpUser(testApp)
  const { user: otherUser } = await factory.setUpUser(testApp)

  const { repo } = await factory.setUpRepo(testApp, {
    owner,
    name: "My Test Repo",
  })

  const { findByRole, queryByRole, findByText, rerender } = render(
    <SignInProvider userId={owner.id}>
      <Repo id={repo.id} />
    </SignInProvider>
  )

  await findByRole("heading", "My Test Repo")

  rerender(
    <SignInProvider userId={otherUser.id}>
      <Repo id={repo.id} />
    </SignInProvider>
  )

  await findByRole("heading", "404 Not Found")
  expect(queryByRole("heading", "My Test Repo")).toBe(null)
})

All of this is in service of the same goal: Tests with explicit preconditions.

What my factory functions look like

This is the typical pattern I use for setting up a factory:

export type Repo = {
  id: string
  slug: string
  starCount: number
  tagIds: string[]
  ownerId: string
}

let repoCount = 0

type RepoOverrides = Omit<Partial<Repo>, "id"> & {
  owner?: User
}

export async function setUpRepo(
  app: FirebaseApp,
  overrides: RepoOverrides = {}
) {
  // It's useful to number the calls to the factory, to have a unique identifier
  // that also indicates the order of creation:
  const uniqueId = ++repoCount

  // Split out the associations from the object properties:
  let { owner, ...propertyOverrides } = overrides

  // Create any associations that are missing:
  if (!owner) {
    owner = await setUpUser()
  }

  // Now create the primary object
  const ref = await addDoc(collection(getFirestore(app), "repos"), {
    // Provide fallback values:
    slug: `repo-${uniqueId}`,
    starCount: 0,
    tagIds: [],

    // Then the overrides from the user:
    ...propertyOverrides,

    // And lastly any associations:
    ownerId: owner.id,
  })

  const repo = {
    id: ref.id,
    ...propertyOverrides,
  } as Repo

  // Finally, return the primary object along with all of its assocations
  return { repo, owner }
}

And that's it. You can build out a large factory system using just those few patterns.

I don't tend to use factory libraries like Fishery. That's a great library, but I don't find it saves much code.

Additional factory patterns I love

Factories should return a set of associated objects

Sometimes folks will set up factories to return just a single object, or maybe an object with a bunch of associations attached to it.

Because "factories auto-generate associations", I recommend returning all of the associations along with the primary object. This allows you use those associations elsewhere in your test:


test("can navigate to repos path", async () => { 
  const { repo, owner } = await factory.setUpRepo(testApp, {
    name: "My Test Repo"
  })

  await signInAs(owner.email, owner.password)
  await goToPage(`/repos/${repo.id}`)

  expect(screen).toHaveRole("heading", "My Test Repo")
})

Conclusion

A solid set of test factories can really accelerate your team in a few ways:

First, they speed up debugging time when tests fail. They make it super clear what scenario is under test, which helps developers spend less time trying to understand a test failure.

Second, they make it much easier to bang out new tests. This gives you better coverage which usually means more stability in your code. It also makes developers more likely to delete obsolete tests, since they know it'll be easy to add back the correct ones.

And lastly, factories reduce the dependencies between tests, which means less time playing whack-a-mole when you change a fixture to get one test to pass, and it breaks another test.

How to spy on a third party ES6 export in Vitest

Erik Pukinskis — Mon, 26 Jun 2023 05:31:43 +0000

This was a bit of a tricky one, and the solution from the Vitest docs didn't work for me.

Those docs suggested that I could do something like:

import * as Firestore from "firebase/firestore"
import { vi } from "vitest"

const onSnapshot = vi.spyOn(Firestore, "onSnapshot")
...
expect(onSnapshot).toHaveBeenCalled()

but that didn't work, Vitest complains that it can't redefine that propery:

TypeError: Cannot redefine property: onSnapshot
 ❯ lib/useDoc.test.ts:12:4
     10| import type { Repo } from "~/test/helpers/factory"
     11| 
     12| vi.spyOn(Firestore, "onSnapshot")

The solution

The answer wasn't too bad, but there are actually three steps:

1) Mock the import
2) Import the module in your test
3) Create the spy

Let's walk through each of those.

1) Mock the import

At the top level of my test file you need to mock the import using vi.mock. In the factory you feed to vi.mock you will replace the function you want to spy on with with a vi.fn:

type FakeFirestore = { onSnapshot(this: void): void }

vi.mock("firebase/firestore", async (getModule) => {
  const original: FakeFirestore = await getModule()

  return {
    ...original,
    onSnapshot: vi.fn().mockImplementation(original.onSnapshot),
  }
})

Note that very useful importOriginal function which lets me keep the Firestore module fully functional. This is because vi.mock is really persnickety about referencing outside variables.

That factory function needs to be 100% self contained. Therefore you have to...

2) Import the module in your test

In order to have something to spy on, you'll need to import that same module directly in your test. This should be the mock object that you returned in your factory above, with the vi.fn where you stuck it. That'll give us something to spy on...

import * as Firestore from "firebase/firestore"

3) Create the spy

Finally, we can create the spy, and place our expectations on it:

import { test, vi } from "vitest"

test("calls onSnapshot", () => {
  const onSnapshot = vi.spyOn(Firestore, "onSnapshot")

  /* trigger the onSnapshot call here in my code */

  expect(onSnapshot).toHaveBeenCalled()
})

And that's it! My test passes.

Check out the complete source code here.

Follow me on Twitter if you want to see more Vite, Vitest, and Firestore tips!

The best way to initialize a React Context in TypeScript

Erik Pukinskis — Wed, 14 Jun 2023 01:13:46 +0000

React Contexts are great—they let you neatly encapsulate behavior that cuts across multiple React components.

But there are a few gotchas when using them in TypeScript.

This article will explain how to deal with one.

TL;DR

You can't easily initialize a React Context if it has required properties. Because you won't know what those properties are when you call createContext.

My makeUninitializedContext gist solves that.

The Problem

A common pattern when using React Contexts is to pass some props into your Context Provider. For example, if your app has dark mode and a light mode, your design system provider might have a theme prop:

import { DesignSystemProvider } from "~/design-system"
import { useState, useEffect, createContext } from "react"

type DesignSystemContextValue = {
  theme: "light" | "dark"
}

const DesignSystemContext = createContext(
  /* what goes here??? */
)

function App() {
  const [theme, setTheme] = useState<"dark" | "light" | undefined>()

  useEffect(() => {
    const listener = (event: MediaQueryListEvent) => {
      setTheme(event.matches ? "dark" : "light")
    }

    const query = window.matchMedia("(prefers-color-scheme: dark)")

    query.addEventListener("change", listener)

    return () => query.removeEventListener("change", listener)
  }, [])

  if (!theme) return null

  return <DesignSystemProvider theme={theme} />
}

The trouble is, how do you then initialize your context? It's easy if you can use a default value...

import { createContext } from "react"

const DesignSystemContext = createContext({
  theme: "light",
})

... but ...

What if you don't want a default value?

What if you want to test that your hooks behave a certain way when used outside the Context Provider?

What if your Context Provider depends on data objects that have no sane default value, like a user or a workspace?

If you try to create a context with an uninitialized object, TypeScript will yell at you:

The Solution

The way I solve this is by including a small snippet of code in almost every React project I work on, called makeUninitializedContext.

The makeUninitializedContext function returns a Proxy object that is typed with whatever type you want:

import { createContext } from "react"
import { makeUninitializedContext } from "~/helpers"

type DesignSystemContextValue = {
  theme: "dark" | "light"
}

const DesignSystemContext = createContext(
  makeUninitializedContext<DesignSystemContextValue>("Cannot use DesignSystemContext outside a DesignSystemProvider")
)

That gives you a Context object which is properly typed...

... and if you try to use the context object without initializing it, you get a helpful error:

Making the context optional

Sometimes you have a hook that can work in either of two ways: with or without the context.

For that case, I use the isInitialized function exported in that same gist. It allows you to detect whether a context is initialized before you try to use it:

import { useContext } from "react"
import { isInitialized } from "~/helpers"

export function useThemeName() {
  const context = useContext(DesignSystemContext)

  return isInitialized(context) ? context.theme : undefined
}

That way your hook can work either inside or outside of the Context Provider. And you won't trigger an error by accessing a property on the uninitialized context object.

I hope that's helpful for someone! Follow me on Twitter for more React tips.