🔰 Introduction
Have you ever opened a CSS file that had grown out of control, full of !important, thought "Can I delete this line?", and then quietly closed the file again because you weren't sure? I have. And every time we do that, the CSS gets a little more chaotic. It's a vicious cycle. 😱
Visual regression testing is how we break out of that cycle. And if you're building Blazor apps, I'd like to show you that setting it up is far easier than you might expect, thanks to Blazing Story.
Let's start with the basics.
🤔 What Is Visual Regression Testing?
There are many definitions out there, but in this article, let me define visual regression testing (VRT) like this:
A test that saves screenshots of how your app looks, compares those screenshots before and after a change, and tells you whether the appearance is broken.
The "app" here means a web application, and I'll focus on Blazor apps in particular.
💡 Why Does It Matter?
Because it catches visual regressions during development, before your users run into them.
This is exactly what makes CSS refactoring safe. With visual regression testing in place, we can clean up messy CSS with confidence instead of fear. If an edit breaks the layout somewhere we didn't expect, the test tells us right away.
And there's a second reason that matters a lot in 2026: AI coding agents. When we hand a CSS change over to an AI agent, visual regression testing means we don't have to worry about the existing UI breaking silently. The UI may break for a moment while the agent works, but the test catches it, and the agent fixes it on its own. That's the whole point. 🎯
🤩 Wait, Blazing Story Already Has the Catalog
So how do we bring visual regression testing into Blazor app development? My recommendation is to use "Blazing Story".
Blazing Story is a Storybook clone, fully reimplemented in Blazor. It takes the Razor components inside your Blazor app and shows them as a catalog, and it runs as a standalone Blazor app.
https://blazingstory.github.io/docs/
Blazing Story ships as a NuGet package. Next to the main Blazor app project you want to catalog, you create a second Blazor app project for Blazing Story. That project references the target app, and for each Razor component you write a small wrapper component called a "story". Those stories then show up on the Blazing Story screen.
I wrote a full introduction to Blazing Story in an earlier article, so please take a look if this is new to you:
Now, why do I recommend Blazing Story specifically for visual regression testing? Because it gives you a UI component catalog, and that's exactly what visual regression testing needs. To run VRT, you first have to list every UI component in your app and take a screenshot of each one. Blazing Story already does the listing part for you, so you can point your screenshot tool straight at it.
Blazing Story has other benefits too. It enables component-first development, it helps the team share knowledge about the components, and it makes component-level E2E testing possible. It can even act as an MCP server so AI agents can build UI with your real components:
But in this article, I'll stay on the visual regression testing side.
⚡ Let's Actually Try It
Let me walk you through the whole thing, from adding a Blazing Story app project to running an actual visual regression test. I'll assume you already have the target Blazor app project (BlazorToDoApp in this example).
🛠️ 1. Add the Blazing Story App Project
First, install the Blazing Story project templates:
dotnet new install BlazingStory.ProjectTemplates
Next, add a Blazing Story app project to the same solution as your target Blazor app. Blazing Story works with both the Blazor Server and the WebAssembly hosting model. To create it as a Blazor WebAssembly project, use the blazingstorywasm template. You can also drop AI agent skills into the project folder at creation time.
From the CLI, run this:
dotnet new blazingstorywasm -n <project name> --skills <claude or agents>
If you're on Windows with Visual Studio, you can pick the Blazing Story WebAssembly project from the "Create a new project" dialog instead.
Once the project exists, add a project reference to your target Blazor app. The Razor components in that app are now visible from the Blazing Story app, so you can write a story for each of them. If you added the AI agent skills, you can simply say "please add a story for the XXX component" and let the agent do the typing.
Run the Blazing Story app, and your components show up as a catalog:
For the full setup instructions, see the official documentation:
blazingstory.github.io
🛠️ 2. Create the Visual Regression Testing Project
Now that we can take a screenshot of every component, let's create the visual regression testing project.
Before we do, one honest disclaimer. The visual regression testing project in this article is, in fact, an ordinary Playwright test project written in TypeScript and running on Node.js. There is not a single line of C#/.NET in it, sadly. 😅 That means the latest LTS version of Node.js has to be installed on the machine that runs the tests. As of 2026, in my experience, Playwright is simply the best tool for visual regression testing of web apps, so that's the path I'm showing you.
But don't worry. The Blazing Story project templates include a template for the visual regression testing project as well. So you can get started even if the Node.js side is unfamiliar territory.
From the CLI, run this:
dotnet new blazingstoryvrt -n <project name> --base-url <URL of the target Blazing Story app>
Visual Studio can't run these tests, but it can still create the project for you. Open the usual "Create a new project" dialog and pick "Blazing Story Visual Regression Testing".
That's it. Move into the folder of the project you just created and install the dependencies:
npm install
From here on I'll use the CLI. If you prefer a GUI, I recommend VSCode with the Playwright extension installed. I'll skip the details in this article, but the extension lets you run tests and browse reports without touching the terminal.
🚀 3. Run the Test for the First Time
Start the target Blazing Story app first. The visual regression testing project talks to the Blazing Story app, discovers what stories exist on its own, and runs a visual regression test for each one. You don't have to register anything by hand.
On the very first run, though, there are no baseline screenshots yet, the ones that say "this is what the correct UI looks like". So the first run has to happen in the mode that saves them. In the visual regression testing project folder, run:
npm run snapshots:update
A screenshot of every story is now taken automatically and saved as PNG files under the tests/vrt.spec.ts-snapshots folder. From now on, those files are the reference.
📝 4. Run It Again After a Change
Once the baselines are saved, change something in your Blazor app and run the test:
npm test
This compares the fresh screenshots against the saved baselines. No difference, and every test passes. Any difference, and the test fails and tells you about it.
When a difference shows up, open playwright-report/index.html in a browser. You can see visually which part of which component changed:
From there it's a simple decision:
- The difference was not intended. Fix the cause in your code.
-
The difference was intended. Run
npm run snapshots:updateagain to accept the new look as the baseline.
And that's the whole workflow!
Yes, you need a Node.js environment, and no, you can't run the tests from Visual Studio. If you rarely step outside the C#/.NET ecosystem, that may sound intimidating. But as you just saw, it comes down to a handful of CLI commands (or a few clicks in VSCode with the Playwright extension).
See? Not so hard, right? 👍
🔧 Stepping Up to Real-World Use
The flow above is enough to get started. Here are a few things to know before you take it into a real team workflow.
🐳 Run the Tests in a Container
By default, Playwright takes its screenshots with a headless Chromium browser. But rendering engines behave slightly differently on each platform, and the installed fonts differ too. Compare screenshots taken on two different platforms and you'll almost certainly see pixel-level differences that mean nothing.
To keep those meaningless differences out of your reports, run your visual regression tests on the same platform every time. The practical way to do that is to run them inside a container with the same configuration, both locally and in your CI/CD pipeline.
Fortunately, the Blazing Story visual regression testing project already includes the configuration files for the VSCode DevContainer feature. Open the project folder in VSCode, choose "Reopen in Container", and you're running your tests in a container. And if you'd rather build the container yourself, the DevContainer configuration tells you which image and setup to reproduce. Give it a try.
☁️ Keep the Baseline Screenshots in Cloud Storage
To keep things simple so far, we saved the baseline screenshots in a local folder. For real team development and CI/CD pipelines, though, cloud storage is the normal place to keep them.
I know, that suddenly sounds like a lot more work. Good news: the Blazing Story visual regression testing project template supports cloud storage out of the box, for these services:
- Azure Blob Storage
- Amazon S3
- Google Cloud Storage
If you created the project in Visual Studio, you may have already spotted the option in the dialog asking which cloud storage to use.
With that option enabled, you get two extra commands, npm run snapshots:pull and npm run snapshots:push, which sync your local baseline screenshots with the cloud storage. That's how you, your teammates, and your CI/CD pipeline all work from exactly the same baselines.
Want to use a different cloud service, or a file server on your own network? That works too. You can implement your own storage provider. There's even an AI agent skill for exactly that, so you can say "please make a storage provider that saves the baseline screenshots to XXX" and let the agent write it.
The documentation covers all of this in detail:
⚙️ Tuning the Test Behavior Itself
As I mentioned, the project generated from the Blazing Story template is, at the end of the day, a plain Playwright test project. So things like the browser window size for screenshots, or how much pixel difference you're willing to tolerate, are configured in the playwright.config.ts file inside the project.
For anything beyond that, ask your AI agent or read the Playwright documentation. Everything Playwright can do is available to you.
🎉 Summary
Visual regression testing changes how it feels to work on the UI:
- The CSS you were afraid to touch becomes safe to refactor.
- AI agents can change the UI without you holding your breath.
- Visual regressions get caught by a test, not by your users.
And in Blazor app development, this safety net is easy to put in place, because Blazing Story hands you the component catalog that VRT needs.
Start with a local run. Then step up to running in a container, sharing baselines on cloud storage, and finally running everything automatically in your CI/CD pipeline.
I hope this article helps you bring visual regression testing into your own Blazor apps, and that your CSS files stop being scary. 🙌
If you try it out, or if you have any questions or feedback, feel free to share them in the comments! 👇
❤️ Happy coding!
Top comments (0)