Automating tests can save time and improve quality in modern software development, and using Storybook, a tool that allows developers to build and showcase UI components in isolation, is a popular approach to testing React components.
Getting Started with Loki.js
You can either follow the official documentation , or you can continue reading this article, as we provide step-by-step instructions based on the official documentation.
Installation and Configuration
To install Loki.js, you can use either yarn or npm. Here are the commands to run:
for yarn run :
# for yarn
yarn add loki --dev
yarn loki init
# for npm
npm i --dev loki
npx loki init
After running the loki init command, you should see something like this:
loki init v0.31.1
Adding loki defaults to package.json
This will add a loki object to your package.json file, containing default configurations for running Loki.js tests. However, it is recommended to move this configuration to a separate loki.config.js file, in order to keep your package.json clean. Here's an example loki.config.js file:
module.exports = {
configurations: {
'chrome.laptop': {
target: 'chrome.docker',
width: 1366,
height: 768,
deviceScaleFactor: 1,
mobile: false,
},
'chrome.iphone7': {
target: 'chrome.docker',
preset: 'iPhone 7',
},
},
};
With this configuration file, you can customize the test configurations for different devices and browsers, and easily maintain them separately from your package.json.
Usage
Once you have installed and configured Loki.js, you can start using it for visual regression testing in your Storybook project. Here are the basic commands to run:
Updating Image References
To update the reference images for your components, run:
yarn loki update
Running Tests
To test your components for any visual changes, run:
yarn loki test
// or
npx loki test
This will compare the current state of your components with the reference images, and generate a report of any visual differences found.
Approving Visual Changes
If you want to accept any visual changes as the new reference images, run:
yarn loki approve
# or
npx loki approve
This will update the reference images to match the current state of your components. Note that this should be done only after carefully reviewing the changes and confirming that they are intentional.
Configuring Git LFS
When using Loki.js with Storybook, images will be generated for every component, potentially for different devices depending on your Loki configuration. This can quickly make your repository large, slowing down cloning and fetching. To keep your repo optimized and at a manageable size, we recommend using Git LFS. Git LFS is a Git extension that manages large files like images separately, improving performance and reducing storage requirements.
To use Git LFS with your repository, you'll first need to install it by following the instructions on the Git LFS website. Once Git LFS is installed, you can enable it for your repository by running the following command:
git lfs install
Next, you'll need to configure Git LFS to manage the file types you want it to handle. in our case we run
git lfs track "*.png"
After adding new file types to Git LFS, make sure to add the updated .gitattributes file to your repository by running:
git add .gitattributes
configure Gitlab Ci
In order to ensure that our Loki tests provide consistent results across different environments, we need to run them in the same environment as our local setup. The default Docker image used by Loki, yukinying/chrome-headless-browser-stable, doesn't have Node installed. Therefore, we need to change this to markhobson/node-chrome.
To configure our GitLab CI pipeline to use the same Docker image, we can add a new job to our .gitlab-ci.yml file:
loki:
image: markhobson/node-chrome
stage: test
script:
- npx yarn
- npx yarn build-storybook --quiet
- npx http-server storybook-static --port 6006 --silent & npx wait-on tcp:6006 && npx yarn loki test
artifacts:
when: on_failure
paths:
- .loki
This job installs the required dependencies, builds the Storybook, starts a local server, waits for it to be available, and finally runs the Loki tests. The .loki directory containing the generated images will be saved as an artifact in case the tests fail.
To run Loki in the same environment as our GitLab CI, we need to update our local Loki configuration to use the markhobson/node-chrome Docker image. We can do this by creating Dockerfile.loki
# Dockerfile.loki
FROM markhobson/node-chrome
WORKDIR /app
RUN npm init -y
RUN npm i loki http-server wait-on
CMD ["sh","./test-visual-regression.sh"]
The test-visual-regression.sh script contains the commands needed to run Loki:
#!/bin/bash
npx http-server storybook-static --port 6006 --silent & npx wait-on tcp:6006 && npx yarn loki test
then we will excute this commands
# Build the Docker image
docker build -f Dockerfile.loki -t test-loki .
# Build the Storybook
npx yarn build-storybook --quiet
# Run the Docker container
docker run \
-v "$(pwd)/scripts/test-visual-regression.sh:/app/test-visual-regression.sh" \
-v "$(pwd)/loki.config.js:/app/loki.config.js" \
-v "$(pwd)/storybook-static:/app/storybook-static" \
-v "$(pwd)/.loki:/app/.loki" \
test-loki
These commands mount the necessary files and directories into the container and execute the test-visual-regression.sh script, which runs the Loki tests. The generated images will be saved in the .loki directory on the host machine.