Throughout this course,
we have emphasized the importance of writing tests for functionality
instead of looks and other stylistic choices.
However, there are scenarios in which it is important to ensure
the application visuals aren't being changed too much.
One way for us to achieve this protection is by writing visual regression tests.
For the sake of simplifying this lesson,
I have already pre-configured our Wordle project
to support end-to-end tests via Cypress.
You can pull this project at this point by using the link in the description.
But let me give you a quick rundown on how I've set up Cypress in it.
I started by installing Cypress as a dev dependency.
And then I created a script called test-e2e,
which runs cypress open.
Since our project didn't have Cypress yet,
Cypress has provided us with a quick wizard to pre-configure an example test.
I went with component tests
because I wanted to write a quick visual regression test
for our WordleBoard.
Since our project is using TypeScript, I also wanted to provide support for it.
This could be achieved by placing a tsconfig.json file
in our Cypress folder.
Notice the type of Cypress in our compiler options.
I then updated the placeholder tests
that Cypress has provided with an end-to-end test
that ensures the display message is displayed
when the user makes a correct guess.
If you see this, this is the test that we have right now.
We have a user typing all the different guesses,
and then Cypress is ensuring
that the message congratulations is rendered to the screen.
Okay, so now we are at a point
where we can run a regular Cypress component test.
Now let's turn this test into a visual regression test.
One way for us to achieve this
is by installing the Cypress Image Snapshot plugin.
The link for this package is also in the description.
To install the package,
we can do pnpm i -D to install it as a dev dependency,
and then the package itself,
which is simonsmith/cypress-image-snapshot
Okay, now we need to add this plugin to our cypress-config.ts.
And you can see over here
that these are the configurations for the component tests,
which is all we have.
And to plug that plugin,
we can just use the setupNodeEvents callback,
and call the add imageMatchImageSnapshotPlugin function.
This plugin function takes the on object as a parameter.
Do note that everything that I'm doing here
is described in the documentation of the package.
The link is also included in the description.
We also need to register the commands.
To do this, we can go to supp/component inside of the cypress folder.
And here we can load the image-snapshot commands
by calling the method addMatchImageSnapshot command.
It's just a function call,
and as long as we're invoking this function in our support file,
we should be good.
Now we can go to our example test
and change our assertion
to instead of being contains the victory message,
we can change it to be match-image-snapshot.
Now let me explain snapshot tests for a second.
They work by comparing the current output of the application
with a given source of truth.
This source of truth is created the very first time you run the tests
without having a source of truth defined.
What I mean by this is that the very first time we run this test,
we're still technically writing the test,
because this first execution will be used to save the output as the source of truth.
So as you can see over here, the test already automatically ran
because Cypress is running in watch mode, but the first time it ran,
it was just saving the snapshot.
And I can see the snapshot file in here.
So you can see that Cypress has created a new file
called Displays the victory message if the player provides guess
with the word of the day.
This is exactly the name of the test, and it's just a photo of our application.
I can run this test again as many times as I want,
and it will still continue to pass as long as I don't provide any drastic changes.
Okay, so let's commit this.
We can say that a good commit message in this case is,
Setup Visual Regression testing for WordleBoard.
Also do notice that we are committing the snapshot itself.
This is very important because the snapshot is part of the test itself,
so always make sure that you're including the snapshot file
n your commit.
What if we change what the user is typing?
What if instead of typing the word of the day,
which is tests, we type happy instead?
Let's take a look.
We can see that our test has failed.
I can even try running this again,
and look at this, Cypress is failing our tests.
If we want to see the difference between the expected result
and the received result, we can look into the diff-output file.
This is located inside of your snapshots folder.
Under the test-switch folder name,
you're going to find a folder called diff-output.
If we expand this, we can see that there is a new file image in here.
If I click on it, this is what I see.
The left-hand side shows the expectation.
The right-hand side shows what was the current input,
and in the middle, we can see a diff between both outputs.
Notice that our test has identified a drastic change in the third row,
which is true because instead of typing tests,
we're typing happy, and it also noticed
that the victory message is completely missing in the new result.
This is pretty nice, right?
Another thing that I want to point out
is that if we try to make a commit right now,
you can see that the diff-output folder is being tracked.
We shouldn't be committing these diff files at all
because they are just failed test results.
So we should add this to the git ignore.
So first, I'm going to, of course,
revert to this change over here that broke our test.
But I also want to add this to our git ignore.
So you can see over here that what phpStorm has done
is just added this extra line to my git ignore.
but this is being too specific.
I don't want to ignore just this file.
I want to ignore everything that is inside of the diff-output folder.
So I'm just going to change this to say anything under the Cypress folder,
as long as it's inside of the diff output, should be ignored.
If I try to commit again,
you can see that the only file being modified is the gitignore file.
That's perfect. So let's save this as ignore snapshot test diff files.
Before we close this lesson,
I do want to point out that I have changed the test itself to make it fail.
A real-world example would involve some change in the component itself
that would cause the drastic visual regression.
So let me demonstrate a more realistic case.
If we go to the WordleBoard and we try to change the CSS for main,
let's just say that I'm going to change this
to just rotate around the z-axis.
So I can say transform, rotateZ, and let's just rotate it 92 degrees.
Now that I save this, we can see that our tests are failing.
Beautiful. And of course,
I should be able to see the diff file again.
And you can see that it's drastically different
than what we expected.
Awesome. Today we have covered
how to quickly write visual regression tests for our Vue components.