Course overview

Introduction

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

How to View Abstract Syntax Tree Code With AST Explorer

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

Environment setup

Understanding Abstract Syntax Trees (AST)

How to Generate a JavaScript AST With Babel Plugins

Traversing an AST With Babel Traverse

Add Type Safety and Prevent Runtime Errors With AST

Working with Abstract Syntax Trees

Practical code audits

How to Audit Your Code With AST Programming

How to Add a Component and Update an AST

When to Use Abstract Syntax Tree Tooling to Refactor at Scale

Code Audits

How to Mutate an AST and Automatically Replace Code Components

How to Create Codemods Using jscodeshift

How to Unit Test jscodeshift Transforms With ts-jest

Codemods

How to Ensure Codebase is Up to Date With Linting Rules

How to Use ESLint to Create AST Rules With Babel Traverse

How to Test Custom ESLint Linting Rules With AST

Linting

node.js

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"
---

# 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_04/lesson_04.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_04/lesson_04.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_04/lesson_04.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>
);
```

Create tests for jscodeshift transforms for a faster feedback loop

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Practical Abstract Syntax Trees

Module 1: Introduction

Introduction:

Start Here

Introduction: (2:27)

Course overview

Module 2: Understanding Abstract Syntax Trees (AST)

Lesson 1: (5:55)

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

Lesson 2: (4:21)

How to View Abstract Syntax Tree Code With AST Explorer

Lesson 3: (1:46)

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

Lesson 4: (1:03)

Environment setup

Module 3: Working with Abstract Syntax Trees

Lesson 1: (6:29)

How to Generate a JavaScript AST With Babel Plugins

Lesson 2: (7:33)

Traversing an AST With Babel Traverse

Lesson 3: (9:31)

Add Type Safety and Prevent Runtime Errors With AST

Module 4: Code Audits

Lesson 1: (2:35)

Practical code audits

Lesson 2: (15:29)

How to Audit Your Code With AST Programming

Lesson 3: (2:32)

How to Add a Component and Update an AST

Lesson 4: (1:43)

When to Use Abstract Syntax Tree Tooling to Refactor at Scale

Module 5: Codemods

Lesson 1: (21:13)

How to Mutate an AST and Automatically Replace Code Components

Lesson 2: (10:03)

How to Create Codemods Using jscodeshift

Lesson 3: (5:55)

How to Unit Test jscodeshift Transforms With ts-jest

Module 6: Linting

Lesson 1: (8:44)

How to Ensure Codebase is Up to Date With Linting Rules

Lesson 2: (5:31)

How to Use ESLint to Create AST Rules With Babel Traverse

Lesson 3: (4:31)

How to Test Custom ESLint Linting Rules With AST

How to Unit Test jscodeshift Transforms With ts-jest