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

Testing custom ESLint rules has similar benefits to testing a custom jscodeshift transform. First, taking a test-driven approach when creating custom rules can offer a faster feedback loop. The tests run significantly faster than trying to run them on an entire codebase. Second, if the rule is complex or shared across many different codebases, tests can help provide confidence that the rule is working as intended.

 directory, with an import for the rule and the 

// Import the custom rule definition.
const rule = require("./no-button-element");
// Import the utility provided by ESLint to test custom rules.
const { RuleTester } = require("eslint");

The rule tester uses the default ESLint configuration (not the one provided by Create React App) so any necessary configuration also needs to be passed to the 

 when initialized. By default, ESLint only expects ES5 syntax. In this case, only the 

 need to be specified to enable JSX support (eg: 

) otherwise the ESLint parser will throw an invalid syntax error.

// Initialize a new rule tester instance, with the default
// configuration to use for all test cases.
const ruleTester = new RuleTester({
  parserOptions: {
    ecmaFeatures: {
      // Enable support for JSX (eg: <button>)
      jsx: true,
    },
  },
});

Then, the test cases can be defined and run. The 

 to execute tests. It expects three arguments: the rule name, the rule definition, and test cases.

// Invoke the `run` method to run the tests cases for
// the given rule.
ruleTester.run(
  // The name of the rule.
  "no-button-element",
  // The custom rule definition itself.
  rule,
  // All test cases are contained in a single object
  // with two keys:
  //  - `valid`: code samples that should pass the
  //    linting rule (not trigger a linting error).
  //  - `invalid`: code samples that should not pass
  //    the linting rule (should trigger a linting error).
  //
  // Each test case (object) must have the `code` property
  // to run the rule on. There are several other options,
  // and many more for invalid test cases.
  //
  // See the docs for the full list: 
  //  https://eslint.org/docs/developer-guide/nodejs-api#ruletester
  {
    valid: [
      {
        // Missing `className`, so valid.
        code: "<button>Button</button>",
      },
      {
        // Missing "button" `className`, so valid.
        code: "<button className='custom-button'>Button</button>",
      },
      {
        // Already a `Button` component, so valid.
        code: "<Button className='button'>Button</Button>",
      },
      {
        // Not a `button` element, so valid.
        code: "<div className='button'>Button</div>",
      },
    ],
    invalid: [
      {
        // `button` element with a "button" `className`, so invalid.
        code: "<button className='button'>Button</button>",
        errors: [
          {
            message:
              'Found "button" element that should be "Button" component.',
          },
        ],
      },
      {
        // `button` element with a "button" `className`, so invalid.
        // This verifies the rule can handle multiple class names.
        code:
          "<button className='otherClassName button anotherClassName'>Button</button>",
        errors: [
          {
            message:
              'Found "button" element that should be "Button" component.',
          },
        ],
      },
    ],
  }
);

---
title: How to Test Custom ESLint Linting Rules With AST
description: Testing custom ESLint linting rules to verify they work as expected
privateVideoUrl: "https://fullstack.wistia.com/medias/ga71wnpusa"
code: https://gitlab.com/fullstackio/books/newline-course-apps/spencer-miskoviak-practical-abstract-syntax-trees-app/-/tree/main/code/module_06/lesson_06.03/App/flash-cards?ref_type=heads
---

# Testing custom linting rules

Testing custom ESLint rules has similar benefits to testing a custom jscodeshift transform. First, taking a test-driven approach when creating custom rules can offer a faster feedback loop. The tests run significantly faster than trying to run them on an entire codebase. Second, if the rule is complex or shared across many different codebases, tests can help provide confidence that the rule is working as intended.

## Testing a rule

To get started, create a new file `no-button-element.test.js` alongside the rule in the `eslint-rules` directory, with an import for the rule and the `RuleTester` utility from ESLint.

```javascript { actualFilename=./protected/flash-cards/eslint-rules/no-button-element.test.js endLine=4 startLine=1 statedFilename=no-button-element.test.js url=https&#x3A;//gitlab.com/fullstackio/books/practical-ast-and-codemods/module_06/lesson_06.03/protected/flash-cards/eslint-rules/no-button-element.test.js }
// Import the custom rule definition.
const rule = require("./no-button-element");
// Import the utility provided by ESLint to test custom rules.
const { RuleTester } = require("eslint");
```

The rule tester uses the default ESLint configuration (not the one provided by Create React App) so any necessary configuration also needs to be passed to the `RuleTester` when initialized. By default, ESLint only expects ES5 syntax. In this case, only the [parser options](https://eslint.org/docs/user-guide/configuring/language-options#specifying-parser-options) need to be specified to enable JSX support (eg: `<button>`) otherwise the ESLint parser will throw an invalid syntax error.

```javascript { actualFilename=./protected/flash-cards/eslint-rules/no-button-element.test.js endLine=15 startLine=6 statedFilename=no-button-element.test.js url=https&#x3A;//gitlab.com/fullstackio/books/practical-ast-and-codemods/module_06/lesson_06.03/protected/flash-cards/eslint-rules/no-button-element.test.js#L6 }
// Initialize a new rule tester instance, with the default
// configuration to use for all test cases.
const ruleTester = new RuleTester({
  parserOptions: {
    ecmaFeatures: {
      // Enable support for JSX (eg: <button>)
      jsx: true,
    },
  },
});
```

Then, the test cases can be defined and run. The `RuleTester` has a [`run` method](https://eslint.org/docs/developer-guide/nodejs-api#ruletester) to execute tests. It expects three arguments: the rule name, the rule definition, and test cases.

Spencer Miskoviak

Testing custom ES lint rules has similar benefits to testing the custom JS code

chint form. First, taking a test-driven approach when creating custom rules can

offer a faster feedback loop. The test runs significantly faster than trying to

run them on an entire codebase. Second, if the rules complex or shared across

many different code bases, tests can help provide confidence that the rule is

working as expected. To get started, we'll create a new file to test the no-

element linting rule alongside this rule in the ES lint rules directory. Then

Next, we'll require ES lint and specifically import the rule tester class.

The rule tester uses the default ES lint configuration, not the one provided by

create React app, so any necessary configuration also needs to be passed to

the rule tester when initialized. By default, ES lint only expects ES5 syntax.

In this case, only the parser option needs to be specified to enable JSX

support. Otherwise, the ES lint parser will throw an invalid syntax error.

Then, we can define test cases to run against our linting rule with this rule

tester. The rule tester has a run method to execute tests. It expects three

arguments. The first argument is the name of the rule.

The next argument is the rule definition, which we've already required. All

test cases are contained in a single object with two keys, valid and invalid.

Valid contains code samples that should pass the linting rule and not trigger

linting error, while invalid contains code samples that should not pass the

linting rule and therefore should trigger a linting error. Each test case is an

object that must have the code property to run the rule on. There are several

options and many more for invalid test cases. You can reference the docs for

full list of all of the test case options.

Now that we've defined a test case for our rule, we can run this test with node

There won't be any output if all of the tests pass.

We can confirm that this test is indeed working by moving an invalid case to

valid, or vice versa, and run the test again.

The error should then be printed to the console.

Let's switch back to our editor and make one of the valid test cases invalid.

Then back in the terminal, let's run the tests again.

We can see that the script now failed with the error message that we should

We can then undo this change to make our tests pass again.

If you're curious to see more complex examples of ESLint rule tests,

all the test cases for the included ESLint rules are in the GitHub repository.

Using tests like this can provide a faster feedback loop when creating custom

rules and validate that they're working as expected.

The Flash codebase has now been fully refactored, replacing button elements

and we've introduced a Linting rule to prevent future violations.

As we should now realize, there are countless practical uses for ASTs,

ranging from understanding the code to refactoring, Linting, and others,

such as formatting code with prettier or minifying code with tracer.

ASTs and the associated tooling can be jargon heavy and seem complex,

but with a basic understanding of what ASTs are, along with some of the terms

we can unlock a whole new range of skills.

Next time you're faced with a refactor or similar problem in a large codebase,

consider if ASTs might be the right tool for the job.