# Sharing Authentication in Playwright for .NET

> When you need to test pages behind authentication using Playwright for .NET but aren't sure where to start, we got you covered!

- URL: https://blog.nimblepros.com/blogs/sharing-authentication-in-playwright-for-dotnet/
- Author: [Sarah Dutkiewicz](https://blog.nimblepros.com/authors/sadukie/)
- Published: 2024-05-02
- Categories: [Testing](https://blog.nimblepros.com/categories/testing/)
- Publisher: [NimblePros](https://blog.nimblepros.com/)

---

If you are currently trying to test pages behind authentication while using Playwright for .NET, you're in the right place! This post stems from inner frustrations of sparse documentation that has code snippets but no real guidance on where those snippets go or how the feature event works. Can you really save an authenticated state and use it in other tests using Playwright for .NET? YES!

So... let's see how we are doing this here at NimblePros!

**Note**: This blog post was written with reference to Microsoft.Playwright.NUnit version 1.43.

## What is that .auth folder?

While looking at the [Playwright for .NET Authentication page](https://playwright.dev/dotnet/docs/auth), I noticed that they called out to create a `playwright/.auth` folder and add it to your `.gitignore` file. I was curious to see if they would save session state to the folder automatically. However, the more I tinkered with how this might work, the more I realized that this isn't really needed. Because... (the next question explains the "why"...)

## But wait... where does my storage state get stored?

When you run your tests, it will look in the `Path` that you specify in `context.StorageStateAsync()`'s options. Keep in mind that if you follow their documentation and use a `Path` value of `state.json`, it will store the `state.json` in the **current working directory**.

For example, suppose my tests are in `C:\code\SuperSecretProject\tests\SuperSecretProject.FrontEndTests`. When I run my tests in Debug mode, I will find the state.json file in the `C:\code\SuperSecretProject\tests\SuperSecretProject.FrontEndTests\bin\Debug\netX.0` folder of your tests project - where `netX.0` matches the project's targeted .NET version.

## What kind of data is stored?

Here's a glimpse at what's stored in `state.json`:

```json
{
    "cookies":[
        {
            "name":".AspNetCore.Antiforgery.TokenCode",
            "value":"AntiforgeryValue",
            "domain":"localhost",
            "path":"/",
            "expires":-1,
            "httpOnly":true,
            "secure":false,
            "sameSite":"Strict"
        },
        // A bunch of marketing cookies        
        {
            "name":"ProjectAuth",
            "value":"AuthValue",
            "domain":"localhost",
            "path":"/",
            "expires":-1,
            "httpOnly":true,
            "secure":true,"
            sameSite":"Lax"
        }
    ],    
    "origins":[]
    }
```

## All these code snippets - where do they go?

I'm glad you asked, because they don't really get into this in the documentation. That's why I'm blogging this.

Cookies and local storage values can be stored in a file through the help of the [BrowserContext.StorageStateAsync()](https://playwright.dev/dotnet/docs/api/class-browsercontext#browser-context-storage-state) method.

The documentation shows snippets for saving state and creating a new context with saved state. But they are snippets of syntax - not snippets with context. 

Before we get into the snippets, let's lay out some of our classes and how they relate.

```mermaid
classDiagram
    class LoginPage {
        LoginAsync()
    }
    LoginPage --|> BasePageObject
    class AuthenticatedPageBaseTest  {
        + IPage AuthenticatedPage
        - AuthenticatedPlaywrightDriver driver
        + OneTimeTearDown()
        + Setup()
    }
    AuthenticatedPageBaseTest *.. AuthenticatedPlaywrightDriver
    AuthenticatedPageBaseTest --|> PageTest
    class AuthenticatedPlaywrightDriver {
        - IPlaywright Playwright
        - IBrowser browser
        - IBrowserContext context
        ~ Task~~IPage~~ CreateAuthenticatedPage()
        - Task~~IBrowserContext~~ CreateAuthenticatedContext()
        - Task~~string~~ LoadStorageStateFromFile()
        - Dispose()
    }
    AuthenticatedPlaywrightDriver ..> LoginPage : Sets storage state if not authenticated
    class PageBehindAuthenticationPageTest {
        + TestSomething1()
        + TestSomething2()
    }
    PageBehindAuthenticationPageTest--|>AuthenticatedPageBaseTest : Uses AuthenticatedPage for navigation
```

Or for those who aren't familiar with reading UML:

- `LoginPage` inherits from `BasePageObject`. `BasePageObject` is a class we use for all page objects that contains the Base URI for testing.
- `AuthenticatedPlaywrightDriver` depends on `LoginPage`. This is an intentional tight coupling, as we need an `IPage` to navigate and get our authenication details. `LoginPage` fits the bill.
- `AuthenticatedPlaywrightDriver` has many private functions. The `CreateAuthenticatedPage()` is marked as `internal` and can be used by the assembly.
- The `AuthenticatedPageBaseTest` is the base class for tests for pages behind authentication. It inherits from the `PageTest` class provided by Playwright. The `AuthenticatedPageBaseTest` has a property that is a `AuthenticatedPlaywrightDriver`.  
- `PageBehindAuthenticationPageTest` inherits from `AuthenticatedPageBaseTest`. 

So imagine you have a `SuperSecretProject` with a page to view related resources that only Admins can see. You want to write an automated test to ensure it works correctly:

- You need a way to either load the session state from file or create the file if it doesn't exist.
- You need a login page to go through the steps of logging into the site and save the state to the state file.
- You want to navigate using a page with a browser context that has the saved session state.
- You need a page object to represent your `SuperSecretAdminPage`. This is the equivalent of `PageBehindAuthenticationPageTest` above.

### How do we create a new browser context?

Their snippets of code looks like this:

#### Save Storage State

```csharp
// Save storage state into the file.
await context.StorageStateAsync(new()
{
    Path = "state.json"
});
```

#### Create Context with Storage State

```csharp
// Create a new context with the saved storage state.
var context = await browser.NewContextAsync(new()
{
    StorageStatePath = "state.json"
});
```

But where do these snippets go? Playwright uses browser contexts to run the tests. So this is the flow I've gone with:

```mermaid
flowchart TB
pw1[Launch Playwright via CreateAsync method]
pw1 --> pw2[Launch a browser]
pw2 --> pw3[Create a browser context]
pw3 --> load1
subgraph Create Browser Context
    load1[Load contents from file]
    create1[Create new file if not exists]
    subgraph Create Context
        context1[Create Context with Storage State Snippet Goes Here]
    end
    load1 --> context1
    create1 --> context1
    context1-->login1{Is storage state null or empty?}
    subgraph Auth and Save
        login2[Do login steps with LoginPage page object]
        login3[Save Storage State Snippet Goes Here]
        login2 --> login3
    end 
    login1 -- Yes -->login2
    login1 -- No -->pw4
end     
pw3 --> pw4[Return authenticated page using authenticated context]
login3 --> pw4
```

From what I've seen in the documentation, it doesn't appear to be something that can be set on the default browser. So we are creating our context in `AuthenticatedPlaywrightDriver`'s `CreateAuthenticatedContext()`:

```csharp
private async Task<IBrowserContext> CreateAuthenticatedContext()
{
  // Load storage state from file
  var storageState = await LoadStorageStateFromFile("state.json");

  // Create a new browser context with the loaded storage state
  var contextOptions = new BrowserNewContextOptions
  {
    StorageState = storageState.ToString()
  };
  _context = await _browser!.NewContextAsync(contextOptions);
  if (string.IsNullOrEmpty(storageState))
  {
    // If the state file didn't exist, a new file is created
    // That would get you here to this point
    // Since the login page object handles logging into the portal,
    // We will add that dependency here.
    var loginPage = new LoginPage(await _context.NewPageAsync());
    await loginPage.LoginAsync();
  }
  return _context;
}
```

Our `LoadStorageStateFromFile()` method isn't anything special:

```csharp
private async Task<string> LoadStorageStateFromFile(string filePath)
{
    if (!File.Exists(filePath))
    {
        // Create the file and release the lock
        File.Create(filePath).Dispose();
    }

    // Read the storage state file
    return await File.ReadAllTextAsync(filePath);
}
```

### Where do we save the browser context?

As for `LoginAsync()`, it navigates the login page, enters in credentials, and then calls the Save snippet to save the value to the `state.json` file. This could be entering credentials in textboxes, clicking links for SSO, or whatever steps you need to take for authentication. Once the authentication is done, then you call the snippet of code to save the state.

## How do we use this with Multiple Pages?

All pages behind authentication can follow the pattern that `PageBehindAuthenticationPageTest` does:

- Inherit from `AuthenticatedPageBaseTest`.
- Use the `AuthenticatedPage` as the IPage object for your tests. This is what contains the storage state.

### What's in the AuthenticatedPageBaseTest?

The authenticated page base test file looks like this:

```csharp
using Microsoft.Playwright;

namespace NimblePros.SuperSecretProject.FrontEndTests.Tests.Auth;

internal class AuthenticatedPageBaseTest : PageTest
{
  private AuthenticatedPlaywrightDriver driver = new AuthenticatedPlaywrightDriver();

  public IPage AuthenticatedPage;
  
  [SetUp]
  public async Task Setup()
  {
    AuthenticatedPage = await driver.CreateAuthenticatedPage();
  }

  [OneTimeTearDown]
  public void OneTimeTearDown()
  {
    driver.Dispose();
  }
}
```

### What's the AuthenticatedPlaywrightDriver?

This is how we launch our Playwright, launch the browser, create the context, and create a new page with the authentication. You can find the code here [in this gist for AuthenticatedPlaywrightDriver.cs](https://gist.github.com/sadukie/bed69e775aa5fa78f6edfe70683ab8dd).

## What if my Authentication Token is in Session Storage?

This post focuses on local storage and cookies. However, we also have a post on [Sharing Session Storage in Playwright for .NET](https://blog.nimblepros.com/blogs/sharing-session-storage-in-playwright-for-dotnet/). That post will walk you through their snippets for accessing session storage.

## Conclusion

I hope this blog post has helped enlighten you on how to save state and reuse it in Playwright for .NET.

If you are getting started with Playwright for .NET, we have a couple on-demand webinars that may help you as well:

- [Design Patterns for Testing](https://youtu.be/kB1bb7q7f0A?si=JBWfguCP6gLTLL-t) - This includes the Page Object pattern for front-end testing.
- [Testing Blazor with Playwright](https://youtu.be/ZZXNPboS0v8?si=pxb9fNLKDVqJn_G8)

If you are interested in having us train your devs on testing or working with Playwright for .NET, [contact us today](https://bit.ly/contact-np)!
