Course overview

Introduction

Understand the basics of an AST and how it relates to real-world code

What is an Abstract Syntax Tree? Visualizing Code Like a Compiler

Looking at an example code snippet and how it relates to the resulting AST

How to View Abstract Syntax Tree Code With AST Explorer

An overview of the tooling available in the web frontend (JavaScript) ecosystem that rely on ASTs

The Best JavaScript AST Tools - ESLint, Babel, Terser, and More

A quick overview of the basic environment setup used throughout this course

Environment setup

Understanding Abstract Syntax Trees (AST)

Exploring tools to convert (or parse) JavaScript into a real AST

How to Generate a JavaScript AST With Babel Plugins

Programmatically traverse an AST and visit arbitrary nodes

Traversing an AST With Babel Traverse

Add Type Safety and Prevent Runtime Errors With AST

Working with Abstract Syntax Trees

A practical example of needing to perform a code audit (static analysis) to understand the current state of a codebase

Practical code audits

Create a custom script to audit a codebase

How to Audit Your Code With AST Programming

Introduce a shared Button component to replace all existing button elements

How to Add a Component and Update an AST

A rough formula to determine when to use AST-based tooling

When to Use Abstract Syntax Tree Tooling to Refactor at Scale

Code Audits

Transforming code in place by mutating an AST

How to Mutate an AST and Automatically Replace Code Components

Using jscodeshift to make the same code transformations with less boilerplate

How to Create Codemods Using jscodeshift

Create tests for jscodeshift transforms for a faster feedback loop

How to Unit Test jscodeshift Transforms With ts-jest

Codemods

Implement a linting rule to prevent the code we just transformed from being reintroduced in the future

How to Ensure Codebase is Up to Date With Linting Rules

Use ESLint to create the same linting rule for the code with less boilerplate

How to Use ESLint to Create AST Rules With Babel Traverse

Testing custom ESLint linting rules to verify they work as expected

How to Test Custom ESLint Linting Rules With AST

Linting

In this course, we'll start with the fundamentals of abstract syntax trees (ASTs) and learn the basic mental models. This general AST knowledge can be translated to almost any tool that works with ASTs.

## Why this course?

Understanding and using ASTs unlocks the ability to make sweeping changes in a safe and reliable way in any size codebase.

## Course topics

Throughout this course, we'll have converted source code into ASTs, traversed, mutated, and generated ASTs. With these concepts we'll then explore several practical applications including things like code audits (static analysis), code transformations (codemods), and linting.

### Module 1

We'll learn the fundamentals of abstract syntax trees. 

- What is an AST?
- How to explore an AST
- Examples of JavaScript tools that work with ASTs

### Module 2

We'll learn how to work with ASTs.

- How to turn code into an AST
- How to programmatically navigate any AST 
- How to leverage TypeScript to prevent runtime errors

### Module 3

We'll learn how to statically analyze, or "audit" code to understand the state of the codebase using abstract syntax trees.

- An introduction to an example codebase and refactor
- Understanding the state of the current codebase
- When to use an AST-based tool versus doing something manually

### Module 4

We'll learn how to transform, or "codemod" code from one state to another using abstract syntax trees.

- How to make changes to an AST
- How to change ASTs with [jscodeshift](https://github.com/facebook/jscodeshift)
- How to test a code transform

### Module 5

We'll learn how to write rules, or "lint" code using abstract syntax trees.

- How to create rules for code
- How to create custom rules with [ESLint](https://eslint.org)
- How to test a rule

In this course, you'll learn the fundamentals of abstract syntax trees, what they are, how they work, and dive into several practical use cases of abstract syntax trees to maintain a JavaScript codebase.

Practical Abstract Syntax Trees

JavaScript tools that work with abstract syntax trees

How to parse, traverse, and generate abstract syntax trees

Practical skill set for maintaining large JavaScript codebases

When working on a transform, it likely only needs to be run once on a codebase, unless it's intended to be reused multiple times. For example, the 

 package is a set of transforms to help update React APIs. These transforms are intended to be run on many codebases.

 transforms are a good example of when testing can be helpful, since they'll be run on many codebases. However, even if a transform is only intended to be run once on your codebase, writing tests can be a good way to streamline development.

The process we've been using up to this point has been to work on the transform, run it on the codebase, undo the changes (

), and repeat. The test helpers from jscodeshift can help turn this into a more automated test-driven development process, and make the iteration much faster by removing the need to run it on the codebase and undo the changes.

Let's continue with the same jscodeshift transform from the previous lesson. We can start by creating new directories for the test cases and test fixtures.

# Create a new directory for the tests in
# the existing `jscodeshift` directory
mkdir __tests__

# Create another new directory for the test fixture
# data also in the `jscodeshift` directory
mkdir __testfixtures__

The test utils require these exact directory names. They also require the tests be written with 

, a popular JavaScript testing framework. The tests can be written in JavaScript or TypeScript. Since the transform is TypeScript, it makes sense to also write the tests in TypeScript.

. There are tradeoffs with either approach, but the babel approach only transpiles and doesn't perform any type-checking. The 

 package is a bit easier to set up, and also performs type-checking. Either approach will work, but let's install the necessary dependencies to get 

# Install dependencies to run Jest with TypeScript
npm i -D jest typescript ts-jest @types/jest

# Initialize ts-jest configuration, this should
# create a `jest.config.js` file.
npx ts-jest config:init

Now, with the test tooling set up, it's time to add a test. Create a new 

import { defineTest } from "jscodeshift/dist/testUtils";

// This is a test helper provided by jscodeshift.
defineTest(
  // The current directory. This is used to automatically
  // load the transform and test fixtures.
  __dirname,
  // The name of the transform's filename (excluding extension).
  "transform",
  // Transform options. These are the custom options the transform
  // expects. This transform didn't use any custom options.
  null,
  // The name of the test fixtures. This will be suffixed with
  // input and output, including the extension.
  "basic",
  // Jscodeshift options. We've been running via the
  // jscodeshift CLI with the `--parser babylon` flag passed,
  // so also passing that when running the tests.
  { parser: "babylon" }
);

In this case, we'll have one test file because there's one transform.

The test fixtures will contain input and output pairings, and there can be as many as needed. The test currently expects test fixtures with the name 

The input will be what is passed into the transform, and the 

 helper will assert the transform output matches the test fixture output.

const button = (
  <button className="button button--secondary">
    <span role="img">📝</span> Sign up
  </button>
);

import { Button } from "../../flash-cards/src/components/Button/Button.js";
const button = (
  <Button variant="secondary">
    <span role="img">📝</span> Sign up
  </Button>
);

---
title: How to Unit Test jscodeshift Transforms With ts-jest
description: Create tests for jscodeshift transforms for a faster feedback loop
privateVideoUrl: "https://fullstack.wistia.com/medias/p4euni1ii4"
code: https://gitlab.com/fullstackio/books/newline-course-apps/spencer-miskoviak-practical-abstract-syntax-trees-app/-/tree/main/code/module_05/lesson_05.03/App/jscodeshift?ref_type=heads
---

# Testing a transform

When working on a transform, it likely only needs to be run once on a codebase, unless it's intended to be reused multiple times. For example, the [`react-codemod`](https://github.com/reactjs/react-codemod) package is a set of transforms to help update React APIs. These transforms are intended to be run on many codebases.

The `react-codemod` transforms are a good example of when testing can be helpful, since they'll be run on many codebases. However, even if a transform is only intended to be run once on your codebase, writing tests can be a good way to streamline development.

The process we've been using up to this point has been to work on the transform, run it on the codebase, undo the changes (`git reset`), and repeat. The test helpers from jscodeshift can help turn this into a more automated test-driven development process, and make the iteration much faster by removing the need to run it on the codebase and undo the changes.

## Adding unit tests

Let's continue with the same jscodeshift transform from the previous lesson. We can start by creating new directories for the test cases and test fixtures.

```bash
# Create a new directory for the tests in
# the existing `jscodeshift` directory
mkdir __tests__

# Create another new directory for the test fixture
# data also in the `jscodeshift` directory
mkdir __testfixtures__
```

The test utils require these exact directory names. They also require the tests be written with [Jest](https://jestjs.io/docs/getting-started), a popular JavaScript testing framework. The tests can be written in JavaScript or TypeScript. Since the transform is TypeScript, it makes sense to also write the tests in TypeScript.

This [requires some extra setup](https://jestjs.io/docs/getting-started#using-typescript), with either babel or [`ts-jest`](https://github.com/kulshekhar/ts-jest). There are tradeoffs with either approach, but the babel approach only transpiles and doesn't perform any type-checking. The `ts-jest` package is a bit easier to set up, and also performs type-checking. Either approach will work, but let's install the necessary dependencies to get `ts-jest` working.

```bash
# Install dependencies to run Jest with TypeScript
npm i -D jest typescript ts-jest @types/jest

# Initialize ts-jest configuration, this should
# create a `jest.config.js` file.
npx ts-jest config:init
```

Now, with the test tooling set up, it's time to add a test. Create a new `transform-test.ts` file in the `__tests__` directory.

```typescript { actualFilename=./protected/jscodeshift/\_\_tests\_\_/transform-00-test.ts endChar=763 endLine=21 startChar=0 startLine=1 statedFilename=\_\_tests\_\_/transform-test.ts url=https&#x3A;//gitlab.com/fullstackio/books/practical-ast-and-codemods/module_05/lesson_05.03/protected/jscodeshift/\_\_tests\_\_/transform-00-test.ts }
import { defineTest } from "jscodeshift/dist/testUtils";

// This is a test helper provided by jscodeshift.
defineTest(
  // The current directory. This is used to automatically
  // load the transform and test fixtures.
  __dirname,
  // The name of the transform's filename (excluding extension).
  "transform",
  // Transform options. These are the custom options the transform
  // expects. This transform didn't use any custom options.
  null,
  // The name of the test fixtures. This will be suffixed with
  // input and output, including the extension.
  "basic",
  // Jscodeshift options. We've been running via the
  // jscodeshift CLI with the `--parser babylon` flag passed,
  // so also passing that when running the tests.
  { parser: "babylon" }
);
```

In this case, we'll have one test file because there's one transform.

The test fixtures will contain input and output pairings, and there can be as many as needed. The test currently expects test fixtures with the name `basic` suffixed with `.input` and `.output` along with the extension which will be `.js` in this case.

Next, add these two files in `__testfixtures__`: `basic.input.js` and `basic.output.js`.

### Basic case

The input will be what is passed into the transform, and the `defineTest` helper will assert the transform output matches the test fixture output.

#### Input

```javascript { actualFilename=./protected/jscodeshift/\_\_testfixtures\_\_/basic.input.js endChar=119 endLine=6 startChar=0 startLine=1 statedFilename=\_\_testfixtures\_\_/basic.input.js url=https&#x3A;//gitlab.com/fullstackio/books/practical-ast-and-codemods/module_05/lesson_05.03/protected/jscodeshift/\_\_testfixtures\_\_/basic.input.js }
const button = (
  <button className="button button--secondary">
    <span role="img">📝</span> Sign up
  </button>
);
```

#### Output

```javascript { actualFilename=./protected/jscodeshift/\_\_testfixtures\_\_/basic.output.js endChar=178 endLine=7 startChar=0 startLine=1 statedFilename=\_\_testfixtures\_\_/basic.input.js url=https&#x3A;//gitlab.com/fullstackio/books/practical-ast-and-codemods/module_05/lesson_05.03/protected/jscodeshift/\_\_testfixtures\_\_/basic.output.js }
import { Button } from "../../flash-cards/src/components/Button/Button.js";
const button = (
  <Button variant="secondary">
    <span role="img">📝</span> Sign up
  </Button>
);
```

Spencer Miskoviak

When working on a transform, it likely only needs to be run once on a codebase,

unless it's intended to be reused multiple times. For example, the React

CodeMod package is a set of transforms to help update React APIs across

The React CodeMod transforms are a good example of when testing can be helpful,

since they'll be run on many codebases. Even if a transform is only intended to

be run once on your codebase, writing tests can be a good way to streamline

development. The process we've been using up to this point has been to work on

the transform, run it on the codebase, undo the changes using getReset and

repeat. The test helpers from JS codeshift can help turn this into a more

automated test-driven development process, and make the iteration much

faster by removing the need to run it on the codebase and undo the changes.

Let's continue with the same JS codeshift transform from the previous lesson.

can step by creating two new directories for the test cases and test fixtures.

JS codeshift test utilities require these exact directory names. They also

require the types be written with Jest, a popular JavaScript testing framework.

The test can be written in JavaScript or TypeScript, but since the transforms

written in TypeScript, it makes sense to also write the tests in TypeScript.

requires some extra setup with either Babel or TS Jest. There are trade-offs

with either approach, but the Babel approach only transpiles and doesn't

perform any type checking. The TS Jest package is a bit easier to set up and

also performs type checking. Either approach would work, but let's install

the necessary dependencies to get TS Jest working. We can then initialize TS J

Now with the test tooling setup, it's time to add a test. Create a new

transform-test.ts file in the test directory. We can then import the

define test helper from the JS codeshift test utils. The JS codeshift types don

declare the define test helper, so using a require instead of an import will

around any of those type issues. The define test helper takes several

arguments. The first argument is the current directory. This is used to

automatically load the transform in test fixtures. The second argument is the

name of the transform's file name, excluding the extension. In this case, it's

named transform. The third argument is any options for the transform. We don't

have any options, so we can pass an all. The fourth argument is the name of the

test fixtures. This will be suffixed with either input or output, including the

extension. For now, let's call it basic. In filing the last argument, our JS

options will set the parser to Babel on. In this case, we'll have one test file

because there's one transform. However, the test fixtures will contain input

output pairings, and there can be as many as needed. The test currently expects

test fixtures with the name basic, suffix with dot input and dot output, along

the extension which will be dot JS in this case. Next, let's add these two

and test fixtures. The input will be what is passed into the transform, and the

define test helper will assert the transform output matches the test fixture

output. For the basic input, we defined a button element with the button class

name in the secondary class variant. For the output, we've included the button

import, along with the transform button component in variant prop. Next, we can

update the test script in package dot JSON to instead run the just package. Now

back on our terminal, we can run npm test and pass the watch options to

just. We can see that the test passed. Let's try updating the input to have a

We can now see that the test fails, since we changed the input and didn't

update the output to reflect that. This basic test case confirms that the

transform works for converting the secondary button into the equivalent

component, but there are a number of other cases missing. Let's add three more

test cases. One, testing props with all default values. One, testing props with

default values, so all the props, and finally a more complex transformation. We

For the default input case, we define props on the button element that are the

default values for the button component. The output therefore doesn't require

props. The all props case is the opposite of the default case, where all props

defined with non-default values. The output therefore requires all props passed

with a value. The complex case is done to verify that custom button elements

don't have the button class name aren't transformed. It also verifies it can

transform nested elements. We can switch back to the terminal to see that all

the tests are passing. For the most part, these four test cases cover most of

logic and edge cases of this transform. In practice, this test-driven approach

creating a transform can be helpful for large complex transforms. An approach

this can work well when working on custom transforms. First, define some test

cases, then updating the transform until it pass all those tests, then run it

the codebase, and if there are any new issues go back to step one and redefine

those test cases, otherwise the transform is complete. When running a quick one

transform, it might not be necessary to create tests for the transform itself,

since the changed code can be reviewed and verified once. Now that the code has

been fully migrated to the new button component, it would be ideal to prevent

anyone adding button elements in the future instead of button components. The

next module will explore how to ensure the codebase remains up-to-date.