A place for me to write about software and other things.

Ryan J. Wessel

Codesigning for iOS Explained Simply


There have been plenty of occasions where I have encountered cryptic error
messages in `xcodebuild` scripts. Sometimes, those error messages were a result
of the app not being signed.

I wasn't familiar with the concept of signing apps at the time, and I found it
difficult to find simple explanations of what a lot of the terms meant for iOS
development. So, this post is my attempt at explaining some core concepts
simply, so that you and I can refer back to them easily in the future.

## What Is Codesigning?

Signing your code does two things:

1. The app your users install came from you (or another developer on your team)
   - This is referred to as the **"code signature"**
2. That your app's code has not been tampered with since you (or your team)
   built it
   - This is referred to as the **"code seal"**

If a malicious actor tampered with your app between the time you built it, and
the time a user attempts to install it, then the app will not install or launch.

Codesigning protects your users from installing apps that intend to do them
harm. Here's a quote about it from the WWDC17 presentation,
_[What's New In Signing for Xcode and Xcode Server](https://developer.apple.com/videos/play/wwdc2017/403/)_.

> "Why do we code sign? Well, the simple answer is that code signing protects
> us. It protects us as users, it protects us as developers.
>
> And all of us are users. All of us download apps from the store, and we're
> sure that, that app came from the developer that wrote it, because of code
> signing. And every app that we download from the store, we're sure that Apple
> has approved that, that app is allowed to use special system services.
>
> We can trust the security and the privacy of our devices because of code
> signing."
>
> - Chris D'Angelo: Xcode Engineer at Apple

## What Do You Need To Sign Your App?

There are 3 things you will always need to sign your app:

1. A signing certificate
2. A provisioning profile
3. Your App's Entitlements

The signing certificate establishes your identity as a developer.

The provisioning profile grants permissions for your app. It allows access to
Entitlements, and allows access to run on certain devices depending on the
signing certificate.

Entitlements are used to define supported capabilities, like iCloud or Wallet
functionality.

Setting up your provisioning profile and signing certificates for your app
warrants a separate post, but here is a screenshot of where you are able to
select your provisioning profile in the signing & Capabilities pane in
Xcode@12.4.

![Xcode Signing & Capabilities Pane](../automatic-xcode-signing-example.png)

## What Types of Signing Certificates Are There?

There are a few signing certificates that are used in different contexts. It
depends on how you want to distribute your app at that time.

- Development certificate
- Distribution certificate

A development certificate would be used if you are building and running on a
simulator.

A distribution certificate would be used when you are deploying your app to
devices. There are a few types of distribution signing types depending on your
use-case.

- If you want to distribute your app to TestFlight or the App Store, you would
  sign your app with an **Apple Developer Program** distribution provisioning
  profile.
- If you want to distribute your app to testers with registered devices, you
  would use an **Ad hoc** provisioning profile.
- If you want to distribute your app to users within your organization, you
  would sign your app with a **Developer Enterprise Program** distribution
  provisioning profile.
- If you only want to distribute your app to users within your Apple Developer
  Program team, you would sign your app with a development provisioning profile.

To simplify, an app distributed to the App Store is provisioned to run on any
device, whereas the other distribution types are provisioned to run on a
specific set of devices.

## What Is The Codesigning Process When Deploying?

When you're ready to share your app, you need to build an archive. An archive is
a special release build of your app.

When you build it, you would use a development certificate. That way, any
developer on your team can easily build an archive without requiring a special
distribution certificate.

Once you've built the archive and begin the distribution process, Xcode will
sign those archives with the distribution certificate.

## Questions I Haven't Answered In This Post

This topic can be lengthy, and I wanted this post to be specific to explaining
some terminology related to codesigning on iOS.

Here are some of the topics that I did not cover in this post:

- How Do I Set Up Certificates and Provisioning Profiles?
- What is App Store Connect?
- How Do I Manage Signing and Distribution in Xcode?

If you liked this post, and would like to learn more about some of these topics,
please [tweet at me](https://twitter.com/ryanjwessel). I would love to hear if
this post was helpful, and would be happy to answer any questions you may have.

### References

I based most of this article on these resources. If you'd like to dive deeper,
these may be good places to start.

- [What's new in Xcode App Signing (WWDC16)](https://developer.apple.com/videos/play/wwdc2016/401/)
- [What's New In Signing for Xcode and Xcode Server (WWDC17)](https://developer.apple.com/videos/play/wwdc2017/403/)
- [Xcode Distribution Overview](https://help.apple.com/xcode/mac/current/#/devac02c5ab8)


What Is Serialization?


I often get confused when trying to remember the difference between
serialization and deserialization. In this post, I will try to explain it in a
simple, easy-to-remember way.

**Serialization** is the process of translating data into a format that can be
stored or transmitted with the ability to reconstruct that data later.

The opposite of this is called **deserialization**. So, translating serialized
data back into a clone of the original object.

Often, the format of serialized data is a stream of bytes. This allows the data
to be reconstructed (aka deserialized) in other environments that may not have
the same capabilities as the system where the data was originally serialized.

This concept is applicable to all programming languages. Here are some examples
to help solidify your understanding.

## An Example in Java

If you work in Java, you may be familiar with the
[Gson](https://github.com/google/gson) library. This is a Java
serialization/deserialization library built by Google. It provides two methods
that allow you to serialize or deserialize data, `toJson()` and `fromJson()`.

When you call `toJson()`, you are **serializing** a Java object into a JSON
object.

When you call `fromJson()`, you are **deserializing** a JSON object back into a
Java object.

So, deserialization is reconstructing data in a format that is usable in the
current context.

## An Example in Javascript

If you have used `JSON.parse()` or `JSON.stringify()` before, then
congratulations! You are familiar with this concept in Javascript.

When you call `JSON.stringify()`, you are **serializing** the data.

When you call `JSON.parse()`, you are **deserializing** the data to be used as
an object.


Getting Things Done: An Overview


Throughout 2020, I have been reading David Allen’s book, _Getting Things Done_
(also known as GTD), and gradually applying pieces of the system to my life. I
just finished the book last month, so I would like to outline some of the most
important lessons I have derived from the book.

Before I begin, I just want to clarify that you don’t need to read this and put
every piece of it in action right away. Part of the beauty of the GTD system is
that you can apply pieces of it in stages. Likely, you will be better off trying
one or two things at a time first before you add onto your system. As I explain
some of the fundamental parts of the system, I will call out which ones make the
most sense to start implementing first.

Ultimately, the purpose of GTD is to assist you in aligning your effort with
your higher-level thinking. Wouldn’t it be great if you could consistently
finish the goals that you set for yourself? As you continue applying pieces of
GTD, you will find yourself more effective at making progress on these
bigger-picture initiatives.

## Capture: Documenting All Of Your Open Loops

An open loop is anything that has a piece of your attention at any time. Your
mind is an incredible idea-generating machine, but it is not the best at
remembering those ideas when they are most relevant.

For example, you might note that you need AA batteries because your TV remote is
dead. The only time you would need to remember that is when you are out running
errands. However, the mind has a funny way of remembering things. That thought
might pop up as soon as your head hits the pillow, but you are likely not going
to make a trip to CVS when you’re about to fall asleep.

I have found this to be the best place to start with GTD. Early on, capture
_anything_ that has your attention in a centralized location. David Allen refers
to this as the “In Tray,” but for more digitally-inclined people like myself, it
can be called the Inbox. Apps like Todoist, TickTick, or even the iOS Reminders
app, are great tools for this. Capturing all of your open loops is the first
step in developing a system your mind can trust to contain all of your ideas and
obligations effectively.

Once you have all of those items in your Inbox, what do you do with them? That
leads us to the next stage — clarification.

## Clarify: Next Action Decision-Making

At this stage, you need to go through each item in your Inbox, define a clear,
achievable outcome, and then determine what the next action is that can move you
closer to that outcome.

After you have captured every open loop in your Inbox, one of those captured
loops might look like this:

> - “Write an article about GTD.”

When I see this item and think about the next actions I can take to move it
forward, it might look something like this:

> - “Create an outline for the GTD Overview article.”
> - “Write the first draft for the GTD Overview article.”
> - “Proofread the first draft.”
> - “Publish the article to my website.”

In this example, there are multiple actions associated with that Inbox item.
Because it has more than one step, you would classify this as a **Project**
(more on that in the next section).

What I have found to be an essential part of this stage is thinking in the next
action mindset. Ask yourself, “What is something that I can do to move this
forward (or complete it) right now?”

Often, when you capture something in your Inbox, you are just writing it down to
get it out of your head and into your system. Most of the time, your Inbox items
won’t have a clear outcome with a specific action. This stage is focused
exclusively on that.

Next action thinking is a skill that takes time to develop. You can start trying
this today, but I still find unclear outcomes on some of my lists. Like any
skill, it takes time and effort to improve.

To be honest, I often blur the lines between this stage (clarification), and the
next one (organization). Usually, you would do both of them right after each
other as you process each item in your Inbox.

## Organize: Put Everything Into The Right Lists

GTD has a specific workflow for determining where an item should go based on a
series of questions:

- Is this actionable?
- Will it take multiple steps to complete?
- Will it take more than 2 minutes to complete?
- Is this a task for someone else to complete?
- Is there a specific date or time associated with this action?

This step may seem daunting to go through for every item in your Inbox, but the
process becomes more natural as you get used to it. I’ll do my best to step
through the workflow succinctly.

Maybe you wrote down an idea like _“make an app for buffalo chicken sandwich
reviews.”_ You know this is a brilliant idea, but you also know that you can’t
take action on it right this second. In this case, you would put this item in
the **Someday/Maybe** list.

If the next item was a copy of the warranty for your new TV, then that isn’t
something you can take action on. But, you will want that to be easily
accessible if the TV has any issues. Something like this goes in your
**Reference** list.

Perhaps the item is not something you find important at all. In that case, throw
it in the **Trash**!

If there are multiple actions associated with an item, then it should be made
into a **Project** list.

If something takes less than two minutes to do, then you should just do it now!

If the next action is something someone else has to do, then that item would go
in the **Waiting** list. You should set reminders on these items, so you know
when the appropriate time is to follow-up.

If there is a specific date or time associated with an action, then it should go
in your **Calendar**. Do not assign arbitrary dates to actions! The Calendar
should be a sacred space that reflects only your time-based commitments.

If an item has not satisfied any of these steps, then it should go on a generic
**Next Actions** list.

The structure of your lists might look something like this once you finish
organizing:

- Inbox
- Projects
  - Write the GTD Overview Article
  - Plan trip to Rhode Island
- Next Actions
- Someday/Maybe
- Waiting
- Reference

Typically, you would maintain your Calendar in a separate system. Currently, I
use Google Calendar for my date-based commitments, Bear for my Reference list,
and TickTick for everything else.

Ultimately, the point of this stage is that all of the open loops in your life
are easily accessible when they are relevant. So, if a slightly different
organization setup makes sense for you, then go for it.

My setup is slightly different in that I use TickTick’s tagging functionality
for **Waiting**. That way, tasks can stay within their Projects, and I still
have visibility for all delegated work.

Another organizational concept I have found useful is **Agendas**, which are
points to remember the next time you speak with someone. I maintain a separate
list for Agendas, and I apply person-specific tags to those items so I can find
them easily.

In the beginning, I think these are the two most important things to remember:

- Treat your calendar as sacred. Don’t assign arbitrary dates. Your schedule
  should encapsulate all time-sensitive tasks.
- Ensure that you define your Projects as clearly achievable outcomes.
  Next-action thinking is not limited to actions!

At first, try applying the concepts of Projects to your work, and see how that
goes. You can always add these other lists as a need for them arises.

## Engage: Taking Action Based On Context

David Allen defines three models for how we choose what to work on, and ensuring
that our work aligns with our desired life trajectory.

### The Four Criteria Model For Decision-Making In The Moment

First, the four criteria model is used to decide what to take action on at any
given moment. This model makes the most sense to implement early on in your GTD
journey, and your Organizational work in the previous stage will fuel it. The
four criteria for choosing what to work on are the following:

1. Context (Tools, People, Location, etc.)
2. Time
3. Energy
4. Priority

If you don’t have a computer with you, then you can’t take action on something
that requires a laptop. Similarly, if you need to be in the office for
something, then it can only be done if you are in the office.

If you only have twenty minutes before your next meeting, then it doesn’t make
sense to pick up a task that requires more time than that. But, perhaps you
could complete a few smaller tasks in that window.

There are times where you feel like you can crush any task that is on your
plate. But, there are also times where you feel lethargic, and you know you
would not be able to sustain long periods of concentration. In those low-energy
states, attempting to barrel through a task that requires deep focus will likely
result in lackluster work. Instead, you can complete some more manageable tasks
for quick wins.

If you have multiple options after whittling them down based on the previous
criteria, then it makes sense to gauge your decision based on what is the
highest priority. Priority can be subjective, which is why it is the last
criteria.

If your productivity software has a tagging or labeling system, this is where it
will shine. During your clarification and organization stages, assign context,
time, and energy labels to your tasks when appropriate. Then, you will be able
to view all of your available work by these criteria and make the best decision
for what to do at any moment.

### The Threefold Model For Evaluating Your Daily Work

Each day, your work will fall under one of these three categories:

- Doing predefined work
- Doing work that comes up in the moment
- Defining future work

Often, obligations that come up in the moment consume most of our day-to-day
(aka “urgent” work). We mustn’t let the other two categories fall by the wayside
because they often align with our goals and visions for our future.

The desired outcome of GTD is that you can be comfortable with deciding between
these three categories. When you have a trusted system that encapsulates all of
your obligations, and it’s organization allows you to assess that landscape,
then you are equipped to make an informed decision that makes the best use of
your time.

### The Six-level Model For Reviewing Your Vertical Alignment

Lastly, the six-level model helps you assess the alignment of your work compared
to the purpose, vision, and goals in your life. David Allen refers to them as
the _Horizons of Focus_, and they look something like this:

- Horizon 5: Purpose & Principles (The “Why”)
- Horizon 4: Three to five-year visions
- Horizon 3: One to two-year goals
- Horizon 2: Areas of Focus and Responsibility
- Horizon 1: Current Projects
- Ground Level: Current Actions & Calendar

Think about the work you have put effort into recently. Did some of that effort
align with your vision of where you want to be in five years? If the answer to
that question is not satisfactory, then you need to identify how you can
transition your projects and actions to move in that direction.

Practically, it makes sense to get the current levels under control first
(actions, projects, areas of focus) before actively defining your future
horizons (goals, visions, and principles). Once you have those under control and
you are not thinking of open loops, then your mind is free to think about the
future more deeply.

To get to this point, you will need to employ the single most crucial part of
the GTD system: the Review.

## Review: The Cornerstone Of GTD

The purpose of the review process is twofold — to ensure you can continue to
trust in your system and to help you engage in higher-level reflection on your
goals, vision, and principles.

I have referred to “your trusted system” several times in this article. What
does trust even mean in the context of productivity?

Trust is feeling comfortable with what you are doing, and what you are not
doing, at any given time. It means having an awareness of everything else that
you have to do, but recognizing that what you are focusing on is the best use of
your time right now. This level of trust is only possible when you have a system
that contains all of your current obligations, and that system is continually
kept up-to-date and organized.

If you don’t discard items that are no longer relevant, or archive completed
Projects, then your system will slowly transform into the equivalent of a
daunting, disorganized pile of papers that are sitting on your desk. The Review
process is your mechanism for keeping the system up-to-date and clear of
clutter.

There are different levels of reviews that happen at varying frequencies, and I
will walk through my rituals from most to least frequent.

Multiple times a day, I decide what task to take action on. I use my current
context to make that decision and assess the available work on my lists. I may
notice an item was already completed and mark it as done. Something may come up
as an open loop, so I document it in my Inbox for future filing. All of this can
be considered a micro-review.

Often, during the week, I am caught up in my day-to-day work, and cannot keep
the entire system up-to-date. The single most important GTD ritual solves this
problem — the Weekly Review.

Once a week, I set aside half an hour in a quiet, comfortable setting. Often, I
start my Sunday with a cup of coffee, some light music, and my iPad. I have
three goals for this session: get clear, get current, and get creative.

Getting clear means that each item in my Inbox has been clarified and organized
appropriately and that every item reflects its current status. If something is
completed, mark it as done. If something is no longer relevant, then put it in
the trash. And so on.

Getting current entails reviewing the actions and events from the previous week
and what is coming up in the next week. Sometimes, when I see an item a second
time, it reminds me of some other action that needs to take place. If so, I
capture it, clarify it, and organize it. This ensures that I am following up
when necessary, and preparing appropriately for the week ahead.

Getting creative comes as a result of being clear and current. This is a fun
part of the process. Ideas like “take an illustration course,” “plan a trip to a
national park,” or anything else that captures your interest should be captured
in your Someday/Maybe list.

Lastly, I also have Monthly and Quarterly Reviews. During these sessions, I
assess the progress I have made on my quarterly goals, and create follow-up
actions to get myself back on-track if needed. At the beginning of each quarter,
I reflect on the previous quarter, and set goals for the new quarter. Sometimes,
I will check in on my Vision and Purpose Horizons. These sessions typically take
about an hour.

What is important is that you keep your system up-to-date, and reflect on your
higher horizons occassionally to ensure you are moving in the direction you want
in life.

## GTD: An Integrated Life-Management System

Technology can simplify a lot of things, but it can also overwhelm us with
information and connectivity. At first, I viewed GTD as a method to relieve my
mind from tracking all of the information I receive on a daily basis. That is
certainly one benefit, but over time it has become clear that it is so much more
than that.

I have always been one to pick up new things, or to start an ambitious goal.
But, I will be the first to admit that I often lose that initial enthusiasm and
don’t see these goals through to completion. Defining a vision for my future,
and aligning my goals to that vision, has fueled these goals with purpose.

After reading this article, I hope you can see how the Getting Things Done
system can help align your work with your larger aspirations. If you found this
helpful, or if you have any questions, please
[tweet at me](https://twitter.com/ryanjwessel) and I would love to hear from
you!


Building the Perfect Software for Getting Things Done


At the beginning of 2020, I started reading David Allen's _Getting Things Done_,
commonly known as GTD. The lessons I have distilled from this book have helped
me balance the work from my job, staying in touch with family and friends, and
completing side projects.

Evidence of that is this website. You are reading this post because of the
benefits of the GTD system.

Those that know me would say I tend to experiment with software, and I am always
seeking "the ideal setup." In my quest to implement GTD this year, I have
migrated my system between Todoist, Bear, Notion, Calendars 5, Google Calendar,
Trello, and Evernote. They are all good at a few particular things, but I was
not completely satisfied with what I was hoping to accomplish.

So, I have decided that I am going to build the software that satisfies my
needs. Hopefully, this tool will enable other people to implement the GTD system
effectively in their own lives. Also, documenting progress on this blog will
serve as a guide to the product life cycle, from ideation and iteration to
deploying it in the wild.

Without further adieu, let's go through the requirements I have compiled for the
ideal GTD productivity software.

## Mobile-first

A fundamental tenet of GTD is capturing all of your "open loops" in a trusted
system. If functionality is only available on the desktop app, then it is
incapable of serving as the trusted source of truth for those actions.

Thus, we need to build this software with mobile as our foundational experience.

## Kanban

Humans are bad at multi-tasking. You may think you are, but
[science suggests otherwise](https://www.npr.org/templates/story/story.php?storyId=95256794).

Another tenet of GTD is feeling comfortable with your current action and feeling
comfortable with what you are not taking action on at this moment. The Kanban
concept of limiting Work-In-Progress aligns with this principle. If you're
interested in learning more about Kanban,
[here is a brief introduction](https://www.agilealliance.org/glossary/kanban/#q=~%28infinite~false~filters~%28posttype~%28~'page~'post~'aa_book~'aa_event_session~'aa_experience_report~'aa_glossary~'aa_research_paper~'aa_video%29~tags~%28~'kanban%29%29~searchterm~'~sort~false~sortdirection~'asc~page~1%29).

Also, since I work in the field of software, I am used to the Kanban workflow.
Keeping my productivity system aligned with my professional workflow will limit
any cognitive overhead when switching between them.

Implementing Kanban means our application would need to support:

- Board(s)
- List(s) on each Board
- Card(s) on each List
- Each List can have a defined Card limit

## Context-Driven

Defining priorities for your actions is a discouraged practice within GTD, as is
setting arbitrary due dates. Instead, Allen suggests you should review your
actions based on your current context.

For example, do you have a laptop with an internet connection right now, or are
you on the go? You cannot do the tasks that require a computer if you do not
have one at this moment. But, if you have some time to make some calls, it would
be helpful to view all of your planned calls in one place. Tagging your actions
based on contexts allows you to make effective use of your time in any
situation.

Therefore, to make context-based decisions on our actions, we will need to add a
tagging system to our application.

## Vertical Alignment

The intent of GTD is not just mindlessly marking items as complete. Instead, it
should help you align your work with your Purpose, Vision, and Goals.

![Horizons of Focus Diagram](../diagrams/horizons-of-focus.drawio.svg)

Actions could be a part of a Project. A Project should align with an Area of
Focus in your life. Your Goals should align with your Vision of where you want
to be in five years.

Therefore, our application will need to support parent-child relationships
between cards.

## Reviewable

The Weekly Review is another fundamental pillar of the GTD system. When you are
capturing everything, it can quickly become overwhelming. That is why reviewing
your lists regularly and clearing out what is no longer relevant enables you to
continue trusting in the system. Viewing your weekly completed actions
at-a-glance will make it easier to _"Get Current, Get Clear, and Get Creative."_

The user should be able to see their completed Projects and Actions in one place
before archiving them. I like the concept of "weekly velocity" to see your
ability to complete Actions and Projects improve over time.

This requirement can get complicated, especially when you consider that it
should also support higher-level reviews that take place less frequently. An
example of this would be a Monthly or Quarterly Review. For right now, I will
leave this section as-is, and we can iterate upon it later.

Nice! We successfully outlined some definite requirements for what this product
should do!

![Colbert Success](https://media2.giphy.com/media/zaqclXyLz3Uoo/giphy.gif?cid=ecf05e4731278b36dfe42d52b1cacd50c3c117fcc1ea58f7&rid=giphy.gif)

Here are the core principles of our application we have gone through:

- Mobile-first
- Kanban
- Context-Driven
- Vertical Alignment
- Reviewable

Other software matches three out of these five criteria at best. Our end goal is
to build a solution that focuses on these principles at its core.

Hopefully, following me on this journey will surface some valuable lessons in
product development and software development.

Stay tuned for the next update!


The Confidence Pedestal + The Testing Trophy


If you have been reading about test driven development in Javascript, chances
are you have come across [Kent C. Dodds](https://kentcdodds.com/), the
[Testing Trophy](https://twitter.com/kentcdodds/status/960723172591992832?ref_src=twsrc%5Etfw%7Ctwcamp%5Etweetembed%7Ctwterm%5E960723172591992832&ref_url=https%3A%2F%2Fkentcdodds.com%2Fblog%2Fwrite-tests),
and the [Testing Library](https://testing-library.com/). The Testing Trophy and
Testing Library have grown significantly over the last couple of years.

You may be asking yourself, _"Self... Why are these things so great?"_. Today I
hope to answer your inner monologue.

The Testing Trophy is a guide as to what the **composition of your testing
suite** might look like. Each type of testing requires a different amount of
effort. Since end-to-end tests requires more effort to set up, it is not viable
to write them exclusively while omitting unit and integration tests. But, if you
only write unit tests, then you won't have confidence that larger pieces of
functionality are working each time you push new code.

This is not an exact prescription to write 50% integration tests, 30% unit
tests, and so on. Instead, it suggests that you (and your team) write tests in a
way that strikes the best possible balance between **confidence** and **level of
effort**.

For frontend applications, his suggestion is that integration tests strike the
best balance between confidence and speed, so you should spend most of your
effort on writing those types of tests.

But, **how** do you achieve confidence with your tests?

If the primary goal of testing is to gain confidence in pushing code without
breaking functionality, then our tests need to be written to satisfy the
following conditions (in this order!):

- They are Realistic (representative of how a user would interact with a
  component)
- They are Resilient to changes (avoiding false positives and false negatives)
- They provide adequate Coverage of your code

This is the missing piece for the Testing Trophy that I have decided to call
**The Confidence Pedestal**.

![Confidence Pedestal Diagram](../diagrams/confidence-pedestal.drawio.svg)

This is the foundation of your Testing Trophy. Realism and Resiliency are
prerequisites for a test suite that gives you confidence. Having adequate code
Coverage is good, but without those as your base you will end up expending
effort without a solid return on investment.

If you use snapshot testing you will gain a lot of Coverage quite easily. But,
as soon as you make a change, even if it does not break the core functionality
of the component, the snapshot test will fail. This is not a Resilient test,
because in this example it triggered a _false negative_.

Conversely, if you made a breaking change to an event handler so that the user
was unable to enter text into an input field, the snapshot test would not fail.
This is a _false positive_, and it further undermines confidence in your tests.

In addition to not being Resilient, these tests are not Realistic in that they
don't represent how a user would actually use your component.

This is what The Confidence Pedestal would look like when applied to snapshot
testing.

![Confidence Pedestal Snapshot Diagram](../diagrams/confidence-pedestal-snapshot.drawio.svg)

The Realism and Resiliency layers are pencil-thin, and your Coverage layer is
deceivingly wide. It only gives you the illusion of Confidence. When you have to
overwrite multiple thousand-line snapshot files for a seemingly minor code
change, will you actually review them all? The answer, in my experience, is
overwhelmingly no.

Allow me to demonstrate the fragility of snapshot testing with a simple
`ResetPassword` component.

```jsx
// ResetPassword.js
import React from 'react';

const initialState = {
  currentPassword: '',
  newPassword: '',
  retypePassword: '',
  isSubmitted: false,
  isValid: false,
};

const validatePasswords = (currentPassword, newPassword, retypePassword) => {
  return (
    currentPassword.length > 0 &&
    newPassword.length > 0 &&
    retypePassword.length > 0 &&
    newPassword === retypePassword
  );
};

const ResetPassword = () => {
  const [formState, setFormState] = React.useState(initialState);
  const {
    currentPassword,
    newPassword,
    retypePassword,
    isSubmitted,
    isValid,
  } = formState;

  // Validate the password fields anytime the input fields are updated.
  React.useEffect(() => {
    setFormState((prevFormState) => ({
      ...prevFormState,
      isValid: validatePasswords(currentPassword, newPassword, retypePassword),
    }));
  }, [currentPassword, newPassword, retypePassword]);

  const handleChange = ({ target: { name, value } }) => {
    setFormState({
      ...formState,
      [name]: value,
    });
  };

  const handleSubmit = () => {
    setFormState({
      ...formState,
      isSubmitted: true,
    });
  };

  return (
    <>
      <div>
        <label htmlFor="currentPassword">Current Password</label>
        <input
          type="password"
          name="currentPassword"
          value={currentPassword}
          onChange={handleChange}
        />
      </div>
      <div>
        <label htmlFor="newPassword">New Password</label>
        <input
          type="password"
          name="newPassword"
          value={newPassword}
          onChange={handleChange}
        />
      </div>
      <div>
        <label htmlFor="retypePassword">Retype Password</label>
        <input
          type="password"
          name="retypePassword"
          value={retypePassword}
          onChange={handleChange}
        />
      </div>
      <button type="submit" disabled={!isValid} onClick={handleSubmit}>
        Submit
      </button>
    </>
  );
};

export default ResetPassword;
```

There are three input fields, and a submit button. As a user, we would expect to
be able to enter text into these three input fields, and then we can submit the
form once we have text in all three fields, plus the two new password fields are
matching. This is overly simplified for the sake of an easy-to-follow example.

If we were to write a snapshot test, it would be as easy as this:

```js
// ResetPassword.test.js
import React from 'react';
import { render } from '@testing-library/react';
import ResetPassword from './ResetPassword';

describe('ResetPassword', () => {
  it('should match the snapshot', () => {
    const { container } = render(<ResetPassword />);
    expect(container.firstChild).toMatchSnapshot();
  });
});
```

Our generated snapshot file looks like this:

```js
exports['ResetPassword should match the snapshot 1'] = `
<div>
  <label
    for="currentPassword"
    id="currentPasswordLabel"
  >
    Current Password
  </label>
  <input
    aria-labelledby="currentPasswordLabel"
    name="currentPassword"
    type="password"
    value=""
  />
</div>
`;
```

Triggering a _false negative_ is simple. Either of these changes will cause your
snapshot test to fail:

- Providing styles to an element

```jsx
<div style={{ backgroundColor: '#ccc'}}>
```

- Or, adding to the rendered output

```jsx
{
  isValid ? <p>✅ Passwords match!</p> : <p>🛑 Form is invalid.</p>;
}
```

Both of these changes did not break the behavior of this component, so the fact
that the test failed does not give us confidence in our test.

For style changes, there is a place for visual regression testing, but it should
not be in your unit and integration tests. Unless, you are making an assertion
that a specific element is rendered or not depending on received props and/or
actions from the user.

To trigger a _false positive_, try changing all uses of `currentPassword` to
`oldPassword`, but don't update the `name` property of the `<input>` element.
This would cause the state to be updated incorrectly, so the user would be
incapable of typing anything into the `oldPassword` field.

Here is what our test output looks like with that change:

```bash
PASS src/ResetPassword.test.js
  ResetPassword
    ✓ should match the snapshot (31ms)
```

So, the user is now unable to enter any text into the input field, but our test
did not notify us of this breakage.

Hopefully, these examples have helped you understand the shortcomings of
snapshot testing. But, I don't want to leave you only with what **not** to do.

Let's go through the same example again, but this time we'll write our tests so
that they are Realistic and Resilient.

You may have noticed the usage of `@testing-library/react` earlier. It is
capable of creating snapshot tests, but it is not intended to be used that way.

Instead, it provides a set of utilities that closely resemble how a user would
interact with a component. The API is designed in a way that encourages
test-writing that adheres to The Confidence Pedestal hierarchy.

We will be using the `getByLabelText` and `getByRole` queries to find the
components we need to test in the rendered output.

Let's start by thinking about some assertions we can make about the expected
behavior of this component.

- The submit button would be disabled at first since nothing is entered yet.
- Each input contains the text we entered as a value after typing in it.
- The button becomes enabled only once each field has a value, and the new and
  retyped passwords are matching.
- As an added bonus, we could verify that the button becomes disabled when the
  retyped password no longer matches.

Here is an example of what these assertions would look like:

```jsx
// ResetPassword.test.js
import React from 'react';
import '@testing-library/jest-dom';
import { render, screen, fireEvent } from '@testing-library/react';
import ResetPassword from './ResetPassword';

describe('ResetPassword', () => {
  const mockCurrentPassword = 'oldPassword9';
  const mockNewPassword = 'newPassword10@';
  const mockNonMatchingNewPassword = 'newPassword11&';

  it('the submit button should only be enabled when the form is valid', () => {
    render(<ResetPassword />);

    const currentPassword = screen.getByLabelText('Current Password');
    const newPassword = screen.getByLabelText('New Password');
    const retypePassword = screen.getByLabelText('Retype Password');
    const submitButton = screen.getByRole('button');

    expect(submitButton).toBeDisabled();

    fireEvent.change(currentPassword, {
      target: { value: mockCurrentPassword },
    });
    expect(currentPassword.value).toEqual(mockCurrentPassword);

    fireEvent.change(newPassword, {
      target: { value: mockNewPassword },
    });
    expect(newPassword.value).toEqual(mockNewPassword);

    fireEvent.change(retypePassword, {
      target: { value: mockNewPassword },
    });
    expect(retypePassword.value).toEqual(mockNewPassword);

    // Everything is valid, button should be enabled now.
    expect(submitButton).toBeEnabled();

    fireEvent.change(retypePassword, {
      target: { value: mockNonMatchingNewPassword },
    });
    expect(retypePassword.value).toEqual(mockNonMatchingNewPassword);

    // New passwords are no longer matching. Submit button should be disabled.
    expect(submitButton).toBeDisabled();
  });
});
```

These tests validate everything the user would expect from a form like this.
They should be able to enter the values in the input fields that correspond with
what they are trying to provide, and the form should only be submittable once
the fields are valid.

Why is this a better alternative than a snapshot test? Because each of the
examples where we caused _false negatives_ and _false positives_ for snapshot
testing are handled gracefully by this approach.

_False negatives_ are not surfaced as errors because are functionality continues
to work. _False positives_ are surfaced as errors because our component no
longer works.

Our interactions and assertions make these tests Realistic, and using the
`@testing-library/react` queries makes them Resilient. Our Confidence Pedestal
is now a sturdy foundation for our testing suite!

Hopefully, this piece helped you understand why Realistic, Resilient tests are a
vital foundation for a testing suite that gives you confidence in pushing code.
Assertion-based, user-centric testing should always be your preferred approach
for writing unit and integration tests for frontend applications.


Thursday, May 27, 2021

Codesigning for iOS Explained Simply

Tuesday, April 20, 2021

What Is Serialization?

Tuesday, July 7, 2020

Getting Things Done: An Overview

Wednesday, June 17, 2020

Building the Perfect Software for Getting Things Done

Saturday, June 6, 2020

The Confidence Pedestal + The Testing Trophy

Monday, April 6, 2020

Reflecting On My Growth As A Software Engineer