Feature request: Project-level reusable authentication with Playwright storageState

[davidfoltyn]

Hi Alex,

first of all, thanks for WrightTest. I've recently deployed it as a self-hosted instance and I'm currently evaluating it for automated testing of our web applications.

One feature that would be very useful for testing authenticated applications is project-level reusable authentication, ideally based on Playwright's storageState.

Use case

We have applications where almost every page requires authentication.

In WrightTest, I'd like to structure the project like this:

Project: Test Application

Authentication check:
  - Login

Checks:
  - Documents list
  - Cases list
  - Administration
  - Search
  - Document detail
  - ...

Currently, as far as I understand, every check creates a new browser context, so each check has to repeat the complete login flow.

For a project containing many checks this adds unnecessary execution time and also duplicates the login steps across all checks.

Suggested behavior

It would be great if a project could optionally select one existing check as its Authentication / Setup check.

After successfully running this check, WrightTest could save the Playwright authentication state:

await context.storageState(...)

Other checks in the project could then create their browser context using the stored state:

const context = await browser.newContext({
  ...deviceConfig,
  storageState: projectAuthState
});

This would allow every check to remain independent while starting from an authenticated state.

Possible UI

Something like this in Project Settings:

Authentication

Authentication check:
[ Login ▼ ]

[x] Use authentication state for project checks

Status: Available
Last refreshed: ...

[ Refresh authentication ]

Existing WrightTest Environments could still be used for credentials:

{{LOGIN_USER}}
{{LOGIN_PASSWORD}}

so there would be no need for a separate credentials mechanism.

Expired sessions

A simple first implementation could just allow the user to manually click Refresh authentication when the session expires.

A future enhancement could automatically rerun the authentication check when the stored session is no longer valid.

Playwright already recommends reusing authenticated browser state for this type of scenario, so this seems like a natural fit for WrightTest.

Would you consider adding something like this?

Thanks!

[AlexFilippov-it]

Thank you for the detailed proposal. This is the authentication model we want WrightTest to support.

We have implemented the MVP in the current development version and are validating it before release. One important design decision is that authentication is not stored as one global storageState per project. It is stored as an authentication profile for each Project + Environment pair, because DEV, STAGE, and PROD can use different domains, cookies, tokens, and user accounts.

How to configure reusable authentication

1. Create an Environment

Open:

Project -> Environments -> New Environment

An Environment is a named set of variables for one target system. It is not a Docker or server environment.

For example:

Environment name: dev

BASE_URL=https://app.example.com
LOGIN_URL=https://app.example.com/login
DASHBOARD_URL=https://app.example.com/dashboard
LOGIN_USER=user@example.com
LOGIN_PASSWORD=your-password

The variable names are flexible. They can be used in check URLs and steps as {{LOGIN_URL}}, {{LOGIN_USER}}, and so on.

An Environment is required because WrightTest keeps a separate authenticated state for every Project + Environment combination.

2. Create a dedicated Login check

Create a normal check named, for example, Login.

Configure it as follows:

• Select the dev Environment.
• Use {{LOGIN_URL}} as the Start URL, or enter the login URL directly.
• Disable Use reusable project authentication for this environment for this check.
• Add the login actions:
  1. Fill the username/email field with {{LOGIN_USER}}.
  2. Fill the password field with {{LOGIN_PASSWORD}}.
  3. Click the sign-in button.
• Add at least one assertion that proves login succeeded.

Recommended assertions:

• Assert URL for the dashboard URL; or
• Assert visible for an element that only exists after login, such as the user menu or dashboard heading.

The assertion is required. A successful click on the sign-in button alone does not prove that authentication completed.

Login, logout, registration, password reset, guest, and negative authentication checks should keep reusable authentication disabled so that they always start unauthenticated.

3. Configure the authentication profile

Open:

Project -> Settings -> Authentication

Then:

1. Select the Environment, for example dev.
2. Select the Login check as the Authentication check.
3. Enable Use authentication state for checks in this environment.
4. Click Save authentication settings.
5. Click Refresh authentication.

WrightTest runs the Login check in a clean browser context without an old authentication state. If every step and assertion passes, WrightTest captures the Playwright browser state, including cookies, local storage, and IndexedDB authentication data.

When the refresh completes, the status changes to Available. The successful refresh is also stored as a regular run with step results, screenshots, and a trace, so it can be inspected when necessary.

4. Use the profile in authenticated checks

For each regular authenticated check:

• Select the same Environment, for example dev.
• Enable Use reusable project authentication for this environment.
• Set the Start URL to the protected page, for example {{DASHBOARD_URL}}.
• Start recording, validate the steps, or run the check.

WrightTest creates a new isolated browser context for every check and initializes it with a copy of the saved authentication state. Checks remain independent; the browser context itself is never shared between runs.

The same authentication state is used consistently by:

• normal check runs;
• selector validation;
• the browser recorder.

This prevents a situation where a check runs as an authenticated user but validation or recording unexpectedly opens the login page.

Refresh and failure behavior

Authentication refresh is manual in the MVP.

Refresh the profile when:

• the session expires;
• the account password changes;
• the login flow changes;
• the environment/domain changes;
• authenticated checks are redirected back to the login page.

A refresh uses last-known-good behavior:

• a successful refresh atomically replaces the previous state;
• a failed refresh does not destroy the previous working state;
• the UI shows the refresh error and keeps the previous state active when one is available;
• a completely empty captured state is rejected.

Security and permissions

Playwright storageState contains credential material such as session cookies and tokens, so it is handled as a secret:

• the state JSON is never returned to the frontend;
• the API returns metadata only: status, environment, authentication check, timestamps, and errors;
• stored state is encrypted at rest;
• Owners and Editors can configure and refresh authentication;
• Viewers can only see read-only status information.

MVP scope

The first version intentionally supports:

• one authentication profile per Project + Environment;
• one Login/setup check per profile;
• manual refresh;
• a per-check opt-out for unauthenticated scenarios;
• fresh isolated contexts for all normal checks.

The MVP does not yet include automatic session-expiry detection, automatic refresh, multiple profiles for one Environment, shared authentication across projects, setup-check chains, or importing/exporting raw authentication state.

So, for the message "Create an environment before configuring reusable authentication", the required first step is to create a project Environment such as dev, add the login-related variables if needed, and then configure the Login check for that Environment.