DEV Community: Devin Witherspoon

Demystifying NPM Scripts

Devin Witherspoon — Sun, 17 Jan 2021 13:18:05 +0000

If you're new to Node or have only worked on projects that already have their npm scripts set up, then you may be wondering what npm scripts are and how they work. In this article, I'll give my best intuitive explanation for how/why they work and highlight some of the key tools available for writing simple npm scripts.

What Are These Scripts?

`package.json`

package.json is the npm configuration file for a project, including its dependencies, project details, and scripts. npm run is the npm command that executes commands written in the scripts section.

For my template article repo, I set up a linter script lint, which is run with npm run lint. Running prettier **/*.md in the terminal directly wouldn't work because prettier isn't found in the global PATH.

"scripts": {
  "lint": "prettier **/*.md"
},
"devDependencies": {
  "prettier": "^2.1.2"
}

Meet `PATH`

PATH is an environment variable that lists directories where the shell should look for commands. You can find a more thorough explanation on Linux Hint.

In order to find out what's inside your PATH you can run echo $PATH. Running that on a repl.it sandbox, I got the following:

~/npm-scripting-tutorial$ echo $PATH
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

At least for our purposes, all npm run does is append a few more directories onto the PATH. We can confirm this by making the following npm script, and running it ourselves:

"scripts": {
  "path": "echo $PATH",
  "lint": "prettier **/*.md"
}

~/npm-scripting-tutorial$ npm run path

> @ path /home/runner/npm-scripting-tutorial
> echo $PATH

/usr/local/lib/node_modules/npm/node_modules/npm-lifecycle/node-gyp-bin:/home/runner/npm-scripting-tutorial/node_modules/.bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

So npm run prepended the following section to the PATH:

/usr/local/lib/node_modules/npm/node_modules/npm-lifecycle/node-gyp-bin:/home/runner/npm-scripting-tutorial/node_modules/.bin

The /home/runner/npm-scripting-tutorial/node_modules/.bin section is what gives us access to prettier in the npm lint command.

What Does This Mean?

The expansion of the PATH is what allows us to call commands written in other npm packages without referencing their exact location in our node_modules folder. If we didn't have this, our scripts would look more like the following:

"scripts": {
  "lint": "./node_modules/.bin/prettier **/*.md"
}

That wouldn't be terrible, but it's not exactly ideal.

Other Highlights

Aliases

Some commands are so common that npm aliases them so they don't need to be prefixed by run. These include:

So running npm start is the same as running npm run start.

Lifecycle Operations

There are some names that are hooks into steps of npm lifecycle commands (e.g. npm publish, npm install, npm start). You can add scripts with these names to trigger commands at those steps:

"scripts": {
  "build": "tsc --project .",
  "prepack": "npm run build"
}

One unintuitive quirk with lifecycle scripts is that prepare and prepublish (both of which are now deprecated) also trigger on local npm install, so if you have a build step that shouldn't trigger on install, it would be better associated with prepublishOnly or prepack.

The docs include more info on other lifecycle operations that you can hook into.

Command Arguments

Normally if we pass in a --option to npm run, it won't pass it through to the command written in scripts. For instance, to make prettier automatically fix issues, we would want to pass the --write option. If we add a -- before the options, they will be passed through. This means we update our npm run lint command above to the following to execute prettier --write:

npm run lint -- --write

Conclusion

Hopefully this quick intro to the concepts around npm scripts makes it easier to read the scripts you encounter, as well as start writing your own. If you have any other questions, I recommend you look through npm's well-written documentation, starting with the npm CLI docs.

Surviving Performance Review Season

Devin Witherspoon — Mon, 11 Jan 2021 04:03:10 +0000

'Tis the season where we all pick up our pens and start writing performance reviews for ourselves, our managers, and our peers. Even if you've prepared ahead of time, this can be a stressful time of year where you have to look back on your recent work and find those nuggets that best represent what you've done over the last six months to a year.

Only you know everything you've done. Your manager and others evaluating your performance don't. Writing a strong self review empowers your manager to advocate for you. So how do we do that? This isn't a definitive guide on writing a performance review, rather a reminder to myself of tools I've used to make this time more manageable and sometimes even enjoyable.

Documenting

Looking over six months of work can be really hard if you haven't been documenting what you've been doing so far. I use a Trello board with lists representing quarters and cards representing each week. These cards include a highlight of the week in the title, as well as checklists of what I did and planned to do throughout the week.

For larger projects that I want to highlight, I have a separate template that I add to the bottom of each list to ensure I include them in my self review. The templates make authoring the weekly cards and projects easier and more consistent.

Here's a template version.

Self Review

Gathering Information

In order to gather additional information, as well as make up for any gaps in my documentation, I use the following sources:

Pull requests I've authored and reviewed
Tickets I've owned
Threads from conversations with teammates
Incident channels I participated in

Writing The Review

Most of the self review prompts I've encountered are broken into three broad sections.

What Did You Do well?

A laundry list of tasks isn't enough - this is where I tell a narrative of the things I've done and their impact. Going beyond technical contributions, I include glue work, recruiting, and mentoring, tying them back to the organization's values. These other contributions are rarely as valued by leadership as technical ones, but they should be equally valued, if not more so, and round out your profile/narrative.

What Can You Improve On?

I try to be as honest as possible here, focusing on things that made my job in the last few months harder. In the past this has included communicating more clearly and proactively, working more effectively with people outside my area of expertise, and using my influence to make the recruitment process more equitable and consistent. Ideally with each self review, I can reference previous areas of improvement as places where I've made progress.

Rate Yourself

Often performance reviews ask you to grade your own performance. By default I start from a position of "Exceeds", and then review my contributions to convince myself whether it should be higher or lower.

Leveling yourself as "Meets all"/"Meets most" whether due to lack of confidence or humility often leads to managers accepting that rating and not pushing for a higher rating. If they disagree with the "Exceeds" rating, then this is a great opportunity to learn how their expectations of an "Exceeds" rating differ from your understanding of your own performance.

Ask a Peer to Review It

Having someone on your team, likely one of your peer reviewers, look over your self review (and doing the same for them) can help you catch things you missed and identify sections that need more detail/context to better describe the impact you had.

Peer Reviews

Peer review prompts are similar to those in self reviews but normally replace the rating with a section for additional notes.

Gathering Information

For peer reviews, I often sync with teammates to get an idea of the story they're trying to tell about their performance and to refresh myself on what we've worked on together. This gives them an opportunity to highlight what they think I would have unique context on.

Writing the Review

What did your peer do well?

Similar to in my self review, I try to highlight what they did as an individual, identifying specific contributions and the impact they had. I'm usually less detailed for this than my self review since I'm writing three to six of these. Highlighting their contributions that I have a unique perspective on is the priority here. This is often my favorite part of performance review season because I get to celebrate the achievements of others.

What Could Your Peer Improve on?

What I highlight depends on my teammate's experience level and where they're interested in growing. The more senior the teammate, the more I focus on their leadership, glue work, and how they drive change in the organization.

I've also had teammates that are performing well beyond their current level and I genuinely can't think of reasonable areas of improvement. In this scenario, I make recommendations for what they can do that's beyond the scope of their current role (e.g. recommend that they tech lead a project in the next cycle).

Additional Notes

This is for anything that doesn't fit in the previous two categories. In the past I've used this section for:

Describing mitigating factors for areas of improvement.
Giving a recommendation for promotion.
Giving additional context for the feedback.

Conclusion

So are performance reviews fun? Generally no, but doing them methodically can make them less intimidating and more effective. Making sure you find the process that works for you and allows your manager to effectively advocate for you is the most important piece here. An added benefit is the work I put into my self reviews becomes the foundation for my resume.

Everything's More Complex Than it First Appears

Devin Witherspoon — Mon, 04 Jan 2021 00:58:18 +0000

Coding in SCSS, like in any other programming language, should always have a goal of optimizing for readability over writing speed. Unfortunately some of the syntax available in SCSS can make it harder to read/understand. An example of this is the parent selector (&).

The parent selector is handy for pseudo-classes (e.g. &:hover) and using the context in a flexible manner (e.g. :not(&)), though we can also abuse this to create "union class names".

.parent {
  &-extension {
  }
}

This usage poses some issues:

You can't search for the resulting CSS class used by your HTML (parent-extension) within the codebase.
If you use this pattern in a larger file, you may need to look through multiple levels of nesting to mentally calculate the resulting CSS class.

This article follows the ongoing process of creating the union-class-name command of dcwither/scss-codemods, with the goal of eliminating our codebase's approximately 2,000 instances of the union class pattern.

Future Proofing

To limit the spread of the existing pattern, I introduced the selector-no-union-class-name Stylelint SCSS Rule to the project. Unfortunately this didn't fix the existing 2,000 instances of this pattern throughout our codebase. In order to make a wider fix, I turned to PostCSS.

PostCSS to the Rescue!

The idea I had was to write a PostCSS script to "promote" nested rules that begin with &- to their parent context after their parent.

Step 1: This Should be Easy, Right?

Using AST Explorer as an experimentation tool, I played with transforms until I found something that looked like it worked:

export default postcss.plugin("remove-nesting-selector", (options = {}) => {
  return (root) => {
    root.walkRules((rule) => {
      if (rule.selector.startsWith("&-")) {
        rule.selector = rule.parent.selector + rule.selector.substr(1);
        rule.parent.parent.append(rule);
      }
    });
  };
});

Attempt 1 AST Explorer snippet

The first problem I noticed was that the script was reversing the classes it promoted. This can change the precedence in which conflicting CSS rules are applied, resulting in a change in behavior.

.some-class {
  &-part1 {
  }
  &-part2 {
  }
}

// becomes

.some-class {
}
.some-class-part2 {
}
.some-class-part1 {
}

This may not be a problem if those classes aren't used by the same elements, but without the relevant HTML, we have no way of knowing whether that's the case.

Step 2: Okay, Let's Fix That One Bug

So all we need to do is maintain the promoted class orders, right?

export default postcss.plugin("remove-nesting-selector", (options = {}) => {
  return (root) => {
    let lastParent = null;
    let insertAfterTarget = null;
    root.walkRules((rule) => {
      if (rule.selector.startsWith("&-")) {
        const ruleParent = rule.parent;
        rule.selector = ruleParent.selector + rule.selector.substr(1);
        if (lastParent !== ruleParent) {
          insertAfterTarget = lastParent = ruleParent;
        }
        ruleParent.parent.insertAfter(insertAfterTarget, rule);
        insertAfterTarget = rule;
      }
    });
  };
});

Attempt 2 AST Explorer snippet

Now promoted classes maintain their order, but the transformed SCSS fails to build because of SCSS variables that don't exist where they're referenced.

.some-class {
  $color: #000;
  &-part1 {
    color: $color;
  }
}

// becomes

.some-class {
  $color: #000;
}
.some-class-part1 {
  color: $color;
}

This is where I started to realize the complexity of this problem. Variables can reference other variables, so we need to deal with that recursion. What about name collisions? What if I break something that was already working in an attempt to fix something else?

Step 3: Time For Some Structure

I wasn't going to finish this project in an afternoon with AST Explorer. At this point I decided to move the project into a GitHub repo so I could manage the increased complexity.

From here, the development process became much more formal:

Wrote tests for existing code.
Wrote test stubs for features I wanted to implement.
Created a GitHub project (Kanban board) to track tasks.
Started thinking about a CLI that others could use.
Documented the intended behavior in a README.

Even though I was the only person working on this, it became necessary to follow these practices as the project grew because I could no longer hold the entire project and behavior in my head.

Verifying

Unit tests, while helpful for documenting and verifying assumptions, are insufficient for ensuring the transform won't have any negative impacts on the resulting CSS. By compiling the SCSS before and after the transformation, we can diff the CSS to confirm there are no changes.

diff --side-by-side --suppress-common-lines \
  <(grep -v "/\* line" [before_tranform_css]) \
  <(grep -v "/\* line" [after_transform_css])

If you're interested in the more complicated testing I did, you can check out Writing Cleaner Tests with Jest Extensions.

All the Bugs So Far

So what did I realize I had missed along the way?

Multiple nesting selectors in a given selector.
Scoped variables that need to be promoted along with the promoted rules.
In Grouping Selectors (.a, .b), every member must begin with &- for the rule to be promoted.
Not accounting for the multiplicative factor of nested grouping selectors (see this test).
Duplicate scoped SCSS variables.
Promoting a rule may change the order of the rules in the compiled CSS.
Promoting SCSS variables to global scope can affect other files.
SCSS variables can have interdependencies and may require recursive promotions.
Everything about variables applies to functions and mixins.

Learnings Re-Learnings

This project isn't finished, but it has finished its arc of escalating from an afternoon of coding in a web editor to having the necessary infrastructure and testing to continue developing with confidence.

The general lesson here, which I find myself relearning from time to time, is that the work necessary to fulfill an idea is often much more complex than what you initially imagine. Because I hadn't spent much time with SCSS in a while, variables, mixins, and grouping selectors weren't top of mind. I had a myopic perspective of the language and problem (nesting and parent selector) that made the problem appear much simpler than in reality.

The bright side is, as I realized the problem needed a more complex solution, I adapted well, gradually increasing the process around the solution. Moving assumptions, requirements, and specifications out of my head and into code/tests/project boards made the entire project more manageable. The other learning is that I no longer assume that this transform is correct - it's only correct enough to be useful in the scenarios I have encountered.

If you're interested in the project, you can check it out below:

dcwither / scss-codemods

SCSS codemods written with postcss plugins

scss-codemods

This project uses postcss to refactor scss code to conform to lint rules that are intended to improve grepability/readability.

Installation

Globally via `npm`

npm i -g scss-codemods

Running on-demand

npx scss-codemods [command] [options]

`union-class-name`

"Promotes" CSS classes that have the &- nesting union selector. Attempts to fix issues flagged by scss/no-union-class-name stylelint rule.

e.g.

.rule {
  &-suffix {
    color: blue;
  }
}

// becomes

.rule-suffix {
  color: blue;
}

Intended to improve "grepability" of the selectors that are produced in the browser.

Usage

scss-codemods union-class-name --reorder never <files>

Options

`--reorder`

Determines the freedom provided to the codemod to reorder rules to better match the desired format (default: never).

Values:

never: won't promote rules if it would result in the reordering of selectors.
safe-only: will promote rules that result in the reordering of selectors as long as the reordered selectors…

View on GitHub

Hobbies Make Me a Better Engineer

Devin Witherspoon — Sun, 27 Dec 2020 15:05:17 +0000

Recently there's been a lot of discussion on Twitter about whether "frontend engineer" is its own specialization. I'm not up for arguing this - my opinion is yes, it absolutely is, and in fact I've worked with people with several specializations within frontend development (accessibility, architecture, performance, infrastructure, etc.).

One of the arguments for expanding into backend/other technologies is that they reinforce and benefit your abilities as a developer. I think this is a good point, but it applies more broadly to any skill or hobby. A frontend engineer can broaden their experience through other means besides backend engineering, like activities, hobbies, or creative outlets. I'll highlight some of the ways my hobbies have made me a better engineer.

Writing

I'm working on my writing for a lot of reasons, but one reason is so I can better communicate with my teammates. As I've gotten further in my career, the marginal benefit of improving my individual coding ability has diminished, and my ability to communicate, negotiate, and prioritize within my team has become more important.

Writing blog posts makes it easier to communicate my ideas and provides me with a resource to reference when people ask for my thoughts on something I'm familiar with. It has also driven several of my new projects as I have to brainstorm new article ideas each week.

Photography

I picked up photography to feel closer to my grandparents who were avid amateur photographers. While I'm not a great photographer, it helps develop my understanding of visual composition and color, making me better at building user interfaces. It also improves my attention to detail and ability to communicate with designers. Editing photos forces me to identify high value work and prioritize my best photos for processing in Lightroom.

Running

Running and other forms of exercise keep me healthy and balance out sitting and standing at a desk all day. They also require growing past my limits through goal tracking and consistent habits. Running reduces my back pain and improves my mood, making me a more pleasant person to work with.

Conclusion

Being a better engineer isn't only about learning the next design pattern, technique, or technology. For me, investing too much into that in the past has led to boredom and burnout, with no escape. Balancing my time with other hobbies helps me keep the creative spark going, as well as build my growth mindset. I'm not great at any of these hobbies compared to my coding ability, but building these skills has been an exercise in humility and recognition of my ability to grow.

What hobbies have made you a better engineer? The connection doesn't have to be direct:

Has it improved your health?
Made you a more helpful teammate?
Allowed you to focus more deeply?

Those all make you a better engineer! Hopefully if you're lucky enough to have a holiday break right now, you're taking time to recharge through other hobbies or interests. Happy Holidays!

Fighting Misery

Devin Witherspoon — Sun, 20 Dec 2020 13:32:58 +0000

As I write this I'm taking good care of myself, working towards contentment. This article serves to remind to my future self what tools I have at my disposal to help escape misery. I'm using misery as a stand-in for depression/anxiety/stress/low motivation because it's often hard for me to recognize which combination of these I'm experiencing and the end result is that I'm unable to experience contentment. Similarly, I'm using contentment as a stand-in for happiness/calm/high motivation.

Before I start, I want to acknowledge that not everyone has all these tools at their disposal, and they certainly won't help everyone. This is also not a replacement for medication or help from a medical professional - in fact I was able to find most of these through therapy and coaching.

Identifying and Maintaining Feelings

One of the biggest challenges as I drift into misery is first identifying how I'm feeling. Knowing that I'm feeling unmotivated, upset, or disappointed in myself helps me build a plan to get to a better place. I use the following habits to maintain and monitor my mental health.

Achievement and Gratitude

At the end of each day, my wife and I share at least one achievement and one gratitude. They can be anything, even everyday activities (e.g. one day my achievement was I went for a walk, and my gratitude was I called my family). This is a moment for me to pause and think about the good things in my life - sometimes I struggle to come up with even one. If this happens a few days in a row, it's a flag that I need to invest more time in my mental health.

Cognitive Behavioral Therapy (CBT) Journaling

To track my mood, I record my feelings with CBT journaling apps. I've used two apps for this - Mood Notes and Stoic. Both have been great, though I recently switched to Stoic because I like the aesthetic. They force me to think about how I'm feeling, which I would otherwise overlook. They ask me questions that test my cognitive biases and have me come up with other ways of thinking about whatever may be bothering me. At times when I feel like I'm always miserable, my previous entries remind me that these feelings aren't actually constant.

Exercise

Every day after I get out of bed, I hop on my stationary bike with a goal of biking for 20 minutes. This isn't intense exercise and if I'm not feeling up for it, I allow myself to stop after 5 minutes. This is my keystone habit and a commitment I've made to myself, so it's a red flag if I skip this routine two days in a row.

Intervening

Once I've identified that I'm experiencing some form of misery, it's time to focus on recovering. I don't always start this step immediately, as taking action requires some amount of energy.

Tell Someone I'm Struggling

The first thing that moves me towards contentment is telling people, often my wife and therapist/coach, that I'm struggling. Being vulnerable is hard for me, but it helps me to not feel alone. It also gives others context on what I'm dealing with and sets expectations for what I'm currently capable of handling.

Work Through Guilt

A common feeling that comes with my misery is guilt - guilt over not keeping up with routines, playing video games too much, eating unhealthily, not exercising, letting laundry pile up, etc. With my therapist's help, I've realized this feeling of guilt isn't motivating me, rather it's driving me to hide from these problems even more.

Listening to this guilt and forgiving myself for these "failures" helps me calm the inner monologue telling me what I should have done. Taking the time to recognize my partial successes also helps me escape the all-or-nothing mindset that contributes to my guilt.

I didn't exercise, but I did go for a walk.
I didn't bike for 20 minutes, but I managed to get on the bike.
I've been miserable and aware of it for a few weeks, but I told someone today and I'm working on it.
I sat on the couch all day, but I remembered to do my CBT journaling.
My other habits are flying out the window, but I've written for 7 weeks in a row.

Find Something I Can Do

From here I pick something within my current ability and commit to doing it. This can be whatever requires the least amount of energy to help build more motivation. CBT refers to this as behavioral activation. For me these activities are biking, going for a walk, cooking an easy meal, and sharing achievement and gratitude. Habits that fit into my typical routine are easier (e.g. biking is a morning thing for me, so doing it in the afternoon requires a lot more motivation).

My friend and former classmate Jamie Wong wrote an amazing article on this topic, so I'll refer you to The Pit, the Cabin, and the Dance Floor for a deeper dive.

Build Accountability

At this point I've already told someone I'm struggling, so now I have to tell that person what I've committed to doing. Being specific makes this more effective, e.g. "I'm going to get out of bed by 7AM and bike for at least five minutes."

Conclusion

My misery doesn't just disappear after following these steps, but this has been how I've been working through it lately. I've gone through the loop of misery and contentment a few times this year, and I've found it's been shorter than in the past. As with academic and professional pursuits, I'm trying to take a growth mindset towards mental health.

Similar to how the goal of meditation isn't to have a clear mind at all times, my goal isn't to be content all the time. The goal is to shorten the times when I'm miserable and extend the times when I'm content.

Typography: Separating Style from Semantics

Devin Witherspoon — Sun, 13 Dec 2020 12:26:20 +0000

Getting started with accessibility can be intimidating, especially when your project has complicated user flows and interactions. A great entry point into accessibility is fixing up your heading hierarchy. Fixing this simple issue can make navigating the site much easier for your users.

This article focuses on improving webpage accessibility in a small but meaningful way. For more information on headings and accessibility, consult the W3 Headings Accessibility Tutorial.

The intent of this Success Criterion is to ensure that information and relationships that are implied by visual or auditory formatting are preserved when the presentation format changes.

- WCAG Success Criterion 1.3.1: Info and Relationships

Heading Hierarchy

Correct heading hierarchy helps assistive technology like screen readers interpret your pages. Consistently applying styles with a 1:1 mapping between heading elements and size is the ideal scenario. On complex websites, though, design constraints often prevent us from consistently styling headings, so we're left with three options.

Styles > Hierarchy

If we prioritize styles, we conform to design constraints but lose the heading hierarchy. Even worse, this results in misleading headings that explicitly miscommunicate the structure to screen readers and other assistive technology.

This use of headings produces a document structure that implies the first h3 (Life) isn't a parent heading of the subsequent h2 despite Kingdom being a grouping within Life - this isn't the intended outcome.

This might not be a big deal for seeing users, but we want everyone to be able to fully navigate and experience the products we build, so we should avoid this practice.

Fight Work with Design to Make Styles = Hierarchy

This option isn't always available, but you should apply it wherever possible. While not universal, text size indicates a visual hierarchy within the document, and making an h3 larger than an h2 can be misleading to the user.

If your designer isn't familiar with accessibility standards, work with them to better understand heading structure and WCAG guidelines. Engineers can't own accessibility alone, and neither can designers - it's a shared responsibility for everyone to invest time and effort into. If everyone does their part, the product will be better for all users.

If you reach full alignment between engineers and designers, you end up with a heading structure that matches both visually and semantically.

Styling Elements Independent from Semantics

For the times we can't reach 100% alignment between engineering and design, we should still work to reach a helpful information hierarchy in our HTML. By separating appearance from the element tag, we can achieve the desired style while maintaining the correct heading hierarchy.

So how do we separate appearance from the element tag? The easiest solution is to use global classes that match the intended element:

/* classes match the intended element */
h1,
h2,
h3,
h4,
h5,
p,
.h1,
.h2,
.h3,
.h4,
.h5,
.body {
  margin: 0 0 0.5em 0;
  font-family: "Poppins", sans-serif;
}

h1,
.h1 {
  font-size: 3rem;
  font-weight: bold;
}

h2,
.h2 {
  font-size: 2.5rem;
  font-weight: bold;
}

h3,
.h3 {
  font-size: 1.75rem;
  font-weight: bold;
}

h4,
.h4 {
  font-size: 1.25rem;
  font-weight: 600;
}

h5,
.h5 {
  font-size: 1rem;
  font-weight: 600;
}

p,
.body {
  font-size: 1rem;
  font-weight: normal;
}

Note: the styles here aren't specific recommendations, rather an example of what can be done.

Existing Implementations

While I've walked through a manual implementation with raw HTML and CSS, you may want a more robust solution. You could build one from scratch without much difficulty, but there are also existing solutions in component libraries:

Conclusion

Hopefully this tutorial helped you learn a bit more about accessibility in web development and how to incorporate it into your regular development practices. If you've come up with your own solution for this topic, please share it below.

Appendix: Automated Heading Tags

Still here? Okay, let's go a little further. What if I use a component in two separate parts of the app - one where the parent heading is an h1 and another where the parent heading is an h2 - what should be the child heading tag in this component?

I might argue that in the first scenario it should be an h2 and in the second it should be an h3. Should we do a custom heading prop? 🤢 Let's try solving it with React context instead.

// Heading.jsx
import React, { createContext, useContext } from "react";

const headingLevelContext = createContext(0);

function useHeadingLevelContext() {
  return useContext(headingLevelContext);
}

export function Heading({ size, as, children }) {
  const defaultComponent = `h${useHeadingLevelContext()}`;
  const HeadingComponent = as || defaultComponent;

  return (
    <HeadingComponent className={size || HeadingComponent}>
      {children}
    </HeadingComponent>
  );
}

export function HeadingBlock({ level, children }) {
  const defaultLevel = useHeadingLevelContext();

  return (
    <headingLevelContext.Provider value={(level || defaultLevel) + 1}>
      {children}
    </headingLevelContext.Provider>
  );
}

HeadingBlock keeps track of the heading level by incrementing the heading level context when nested inside another HeadingBlock and increasing the heading tag used by Heading. Let's look at it in action:

By capturing the heading level in the context, we can provide the size for styling, while the context determines the heading element used.

Abstracting heading semantics away from developers may also have downsides, and I haven't tested it in a production application or accessibility audit, but it's an interesting idea to explore further.

My Dev.to Writing Process

Devin Witherspoon — Sun, 06 Dec 2020 12:11:09 +0000

Beginning to write Dev.to articles was intimidating for me, and a tutorial on writing articles would have helped reduce the barrier to entry. Now that I've written six articles, I've settled into a comfortable flow that I thought I'd share with anyone else interested in taking the plunge into writing their own technical articles.

I've tuned this process for my needs as a writer, ensuring I can consistently write technical articles with a specific structure, but I think it works well for opinion pieces as well.

The Setup

I keep all my articles in a GitHub repository so that I can access them from multiple computers and track changes as I go. Like coding, sometimes I'm unsatisfied with my changes, and I want to compare them to a previous version. A simple file version manager would also suffice.

File Structure

I keep my active articles in a drafts folder. When I publish an article, I prepend it with the date and move it to the published folder for ordering/archival purposes. This gives me a record of my articles and images in case I want to publish anywhere else or need to make a change.

├── README.md
├── drafts
│   ├── more_accessible
│   │   └── main.md
│   └── writing_process
│       └── main.md
├── package-lock.json
├── package.json
└── published
    ├── 2020_10_31_color_migration
    │   ├── hero.jpg
    │   └── main.md
    ├── 2020_11_07_testing_postcss
    │   ├── hero.jpg
    │   └── main.md
    ├── 2020_11_15_marginal_linting
    │   ├── hero.jpg
    │   ├── main.md
    │   └── reviewdog-annotation.png
    ├── 2020_11_16_use_datetime
    │   └── main.md
    ├── 2020_11_22_testing_time
    │   ├── hero.jpg
    │   └── main.md
    └── 2020_11_29_bad_variable_names
        ├── hero.png
        └── main.md

Package.json

I use Prettier with lint-staged to automatically format my articles after every commit. This is particularly helpful for any code blocks in .md files.

// package.json stub with the dependencies and scripts necessary for the commit hooks
{
  "scripts": {
    "lint": "prettier --ignore-path=.gitignore **/*.md",
    "lint:fix": "npm run lint -- --write"
  },
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{js,jsx,css,scss,md}": "prettier --write"
  },
  "devDependencies": {
    "husky": "^4.3.0",
    "lint-staged": "^10.5.1",
    "prettier": "^2.1.2"
  }
}

VSCode

I use Visual Studio Code to edit and preview markdown. I've tried Mark Text, and Typora, neither of which felt right for me - their rich text editing for markdown seems to struggle with undo/redo.

I use the following VSCode Plugins to help with my writing:

Spell Right for basic spell checking.
VSCode Prettier auto-formats my code on every save.
Write Good encourages me to use active voice and cuts unnecessary words.

Here's my project level .vscode/settings.json for configuring the plugins:

{
  "editor.rulers": [100],
  "[markdown]": {
    "editor.wordWrap": "bounded",
    "editor.wordWrapColumn": 100
  },
  "editor.formatOnSave": true,
  "write-good.languages": ["markdown", "plaintext"],
  "languageToolLinter.serviceType": "public"
}

The Process

Ideas 💡

I initially struggled each week to come up with new article ideas, so I started tracking my thoughts as they popped into my head throughout the day. As I come up with ideas I add them as sections to README.md. To develop the idea, I add bullet points that I'd like to cover. Often these bullet points become the headings for my articles. If my computer isn't near, I add a short note on my phone to move to my README.md later.

Structure 🏗

When I get started on an article, I try to get the heading structure onto the page first. This helps me identify what I want to say and make sure I'm making an honest effort at having a flow to my article. At this point I run the structure by my editor (in my case, my wife, but whomever you have to get a second opinion can help).

First Draft 📝

Now that I have the idea and structure, it's time to write the article. In addition to the article itself, I build demos or test applications to verify technical accuracy. For instance, I made jest-postcss while writing Writing Cleaner Tests with Jest Extensions and an example repo for Adding New Lint Rules Without the Fuss. I embed interactive tools (repl.it, Code Sandbox) whenever possible through Dev.to's liquid tags to make the article more engaging.

Read Through 👀

I do a first pass to make sure everything makes sense to me. A lot of big edits and paragraph rearranging happen in this step. I try to leave the first draft sitting for a few hours or a day so I can come back to it with a fresh mind.

Listen to it 🎧

Because I struggle to see what is wrong with my writing just by reading it, I use Mac's text to speech to listen to my article. This helps catch phrasing that is hard to parse or sounds awkward when read aloud. This and the read through help limit the time my editor puts into the writing - she's doing it for free after all.

High-Level Feedback 🚥

At this point I ask my editor to look through the article for any big changes or gaps in the article. I try to not be too attached to anything I've written so far because anything is fair game for revisions.

Polish ✨

After addressing high-level comments, I ask my editor to walk through the entire article with me piece-by-piece to clean up wording. This is where we make sure the ideas are easy to understand for the reader. We no longer spend the whole time fixing passive voice now that I use the Write Good plugin.

Ship It! 🚢

For now I publish directly to Dev.to by copying my markdown files over, making sure to preview them for any issues. It's important to make sure liquid tags work before publishing since they don't render in VSCode's markdown preview.

Hero Images

Hero images help catch the reader's eye. They're an opportunity to show readers something about your article or yourself. I normally use a photo I've taken myself, but for articles with code I started using Carbon.now.sh to help give readers a clearer idea of the article's contents.

This was the hero image from my article, Stop Using "data" as a Variable Name

Conclusion

That's my whole process for writing technical articles. I hope it's helpful to anyone who wants to start writing and makes the process less intimidating. I'd love to hear what other tools, processes, or services people use for their writing.

You can also check out my template repo, which I'll try to keep up-to-date with any new practices I adopt.

dcwither / articles-template

template folder

Ideas

Easy

Previous Projects

Future Projects

Opinion

Big Ideas

View on GitHub

Stop Using "data" as a Variable Name

Devin Witherspoon — Sun, 29 Nov 2020 12:41:02 +0000

"There are only two hard things in Computer Science: cache invalidation and naming things."

- Phil Karlton

Setting aside cache invalidation, which is indeed difficult, this infamous quote is something that rings in my head whenever I'm having trouble finding the right name for something. Clear naming provides important context whenever someone needs to quickly understand code, whether they're firefighting, debugging, interviewing, or assisting a teammate - I don't have to ask someone what users means, but I do have to ask what data means. While I don't often find the best names, I try to optimize my code for the reader by following some basic rules.

The Rules:

Use Meaningful Prefixes

While these prefixes aren't universal, they are great to establish a shared language within your team. Using them consistently throughout your codebase can make reading comprehension easier.

get, find, fetch for functions that return a value or a Promise that resolves to a value without mutating arguments or itself.
set, update for functions that mutate arguments or the callee for member functions. These functions may also return the updated value or a Promise that resolves to the updated value.
on, handle for event handler functions. My team's convention is that onEvent is passed through props into the component and handleEvent is declared inside the component.
is, should, can for boolean variables and functions with boolean return values.

Any convention that becomes a standard in your team can help with readability. Make sure to document these in the project README or wiki. Creating custom linters to enforce these would be even more effective.

Use Words that Add Meaning

As an example, developers often name variables data by default, but let's examine a couple of its definitions:

"factual information (such as measurements or statistics) used as a basis for reasoning, discussion, or calculation"

"information in digital form that can be transmitted or processed"

These definitions could refer to any variable we process, so they give the reader no information. Let's look at an example that doesn't follow this rule:

function total(data) {
  let total = 0;
  for (let i = 0; i < data.length; i++) {
    total += data[i].value;
  }

  return total;
}

We know this function calculates a total of something, but we're not sure what.

Exceptions

Sometimes your variable could actually contain anything, like a network request response body. Libraries like axios use data, which is a reasonable name in this context. Even in this scenario, the alternative body conveys more meaning and is what the native web API fetch uses in its Response.

Use Full Words

Like everyone else's, the System 1 part of my brain always tells me to take shortcuts to finish my task sooner. When it comes to variable naming, shortcuts often mean abbreviations or single character variable names.

Like before, let's look at a function that doesn't follow the rule:

function totBal(accts) {
  let tot = 0;
  for (let i = 0; i < accts.length; i++) {
    tot += accts[i].bal;
  }

  return tot;
}

We can do some mental gymnastics to guess that accts means accounts and tot is total, but we can't process the code at a glance.

Exceptions

Common industry abbreviations are preferred over their long form (e.g. URL, API, CSS).

Don't Use "Fluff" Words

Container and Wrapper only have meaning in relation to the thing they're containing. The problem is that any component that isn't a base element contains another component. You also end up in the awkward position of naming components MyComponentContainerContainer. The same applies to Wrapper.

Exceptions

In some contexts, these "fluff" words can have significant meaning. A common pattern in React class components is the presentation/container component pattern. Container in this case may indicate a component that manages state on behalf of a presentation component - just make sure you consistently use it for this purpose, or it loses meaning.

Spelling Matters

Misspelling words creates bugs and makes searching your code harder. Typos are easy to ignore, but having the right spelling for everything in your codebase makes a world of difference, especially when attempting global find/replace.

Putting it Together

Applying all the rules at once, we get the following function:

function getAccountsTotalBalance(accounts) {
  let totalBalance = 0;
  for (let accountIndex = 0; accountIndex < accounts.length; accountIndex++) {
    totalBalance += accounts[accountIndex].balance;
  }

  return totalBalance;
}

While accountIndex vs. i might be contentious, the rest of the function should be much clearer. getAccountsTotalBalance fully communicates the intent of the function and the prefix get indicates that it will not result in any mutations. It's worth the code author investing increased effort in exchange for the benefit of the reader. Your future self will appreciate the extra work when they're maintaining the code six months later.

If you're worried about line length, consider using a tool like Prettier to automatically format the code.

Conclusion

The goal of these rules is to bring as much meaning as possible to the code we write for future readers. Find the ones that work for your context, and if a rule is doing more harm than good, change or abandon it. Codifying your team's rules will help communicate your thoughts on the subject and is not meant to bring a hammer down on your teammates.

Please share any other rules you follow when naming variables, functions, classes, etc. or let me know if you disagree with any of the rules here and how you'd change them.

Defusing Time Bomb Tests using Randomization

Devin Witherspoon — Sun, 22 Nov 2020 22:45:00 +0000

Flaky tests are generally something to avoid, but even worse are tests that start failing a year after they merge. These tests are time bombs waiting to go off when we're least prepared (e.g. in the new year). What if adding chaos into our test environments actually helped surface these issues earlier in the development cycle?

Note: All examples are written for Jest tests, but the concepts can be adapted for other testing frameworks/languages.

Time in Tests

You may have already written a test that worked when you wrote it and even worked in CI, but it stopped working at a later date - especially around New Year's when offices are closed.

Here's an example:

// relies-on-time.js
export function isInPast(date) {
  return new Date() >= date;
}

// relies-on-time.test.js
describe("relies-on-time#isInPast", () => {
  it("should return false for dates in the future", () => {
    expect(isInPast(new Date("2020-12-31T00:00:00.000Z"))).toBe(false);
  });
});

At time of writing, this test passes, but on Jan 1, 2021, the test will begin failing. This isn't ideal because this code could have merged long ago. By the time it begins failing, it may block application deployments and we've lost some context on the intended behavior.

Using Fake Timers

One solution is to use fake timers to mock the date. If you've spent a lot of time writing Jest tests, you've even likely mocked Date.now to set the current date.

As of Jest 26.1.0 it includes the jest.setSystemTime(now?: number | Date) function to mock the system time as long as you're using the "modern" setting.

Using fake timers and jest.setSystemTime, we have a test that will now pass regardless of the current date:

// relies-on-time.test.js
describe("relies-on-time#isInPast", () => {
  it("should return false for dates in the future", () => {
    jest.useFakeTimers("modern");
    jest.setSystemTime(new Date("2020-11-20T00:00:00.000Z"));

    expect(isInPast(new Date("2020-12-31T00:00:00.000Z"))).toBe(false);
  });
});

We've caught this test and fixed it, but there are still other tests with the same issue waiting to blow up. People are also forgetful - we'll write more tests that pass now but won't pass the next day/week/month/year, so what do we do?

Random Time as a Default

We can make use of randomization to get our tests to fail now instead of later. If we default time as a random time that changes per run, we can take advantage of this randomization to detect tests that rely on a certain real-world time. This also helps the team build good habits of addressing time in tests.

// jest.setup.js
function randomDate(start, end) {
  // Source: https://stackoverflow.com/questions/9035627/elegant-method-to-generate-array-of-random-dates-within-two-dates
  return new Date(
    start.getTime() + Math.random() * (end.getTime() - start.getTime())
  );
}

beforeEach(() => {
  // setup our fake timers
  jest.useFakeTimers("modern");
  jest.setSystemTime(
    randomDate(
      new Date("2000-01-01T00:00:00.000Z"),
      new Date("2040-01-01T00:00:00.000Z")
    )
  );
});

afterEach(() => {
  // cleanup fake timers
  jest.runOnlyPendingTimers();
  jest.useRealTimers();
});

Note: I chose Jan 1, 2000, to Jan 1, 2040, as an appropriate range for my application. You should pick the range that best fits your needs.

You can add this snippet to your global jest setup. After several runs, it will identify any tests that implicitly rely on time.

Catching Issues Sooner

You should make sure that this check can flag issues before they merge. For example, you could add redundancy to test runs before PR merge by running them multiple times in CI.

Conclusion

Fake timers are great, but enforcing their use can be tricky. Time can be deeply embedded in our applications in ways we don't immediately see. Take advantage of randomization to root out implicit assumptions, and make them explicit so your tests can withstand the test of time.

Appendix: Full Setup

You can take a look at the whole setup with some more tests in this example GitHub repo, or browse this repl.it:

Sorry, repl.it embeds don't let me choose the default file. Check out jest.setup.js and relies-on-time.test.js.

Tracking Time with React Hooks

Devin Witherspoon — Tue, 17 Nov 2020 00:18:37 +0000

Let's Talk About Time

Time is super tricky to account for in software, and one of the most common issues in frontend applications is developers forget that time keeps passing when the page is open.

Take a look at Falsehoods programmers believe about time for a starting point on the assumptions developers make.

It's really common to write a component that looks like this:

const formatter = new Intl.DateTimeFormat("en-us", {
  year: "numeric",
  month: "numeric",
  day: "numeric",
  hour: "numeric",
  minute: "numeric",
  second: "numeric",
});

const MyDateComponent = () => {
  const date = new Date();

  return formatter.format(date);
};

See MDN Intl.DateTimeFormat for more on the date formatter used.

The issue with this component is that it doesn't update when the seconds change. This isn't as much an issue if we're not displaying seconds, but even hours and days can pass while browser tabs are open.

`useDateTime`

To solve this problem, I wrote useDateTime, a React hook that tracks the time to a specified precision (second/minute/hour/day), triggering a state change on each tick.

Using useDateTime to fix MyDateComponent, we get the following:

const MyDateComponent = () => {
  const date = useDateTime("second"); // second | minute | hour | day

  return formatter.format(date);
};

This component now updates every second, keeping it accurate. We probably only want updates for every second in a clock component, and should avoid this frequency of updates for expensive renders. Outside of clocks, updating by the hour/day is much more common and something we should plan for as frontend engineers.

You can take a look at the implementation of useDateTime in this codesandbox:

The implementation uses date-fns but could be rewritten with any date library (e.g. Moment/Luxon/Day.js)

A similar hook could be used to track relative times by modifying msUntilNext to determine the next tick in increasing intervals.

Disclaimer

This component attempts to update immediately after the next tick at the specified precision. Javascript's setTimeout API does not guarantee that the timeout will trigger precisely on the target time, so the precision of this hook is also limited. Here's a good Stack Overflow Q&A summarizing this problem and a workaround.

Adding New Lint Rules Without the Fuss

Devin Witherspoon — Sun, 15 Nov 2020 15:57:38 +0000

Linters are great for maintaining code quality and encoding team conventions, but how do you add new rules that your codebase currently violates? If there's a handful of violations or the violations can be autofixed, then it may be easy to fix them before adding the rule, but what if there are hundreds of them?

Case Study

Suppose we've already set up CI for linting and want to add the ESLint rule import/extensions to ensure that every import has a file extension. Let's walk through some options at our disposal and consider the pros and cons of each option.

Option 1: Fix Every Violation

The first option available is to fix every violation that comes up from the new lint rule.

The Setup

First, add the new rule:

diff --git a/.eslintrc.json b/.eslintrc.json
   ...
   "rules": {
+    "import/extensions": ["error", "always"]
   }

There's now lint errors and we can't merge to our main branch without failing CI, so we fix every error before merging. While time consuming, this process is straightforward. You go through each lint violation in the codebase and fix it - in this case, by adding a file extension to every import that is missing one.

Pros

The codebase is 100% adhering to the new rule! There are no lint violations, and everyone in the future will follow this rule in their changes or face the wrath of a failing build. This strategy is awesome when there's time and motivation to get it done.

Cons

When there are hundreds of warnings that can't be autofixed, this strategy will postpone or prevent you from getting value out of new rules.

Option 2: Make the New Rule a Warning

What about adding the new rule as a warning instead of an error?

The Setup

First, add our new rule:

diff --git a/.eslintrc.json b/.eslintrc.json
   ...
   "rules": {
+    "import/extensions": ["warn", "always"]
   }

and we're done!

Pros

Setup was super easy - there's now a new lint rule that developers will see in their editors if they use an ESLint plugin.

Cons

There's nothing really enforcing the new rule. It's just a warning, and there may be hundreds of other warnings in the codebase. Warnings will pile up without developers noticing them.

Mitigations

ESLint has a CLI option --max-warnings which enforces a max number of warnings. Unfortunately, as you fix any existing warnings you have to keep this up to date, otherwise each fix gives slack for future warnings.

Option 3: Suppress the ESLint Errors

We could suppress the existing violations to enforce the new rule going forward while avoiding the immediate cost of fixing existing issues.

The Setup

We'll add the new rule, and then add eslint-disable-next-line for each lint violation.

First, add the lint changes to .eslintrc.json, same as option 1:

diff --git a/.eslintrc.json b/.eslintrc.json
   ...
   "rules": {
+    "import/extensions": ["error", "always"]
   }

Then run suppress-eslint-errors. The suppress-eslint-errors package notes that you may have to manually fix some of the suppressions it adds. If your setup doesn't involve ESLint, you'll need to find an alternative to suppress-eslint-errors, or may have to do this part manually.

npx suppress-eslint-errors src/**/*.{ts,tsx} --message="TODO: add extension"

diff --git a/src/App.test.tsx b/src/App.test.tsx
 import { render, screen } from '@testing-library/react
+// TODO: add extension
+// eslint-disable-next-line import/extensions
 import App from './App';

See this example of a suppress violations diff for the changes needed to add this to a small project.

Pros

Suppressing existing failures keeps our lint warnings clean and allows us to enforce future changes don't violate the new rule. You can go back and systematically fix suppressed violations in smaller chunks.

Cons

The lines suppressing warnings reduce the signal-to-noise ratio of the code. It can also make it seem ok to add eslint-disable whenever a developer writes code that violates lint rules, reducing the effectiveness of linting.

Option 4: Only Lint New Changes with New Rules

With a little extra work and a slightly more complicated setup, we can achieve linting that will ignore existing violations, while keeping us accountable in new changes. I like to call this marginal linting.

Using a tool like reviewdog (or pronto if you like ruby), we can set up GitHub checks to annotate our PRs with any lint violations.

The Setup

We'll have two separate ESLint configs now. The "main" ESLint config (.eslintrc.json) adds the new rule. This is our default config which we run in editors as well as in reviewdog.

First, add the lint changes to .eslintrc.json, same as option 1.

diff --git a/.eslintrc.json b/.eslintrc.json
   ...
   "rules": {
+    "import/extensions": ["error", "always"]
   }

Our second ESLint config will intentionally disable the newly added rule in CI. Target it in the lint workflow with eslint --config=.eslint-ci.json.

// .eslintrc-ci.json
{
  "extends": ".eslintrc.json",
  "rules": {
    "import/extensions": "off"
  }
}

Add a new GitHub workflow using the reviewdog eslint action to execute our new rules on pull requests.

# .github/workflows/reviewdog.yml
# Modified from reviewdog action eslint README
# https://github.com/reviewdog/action-eslint#githubworkflowsreviewdogyml
name: reviewdog
on: [pull_request]
jobs:
  eslint:
    name: runner / eslint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - name: Lint Typescript Changes 👕
        uses: reviewdog/action-eslint@v1
        with:
          reporter: github-pr-check
          eslint_flags: "--config=.eslintrc.json src/**/*.{ts,tsx}"

See this example reviewdog setup diff for the changes needed to add this to a small project.

The Result

We now receive warnings in our pull requests whenever our changes violate any lint rules, including our existing ones.

Pros

Making .eslintrc.json the more restrictive configuration ensures that any new integrations will follow it by default. Any use of .eslintrc-ci.json can be explicitly specified such as in CI.

This setup has the added benefit of including code review integration, which can be beneficial regardless of new lint rules. It also means that any new rules require a two line change: one for the lint rule in .eslintrc.json and another to disable it in .eslintrc-ci.json.

Cons

The setup for this option is more involved, and adds a new technology to the CI stack. The build time for this task in a new create-react-app was 3 minutes, and could increase depending on the project size.

Conclusion

While it's nice to have a 100% compliant codebase, it might not be possible to fix every violation immediately. Minimizing the effort of adding new lint rules helps ensure your team can adopt and enforce best practices moving forward.

Running a script to disable lint errors for new rules can quickly fix the issue but remains the same effort for every future lint rule. Adopting two lint configs, while requiring a slightly more complex initial setup, provides the same benefit and allows you to add new rules easily. Integrating it with reviewdog or pronto makes encouraging the new practices even easier in code review.

Writing Cleaner Tests with Jest Extensions

Devin Witherspoon — Mon, 09 Nov 2020 15:21:41 +0000

Introduction

While developing scss-codemods I wrote tests to ensure changes for new features wouldn't break my previous work. As the tests grew in number, I found myself following a familiar pattern: refining tests and extracting boilerplate to further focus each test on the behavior we're testing (the test subject).

The Jest extensions (custom serializers and matchers) below are available in the jest-postcss npm package.

Testing PostCSS Plugins

While PostCSS plugins can have countless behaviors that need testing, they have a clear API to test - the input CSS and output CSS. We'll start with a single standalone test:

import postcss, { Result } from "postcss";
import postcssScss from "postcss-scss";

it("should transform the css", async () => {
  const result = await postcss(removeNestingSelector).process(
    `
      .rule { 
        &-part {}
      }
    `,
    {
      parser: postcssScss,
      from: "CSS",
    }
  );

  expect(result.css).toMatchInlineSnapshot(`
    ".rule {
      } 
      .rule-part {}"
  `);
});

Note: I'm fond of inline snapshot tests, as long as they're concise.

Stripping out the PostCSS specifics, the test looks like this:

it("should transform the css", async () => {
  const RECEIVED = BOILERPLATE(SUBJECT, INPUT);
  expect(RECEIVED).MATCHER(EXPECTED);
});

We can look at this test as having 2 steps:

Apply the BOILERPLATE function to the SUBJECT plugin and INPUT CSS, giving us the RECEIVED CSS.
Check RECEIVED against EXPECTED using a MATCHER.

1. Extracting the Boilerplate

Pulling out the BOILERPLATE from our test case gives us the function createProcessor:

import postcss from "postcss";
import postcssScss from "postcss-scss";

function createProcessor(plugins) {
  const configured = postcss(plugins);
  return async (css) => {
    return await configured.process(css, {
      parser: postcssScss,
      from: "CSS",
    });
  };
}

We can now apply this function outside of the tests to avoid unnecessary setup for each test.

2a. Snapshot Serializers as `MATCHER`

If we use inline snapshots to compare RECEIVED and EXPECTED, we'll want to clean up the snapshot.

expect(result.css).toMatchInlineSnapshot(`
    ".rule {
      } 
      .rule-part {}"
`);

The extra quotes and poor indentation distract from the goal of the test - to check that the RECEIVED is the same as EXPECTED. We can reformat the snapshot by adding a snapshot serializer to Jest with expect.addSnapshotSerializer, prettifying the CSS for easy visual comparison.

import prettier from "prettier";

function serializeCSS(css: string) {
  return (
    prettier
      .format(css, { parser: "scss" })
      // keep empty rules compact for simpler testing
      .replace(/\{\s*\}/g, "{}")
      .trim()
  );
}

expect.addSnapshotSerializer({
  test: (val) => val instanceof Result,
  print: (val) => serializeCSS(val.css),
});

Now any PostCSS Result will render as prettified CSS when tested using Jest snapshots.

After completing these two steps the test is much easier to read, making it easier to identify whether updates are intentional during code review. This refactor isn't worth it for a single test, but with 48 snapshot tests in scss-codemods, the value adds up.

const process = createProcessor(removeNestingSelector);

it("should fold out dash ampersand rules", async () => {
  expect(
    await process(`
      .rule { 
        &-part1 {}
      }
    `)
  ).toMatchInlineSnapshot(`
    .rule {}
    .rule-part1 {}
  `);
});

2b. Custom Matchers as `MATCHER`

As I mentioned before, I really like snapshot tests, but sometimes you want to avoid test behavior automatically changing too easily with a simple command (jest --update). We can write our own custom matcher using Jest's expect.extend to achieve the same matching without the automatic update behavior of snapshot tests.

function toMatchCSS(result, css) {
  const expected = serializeCSS(css);
  const received = serializeCSS(result.css);

  return {
    pass: expected === received,
    message: () => {
      const matcher = `${this.isNot ? ".not" : ""}.toMatchCSS`;
      return [
        this.utils.matcherHint(matcher),
        "",
        this.utils.diff(expected, received),
      ].join("\n");
    },
  };
}

expect.extend({ toMatchCSS });

The matcher function uses the same serializeCSS function to format RECEIVED and EXPECTED CSS and Jest's this.utils, which provides helpers for writing matchers:

this.utils.matcherHint returns a string representing the failed test to help identify what failed.
this.utils.diff performs a string diff to identify the difference between the expected and received results.

We can use the custom matcher in the same way as the inline snapshots.

it("should fold out dash ampersand rules", async () => {
  expect(
    await process(`
      .rule { 
        &-part1 {}
      }
    `)
  ).toMatchCSS(`
    .rule {}
    .rule-part1 {}
  `);
});

An example of a failed test:

expect(received).toMatchCSS(expected)

- Expected
+ Received

- .rule {}
- .rule-part1 {}
+ .rule {
+   &-part1 {}
+ }

Snapshots vs. Matchers

Using a snapshot or custom matcher is a personal choice, but here are some heuristics to help you decide.

Snapshot tests are faster to write and work well as regression tests when you know your system already behaves well. They can update automatically, so they're well suited to rapidly changing behavior in tests as long as the snapshot is small enough to review.

Custom matchers are more explicit and can support a more diverse set of checks. They work well when you want to confirm the behavior of a small part of the whole. Matchers also won't change without manual editing, so the risk of unintentional changes is lower.

Conclusion

By extracting boilerplate and writing Jest extensions for PostCSS, we're able to simplify individual tests, focusing more on the test subject and expected behavior.

PostCSS's clear API makes serializers and matchers the ideal tools for cleaning up these tests. Pulling these test extensions out of scss-codemods and into jest-postcss can help others write tests for their PostCSS plugins.

I hope you enjoyed this post, and let me know in the comments how you're making Jest extensions work for you!

Appendix: Making Jest Extensions Production-Ready

This is a bonus section in case you're interested in publishing your own Jest extensions and need to write tests for them.

Testing Matchers

Testing serializers and matchers is a little tricky. We are inverting the relationship of our tests - writing plugins to test matchers, instead of matchers to test plugins. For cases when RECEIVED matches EXPECTED, it's as simple as writing a test that passes, but we also need to ensure the matcher provides helpful hints when they don't match.

Error: Task Failed Successfully

To test this behavior, we need to verify the error the matcher returns. Wrapping the failing expect in a expect(() => {...}).rejects or a try/catch block resolves this issue.

// We're testing a failure with an identity plugin  for simplicity
const process = createProcessor({
  postcssPlugin: "identity",
  Once() {},
});

it("should fail with a helpful message", async () => {
  expect(async () => {
    expect(
      await process(`
        .rule { 
          &-part1 {}
        }
      `)
    ).toMatchCSS(`
      .rule {}
      .rule-part1 {}
    `);
  }).rejects.toMatchInlineSnapshot(`
    [Error: expect(received).toMatchCSS(expected)

    - Expected
    + Received

    - .rule {}
    - .rule-part1 {}
    + .rule {
    +   &-part1 {}
    + }]
  `);
});

This test confirms the inner expect throws an error matching the desired format, ensuring that the matcher provides helpful feedback to developers when tests using it fail.

DEV Community: Devin Witherspoon

Demystifying NPM Scripts

What Are These Scripts?

package.json

Meet PATH

What Does This Mean?

Other Highlights

Aliases

Lifecycle Operations

Command Arguments

Conclusion

Surviving Performance Review Season

Documenting

Self Review

Gathering Information

Writing The Review

What Did You Do well?

What Can You Improve On?

Rate Yourself

Ask a Peer to Review It

Peer Reviews

Gathering Information

Writing the Review

What did your peer do well?

What Could Your Peer Improve on?

Additional Notes

Conclusion

Everything's More Complex Than it First Appears

Future Proofing

PostCSS to the Rescue!

Step 1: This Should be Easy, Right?

Step 2: Okay, Let's Fix That One Bug

Step 3: Time For Some Structure

Verifying

All the Bugs So Far

Learnings Re-Learnings

dcwither / scss-codemods

SCSS codemods written with postcss plugins

scss-codemods

Installation

Globally via npm

Running on-demand

union-class-name

Usage

Options

--reorder

Hobbies Make Me a Better Engineer

Writing

Photography

Running

Conclusion

Fighting Misery

Identifying and Maintaining Feelings

Achievement and Gratitude

Cognitive Behavioral Therapy (CBT) Journaling

Exercise

Intervening

Tell Someone I'm Struggling

Work Through Guilt

Find Something I Can Do

Build Accountability

Conclusion

Typography: Separating Style from Semantics

Heading Hierarchy

Styles > Hierarchy

Fight Work with Design to Make Styles = Hierarchy

Styling Elements Independent from Semantics

Existing Implementations

Conclusion

Appendix: Automated Heading Tags

My Dev.to Writing Process

The Setup

File Structure

Package.json

VSCode

The Process

Ideas 💡

Structure 🏗

First Draft 📝

Read Through 👀

`package.json`

Meet `PATH`

Globally via `npm`

`union-class-name`

`--reorder`

`useDateTime`

2a. Snapshot Serializers as `MATCHER`

2b. Custom Matchers as `MATCHER`