Set Up Jest Testing Framework
Learning Objectives
After completing this unit, you'll be able to:
- Describe the Jest test framework.
- Describe the role of Node.js and npm.
- Install Node.js and npm.
- Install the @salesforce/sfdx-lwc-jest JavaScript module in a Salesforce DX project.
Before You Begin
To complete this module, you need Salesforce CLI, Visual Studio Code, and Salesforce Extensions for Visual Studio Code installed and updated. To fulfill these prerequisites, we recommend that you complete the Quick Start: Salesforce DX, Quick Start: Visual Studio Code for Salesforce Development, and Quick Start: Lightning Web Components projects before you go on.
We're taking a test-driven development (TDD) approach, where we'll write the Jest test before we write the component that it tests. Because of this, each test will initially fail. Then we'll update the component to get the Jest test to pass.
Create a Salesforce DX Project
The first step before testing is to create a Salesforce DX project to store your Lightning web components and Jest tests.
- In Visual Studio Code, open the Command Palette by pressing Ctrl+Shift+P (Windows) or Cmd+Shift+P (macOS).
- Enter
sfdx
. - Select SFDX: Create Project. If you don't see this option, complete the prerequisites from this module's first unit before you go on.
- Select Standard.
- Enter
test-lwc
as the project name. - Press Enter.
- Select a folder to store the project.
- Click Create Project and wait for the new Visual Studio Code window to open.
- Click View, then choose Terminal. This opens a terminal window inside Visual Studio Code. The terminal defaults to the top-level directory of the project. You need the terminal later to run commands in the working directory of this project.
What Are Node.js and npm?
Node.js is a JavaScript runtime built on Chrome's V8 JavaScript engine and npm is a package manager for distributing reusable code modules. In the universe of Node.js and npm, these reusable code modules are known as Node modules. In Salesforce terminology, a Node module—reusable code that can be easily distributed to multiple projects—is similar to unlocked packages.
Node.js and npm are popular tools in a modern JavaScript developer's toolbox. Learn more about modern JavaScript in the Learn to Work with JavaScript trail.
Install Node.js and npm
Jest is a Node module, so to use it you need to install Node and npm. Let's do that now.
- Install Node.js from https://nodejs.org/en/download/. We recommend using the LTS (long-term support) version.
- Confirm Node.js is installed. In the Visual Studio Code terminal we opened earlier, enter the following command.
node --version
You should see output likev16.13.0
or a later version. - When you install Node.js, npm also installs automatically.
In a terminal, enter the following command.npm --version
You should see output like8.1.0
or a later version. It's a good idea to keep npm updated.
What Is Jest?
Jest is a powerful tool with rich features for writing JavaScript tests. Jest can collect code coverage information and supports mocking to help isolate tests from complex dependencies. Jest tests don't run in a browser or connect to an org, so they run fast. Use Jest to write unit tests for all of your Lightning web components. To run Jest tests for Lightning web components, you need the @salesforce/sfdx-lwc-jest Node module in your Salesforce DX project.
Install sfdx-lwc-jest Node Module
The @salesforce/sfdx-lwc-jest Node module lets you write, run, and debug Jest tests for Lightning Web Components. The Salesforce CLI makes it easy to install Jest and its dependencies into the project.
- Confirm the CLI is properly installed and on the latest version by running the following command from the command line.
sf update
You should see output likecli: Updating CLI...
. - In the Visual Studio Code terminal, run the following command in the top-level directory of your Salesforce DX project:
sf force lightning lwc test setup
This installs npm and @salesforce/sfdx-lwc-jest into the project. Results should look like this:
You may notice the process finds some vulnerabilities. For our purposes that's fine. These are not the vulnerabilities you are looking for.
Run Jest Tests
Excellent, you set up your Salesforce DX project to be able to run the Jest tests that you write later in this module. There are several ways to run the Jest tests now that everything is set up. You can call the script directly, use npm commands, or you can use clicks in Visual Studio Code. You can run one test or all tests in a file or project. You can even run tests automatically when the code the test covers is changed.
Let's take a look at the different ways you can run Jest tests.
The sfdx-lwc-jest Node Command
You can run the script directly from where it was installed in the project using the following Node command.
- In the Visual Studio Code terminal, in the top-level directory of the Salesforce
DX project, enter the following command.
node node_modules/@salesforce/sfdx-lwc-jest/bin/sfdx-lwc-jest
There are no Jest tests yet so you should see output likeNo tests found, exiting with code 1
.
That's a great start, but let's look at how we can make it even better with automation.
Automate Test Scripts with Package.json and npm
A goal of having unit tests is to promote developers to write and run them as part of their development and continuous integration process so that bugs are identified and fixed sooner rather than later. Having to remember and type long commands like the one above over and over is counterproductive to your goal. Here's where automation comes in.
npm has some great out-of-the-box script automation flexibility. Running the install earlier added a series of options to the scripts
property of the package.json file at the root of your project.
{ "name": "test-lwc", ... "scripts": { ... "test:unit": "sfdx-lwc-jest", "test:unit:watch": "sfdx-lwc-jest --watch", "test:unit:debug": "sfdx-lwc-jest --debug", "test:unit:coverage": "sfdx-lwc-jest --coverage", ... }, ...}
If you want to run all tests for your project, run this npm command from the base directory of your project.
npm run test:unit
If you want to run tests in a specific directory, using the command above in a specific directory will run only the tests in that directory. This allows you to isolate what you are testing.
Run Tests Continuously During Development
For this option, Node relies on Git to “watch” the code. To use this option, be sure to have Git initialized for your project. To run all tests for a single component every time you save changes, change directories to the component directory and run the npm command below that utilizes sfdx-lwc-jest with the --watch
parameter. As mentioned above you could also run this from the base of the project and have all tests in the project run for every change.
npm run test:unit:watch
Jest now watches all component files for updates and runs all relevant tests every time it detects a change.
Run Tests in Jest Debug Mode
Running Jest tests in debug mode is useful if you want to step through your tests and app code to find out why your tests or code aren't behaving as expected. You can debug Jest tests using the following tools.
- Visual Studio Code Salesforce Extension Pack
- Chrome Developer Tools
- Visual Studio Code debugger advanced configuration
The Visual Studio Code Salesforce Extension Pack provides the simplest and most straightforward option, while Chrome DevTools caters to seasoned web developers. Additionally, the advanced configuration for the VS Code debugger enables you to work with different debuggers and debugging scenarios. The advanced configuration offers the most flexible option for debugging your Jest tests.
For more information, see Debug Jest Tests for Lightning Web Components or for information about troubleshooting Jest issues, see Jest: Troubleshooting.
Run Tests and Display Code Coverage
To see the code coverage of the tests, use the --coverage
option below.
npm run test:unit:coverage
Run Tests with Clicks in Visual Studio Code
The Salesforce Visual Studio Code extensions give a lot of control and visual feedback for running Jest tests. It gives you options to run single, multiple, or all tests. It also gives you the ability to use the --watch
option on a file since Git is preinstalled in Visual Studio Code.
Click the test beaker icon to open the Test sidebar. If you don't see the icon, then you may need to create a new SFDX project. In the Test sidebar there is an LWC Tests section that displays any Jest tests that are in the project. Here is what the test sidebar looks like with tests in your project.
Click the play button to run a test or multiple tests in a project. Hover your cursor over the directory or individual test to display the play button. When a test runs, the results display in the terminal. The results are also indicated by color in the sidebar. Green means passing. Blue indicates not run, orange shows a skipped test, and red indicates a failing test. Clicking the test in the sidebar opens the file and takes you right to that test.
Click the refresh icon to clear the test results.
There are also direct controls in the test file view.
Click the play button in the main toolbar to run all the tests in the file. You can also click Run Test above each test in the file to run that specific test.
To run all the tests in the file every time you save changes, click the watch icon in the main toolbar. It's a great option to use when you are working on tests in the file.
Wow! That's a lot to take in.
Alright, let's write some tests.
Resources
- Developer Guide: Test Lightning Web Components
- Salesforce Blog: Unit Test Lightning Web Components with Jest
- Salesforce Extensions for VS Code: Test Lightning Web Components
- External Site: Node.js: Downloads
- External Site: npm: @salesforce/sfdx-lwc-jest
- External Site: npm: Using a package.json
- External Site: npm: package.json
- External Site: Jest: Getting Started
- External Site: Jest: Configuration
- External Site: Jest: Troubleshooting
- External Site: Wikipedia: Test-Driven Development