Use Playwright with Microsoft Dev Proxy on GitHub Actions

Part of the process of testing the Microsoft Dev Proxy on GitHub Actions, was to use it in combination with Playwright. The advantage of this combination is that you can use the same mocked API responses which you use during development to test your solutions.

In this blog post, I will show you how to use Playwright in combination with the Microsoft Dev Proxy in your GitHub Actions workflow.

Things to know before you start

When creating tests, your goal is to aim to a desired outcome. The Dev Proxy can be used in various ways to simulate different scenarios. One of those is to simulate random errors (by using the GenericRandomErrorPlugin plugin), which can be useful during local development, but not when you want to run your end-to-end tests.

Best practice is to use the Dev Proxy for mocking APIs or simulating specific scenarios during end-to-end tests. This way, you can ensure that your tests are predictable and reliable.

Setting up Playwright

When you followed the Playwright getting started guide, you should have a basic setup in place. When you want to use Playwright with the Dev Proxy, you can add the proxy configuration to the configuration. You can do this in your playwright.config.ts file by adding the following code:

1
import { defineConfig } from '@playwright/test';
2
export default defineConfig({
3
  use: {
4
    proxy: {
5
      server: 'http://localhost:8000'
6
    }
7
  }
8
});

Configuring the GitHub Actions workflow

Once the configuration is in place, you can start configuring your GitHub Actions workflow.

Using a macOS runner

When using the macOS runner, you can start with the configuration found in the Using Microsoft Dev Proxy in your GitHub Actions workflow on a macOS hosted VM article. The only thing you need to add is the dependency installation steps.

1
name: macOS Dev Proxy with Playwright
2

3
on:
4
  push:
5
    branches:
6
      - main
7
      - dev
8
  workflow_dispatch:
9

10
jobs:
11
  test:
12
    timeout-minutes: 60
13
    runs-on: macos-latest
14
    steps:
15
      - uses: actions/checkout@v4
16

17
      - uses: actions/setup-node@v4
18
        with:
19
          cache: "npm"
20

21
      - name: Install dependencies
22
        run: npm ci
23

24
      #################################
25
      # Cache + install of Playwright #
26
      #################################
27
      - name: Store Playwright's Version
28
        run: |
29
          PLAYWRIGHT_VERSION=$(npm ls @playwright/test | grep @playwright | sed 's/.*@//')
30
          echo "Playwright's Version: $PLAYWRIGHT_VERSION"
31
          echo "PLAYWRIGHT_VERSION=$PLAYWRIGHT_VERSION" >> $GITHUB_ENV
32

33
      - name: Cache Playwright Browsers for Playwright's Version
34
        id: cache-playwright
35
        uses: actions/cache@v4
36
        with:
37
          path: ~/Library/Caches/ms-playwright
38
          key: playwright-${{ env.PLAYWRIGHT_VERSION }}
39

40
      - name: Install Playwright Browsers
41
        if: steps.cache-playwright.outputs.cache-hit != 'true'
42
        run: npx playwright install --with-deps
43

44
      ################################
45
      # Cache + install of Dev Proxy #
46
      ################################
47
      - name: Store Dev Proxy's Version
48
        run: |
49
          DEVPROXY_VERSION=$(curl -s https://api.github.com/repos/microsoft/dev-proxy/releases/latest | jq .tag_name -r)
50
          echo "Dev Proxy's Version: $DEVPROXY_VERSION"
51
          echo "DEVPROXY_VERSION=$DEVPROXY_VERSION" >> $GITHUB_ENV
52

53
      - name: Cache Dev Proxy
54
        id: cache-devproxy
55
        uses: actions/cache@v4
56
        with:
57
          path: ./devproxy
58
          key: devproxy-${{ env.DEVPROXY_VERSION }}
59

60
      - name: Install Dev Proxy
61
        if: steps.cache-devproxy.outputs.cache-hit != 'true'
62
        run: bash -c "$(curl -sL https://aka.ms/devproxy/setup.sh)"
63

64
      #######################
65
      # Configure Dev Proxy #
66
      #######################
67
      - name: Run Dev Proxy
68
        run: ./devproxy/devproxy &
69

70
      - name: Install the Dev Proxy's certificate
71
        timeout-minutes: 1
72
        run: |
73
          echo "Finding certificate..."
74
          security find-certificate -c "Dev Proxy CA" -a -p > dev-proxy-ca.pem
75

76
          echo "Trusting certificate..."
77
          sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain dev-proxy-ca.pem
78
          echo "Certificate trusted."
79

80
      ##########################
81
      # Start Playwright tests #
82
      ##########################
83
      - name: Run Playwright tests
84
        run: npx playwright test

Playwright outcome with Dev Proxy on a macOS runner

Using an Ubuntu runner

Things are a bit more complicated when you want to use the Dev Proxy with Playwright on an Ubuntu virtual machine/runner. The reason is the way browsers manage certificates on Linux. On macOS, all browsers use the certificates wich are trusted in the Keychain, but on Linux, each browser has its own certificate store which complicates things.

Chromium uses the NSS Shared DB to manage certificates.

Firefox does not have a central location where it looks for certificates. It will use the current profile or you can assign a policy template to manage certificates.

When using Firefox with Playwright, it creates an in-memory profile, so you cannot add the certificate to the profile before starting the browser. The policy approach is not yet supported by Playwright Playwright issue #28967. So, in case of using Firefox, you will have to ignore the HTTPS errors.

Ignoring HTTPS errors (the simple approach)

The simple approach is to ignore HTTPS errors by setting the ignoreHTTPSErrors to true in your Playwright configuration. You can do this for all browsers or for specific browsers. Here is an example of how you can do this:

1
import { defineConfig } from '@playwright/test';
2

3
export default defineConfig({
4
  use: {
5
    proxy: {
6
      server: 'http://localhost:8000'
7
    },
8
    // Ignore all for all browsers
9
    ignoreHTTPSErrors: true
10
  },
11
  projects: [
12
    {
13
      name: "firefox",
14
      use: {
15
        ...devices["Firefox Desktop"],
16
        // Ignore HTTPS errors for Firefox only
17
        ignoreHTTPSErrors: true
18
      },
19
    },
20
  ],
21
});

Adding the certificate to the NSS Shared DB

If you are only using Chromium in your tests, you can add the certificate to the Chromium NSS Shared DB.

To add the certificate to the NSS Shared DB, you can use the following steps:

1
- name: Install the Dev Proxy certificate for Chromium
2
  timeout-minutes: 1
3
  run: |
4
    echo "Export the Dev Proxy's Root Certificate"
5
    openssl pkcs12 -in ~/.config/dev-proxy/rootCert.pfx -clcerts -nokeys -out dev-proxy-ca.crt -passin pass:""
6

7
    # echo "Installing certutil"
8
    sudo apt install libnss3-tools
9

10
    # echo "Adding certificate to the NSS database for Chromium"
11
    mkdir -p $HOME/.pki/nssdb
12
    certutil --empty-password -d $HOME/.pki/nssdb -N
13
    certutil -d sql:$HOME/.pki/nssdb -A -t "CT,," -n dev-proxy-ca.crt -i dev-proxy-ca.crt
14
    echo "Certificate trusted."

The highlighted line in the code snippet above shows how you can add the dev-proxy-ca.crt certificate to the NSS Shared DB of Chromium. The CT,, trust arguments add the trusted for SSL client authentication.

Here is the complete GitHub Actions workflow for Ubuntu:

1
name: ubuntu Dev Proxy
2

3
on:
4
  push:
5
    branches:
6
      - main
7
      - dev
8
  workflow_dispatch:
9

10
jobs:
11
  test:
12
    timeout-minutes: 60
13
    runs-on: ubuntu-latest
14
    steps:
15
      - uses: actions/checkout@v4
16

17
      - uses: actions/setup-node@v4
18
        with:
19
          cache: "npm"
20

21
      - name: Install dependencies
22
        run: npm ci
23

24
      #################################
25
      # Cache + install of Playwright #
26
      #################################
27
      - name: Store Playwright's Version
28
        run: |
29
          PLAYWRIGHT_VERSION=$(npm ls @playwright/test | grep @playwright | sed 's/.*@//')
30
          echo "Playwright's Version: $PLAYWRIGHT_VERSION"
31
          echo "PLAYWRIGHT_VERSION=$PLAYWRIGHT_VERSION" >> $GITHUB_ENV
32

33
      - name: Cache Playwright Browsers for Playwright's Version
34
        id: cache-playwright
35
        uses: actions/cache@v4
36
        with:
37
          path: ~/.cache/ms-playwright
38
          key: playwright-ubuntu-${{ env.PLAYWRIGHT_VERSION }}
39

40
      - name: Install Playwright Browsers
41
        if: steps.cache-playwright.outputs.cache-hit != 'true'
42
        run: npx playwright install --with-deps
43

44
      ################################
45
      # Cache + install of Dev Proxy #
46
      ################################
47
      - name: Store Dev Proxy's Version
48
        run: |
49
          DEVPROXY_VERSION=$(curl -s https://api.github.com/repos/microsoft/dev-proxy/releases/latest | jq .tag_name -r)
50
          echo "Dev Proxy's Version: $DEVPROXY_VERSION"
51
          echo "DEVPROXY_VERSION=$DEVPROXY_VERSION" >> $GITHUB_ENV
52

53
      - name: Cache Dev Proxy
54
        id: cache-devproxy
55
        uses: actions/cache@v4
56
        with:
57
          path: ./devproxy
58
          key: devproxy-ubuntu-${{ env.DEVPROXY_VERSION }}
59

60
      - name: Install Dev Proxy
61
        if: steps.cache-devproxy.outputs.cache-hit != 'true'
62
        run: bash -c "$(curl -sL https://aka.ms/devproxy/setup.sh)"
63

64
      #######################
65
      # Configure Dev Proxy #
66
      #######################
67
      - name: Run Dev Proxy
68
        run: ./devproxy/devproxy &
69

70
      - name: Install the Dev Proxy certificate for Chromium
71
        timeout-minutes: 1
72
        run: |
73
          echo "Export the Dev Proxy's Root Certificate"
74
          openssl pkcs12 -in ~/.config/dev-proxy/rootCert.pfx -clcerts -nokeys -out dev-proxy-ca.crt -passin pass:""
75

76
          # echo "Installing certutil"
77
          sudo apt install libnss3-tools
78

79
          # echo "Adding certificate to the NSS database for Chromium"
80
          mkdir -p $HOME/.pki/nssdb
81
          certutil --empty-password -d $HOME/.pki/nssdb -N
82
          certutil -d sql:$HOME/.pki/nssdb -A -t "CT,," -n dev-proxy-ca.crt -i dev-proxy-ca.crt
83
          echo "Certificate trusted."
84

85
      ##########################
86
      # Start Playwright tests #
87
      ##########################
88
      - name: Run Playwright tests
89
        run: npx playwright test

Playwright outcome with Dev Proxy on an Ubuntu runner

Conclusion

Using Playwright in combination with the Microsoft Dev Proxy on GitHub Actions is possible, but as you can see it requires some additional steps when using an Ubuntu runner. The macOS runner is more straightforward to configure. Hopefully these configuration differences will change in the future, but for now I hope you can get started with the provided examples.

Use Playwright with Microsoft Dev Proxy on GitHub Actions

Things to know before you start

Setting up Playwright

Configuring the GitHub Actions workflow

Using a macOS runner

Using an Ubuntu runner

Ignoring HTTPS errors (the simple approach)

Adding the certificate to the NSS Shared DB

Conclusion

Related articles

Test the unexpected API results with Playwright mocking

The Playwright Reporter for GitHub Actions

Using Dev Proxy in your GitHub Actions workflow on macOS

Report issues or make changes on GitHub

Comments

Elio Struyf