As of Playwright version 1.31, there is a new feature that makes it much easier to authenticate users for your tests. In this post, we revamp a previous blog post, Fast and Easy Authentication with Playwright, and discuss how this resolves a few issues that I had with it.
The old approach used the global setup feature to authenticate a test user and reuse its authentication state throughout your test suite. Although it worked, it's not the most elegant solution because it has two major drawbacks:
- the authentication state is reused for every test case, making it harder to test different user roles
- we have to manually instantiate a new browser page using the Playwright API
The main benefit that we gain after migrating to the new API is that we're able to sign in with multiple users (and roles). Even if that's not a requirement for your project, you still have the possibility for it in the future. Additionally, the updated version creates a cleaner codebase, aligned with the rest of the test suite.
To refactor our previous solution we need to update the configuration and the setup file.
Configuration Update link
Let's modify the configuration file first to use the new API. The configuration changes are as follows:
We create a new project in
setup, and we move the
globalSetup property to the
Within the created
setup project add the
testMatch property to define which file to be execute when it's run.
Next, we add the
storageState path to each project that needs to be authenticated.
The value of this property (
e2e/.auth/storageState.json) is that same as the previous global
storageState property, which means that we can also remove the
Because the Playwright team encourages to store this file in the
.auth directory (to make it easy to git ignore), we'll also make this change to our setup.
This value defines the file that includes the stored authentication state for the user, the setup project will write its state to this file (which we'll see in a minute).
Lastly, we need to add a dependency to the
setup project in each Playwright project.
With the configuration in place, we can now update the setup file.
And the changes are minimal;
Instead of writing a Playwright script, we refactor the code into a Playwright test.
It's essential to name the test file the same as used in the
testMatch property within the configuration file. In this case, it's
The most important part of this test is the last line,
page.context().storageState(), which writes the authentication state to the
storageState.json file, including our users' information
When we compare the new structure to the previous solution, we can see that we're not required to have knowledge about the low-level Playwright API.
The setup becomes a lot cleaner and easier to read because the authentication flow is now part of a test case.
For example, instead of manually creating (and closing) a new browser page, we can use the
page object that's provided by the Playwright test runner.
We're also able to sign in with multiple users (and roles), which is a nice bonus. While this is not covered in this post, I can point you to the Playwright documentation. With this new feature, the documentation also gained a new corresponding guide on authentication that includes great examples.
Feel free to update this blog post on GitHub, thanks in advance!
I appreciate it if you would support me if have you enjoyed this post and found it useful, thank you in advance.