Every quarter, Salesforce teams hit the same wall: a sandbox gets refreshed, and every automated test in the pipeline goes red overnight. URLs change, passwords reset, OAuth tokens expire, and that stable CI/CD pipeline you spent weeks building now looks like a pile of broken glass.

The core pain point is not the refresh itself. It is the fact that most test automation setups treat the Salesforce environment as a static target. When that target moves, which it does every single refresh, the entire testing pipeline collapses and someone spends a full day manually reconfiguring secrets, re-authenticating users, and babysitting the build.

This guide walks you through a battle-tested approach to running Salesforce Playwright tests in CI/CD that actually survives sandbox refreshes. You will learn how to structure your auth layer, externalize your configuration, wire everything into GitHub Actions, and handle the Salesforce-specific quirks that generic Playwright CI/CD guides never mention. If you are new to Salesforce testing with Playwright, start there for the fundamentals before tackling the CI/CD side.

Why sandbox refreshes break everything

To understand why running Salesforce Playwright tests in CI/CD is harder than testing a typical web app, you first need to understand what makes Salesforce sandboxes different from standard staging environments.

A regular staging environment for a React or Node.js app sits on infrastructure your team controls. The URLs stay the same. The database credentials stay the same. The test users stay the same. You deploy new code, and the environment evolves predictably.

Salesforce sandboxes do not work that way. They are copies of your production org, managed entirely by Salesforce's infrastructure. When a sandbox is refreshed, Salesforce generates a new environment from scratch using a snapshot of production. This means the sandbox you tested against yesterday is literally a different org today.

This is why a hardcoded login URL, a stored auth token, or a static base URL in your Playwright config will break the moment someone clicks "Refresh" in Salesforce Setup. The environment is not updated; it is replaced.

For teams running continuous integration pipelines, this creates a recurring crisis. Every refresh cycle produces the same frantic Slack messages: "CI is red," "tests are failing on staging," "who refreshed the sandbox?" Understanding exactly what changes during a refresh is the first step toward making your pipeline immune to it.

What a Salesforce sandbox refresh actually changes

Before you can build refresh-proof Salesforce Playwright tests in CI/CD, you need a clear picture of what moves and what stays put after a refresh. Here is the breakdown, based on Salesforce official sandbox documentation:

What changes after a refresh

• Organization ID: Every sandbox gets a new unique 18-character org ID. Any test logic that references the org ID will break.
• My Domain URL: The sandbox URL follows the pattern https://MyDomain--SandboxName.sandbox.my.salesforce.com. If the sandbox name changes or the org moves to a different Hyperforce instance, the URL changes.
• Usernames: Appended with .sandboxname (e.g., [email protected] becomes [email protected]).
• User passwords: All previous sandbox passwords are wiped. Production passwords are copied at snapshot time.
• Email addresses: Salesforce appends .invalid to every email address to prevent accidental outbound emails from sandbox.
• OAuth tokens: All connected app authorizations and refresh tokens are invalidated.
• Email deliverability: Reset to "System Email Only," blocking outbound email automation tests.
• Scheduled jobs: All scheduled Apex, batch jobs, flows, and report subscriptions are disabled.
• Session IDs: Every active session is destroyed.
• Named credentials and integrations: Endpoint URLs from production are copied, potentially pointing sandbox tests at live third-party systems.

What stays the same

• Metadata structure (objects, fields, Apex classes, LWC components, page layouts)
• User records (the users exist, but their passwords and emails are modified)
• Profiles and permission sets
• Connected App metadata (the app definition survives, but authorizations do not)

Sandbox types and their refresh cycles

The refresh interval matters for your CI/CD planning. If you are running Salesforce Playwright tests in CI/CD against a Developer sandbox, that sandbox could be refreshed daily. Your pipeline needs to handle that frequency without manual intervention.

Knowing exactly what breaks gives you a checklist of things to externalize. The next step is setting up Playwright in a way that is already prepared for those changes.

Setting up Playwright for Salesforce orgs

If you are starting fresh, the initial Playwright setup for Salesforce needs a few adjustments compared to a standard web app. The Playwright config file is where most of the Salesforce-specific tuning happens.

Install and initialize

npm init playwright@latest
npm install --save-dev dotenv

This gives you the default project structure. Now, adjust the config for Salesforce:

import { defineConfig, devices } from '@playwright/test';
import dotenv from 'dotenv';
import path from 'path';

// Load environment-specific variables
const environment = process.env.SF_ENV || 'dev';
dotenv.config({ path: path.resolve(__dirname, `.env.${environment}`) });
export default defineConfig({
  testDir: './tests',
  timeout: 60_000,
  expect: { timeout: 10_000 },
  fullyParallel: false,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 2 : undefined,
  reporter: process.env.CI
    ? [['html', { open: 'never' }], ['json', { outputFile: 'results.json' }]]
    : 'html',
  use: {
    baseURL: process.env.SF_BASE_URL,
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
    actionTimeout: 15_000,
    navigationTimeout: 30_000,
    launchOptions: {
      args: [
        '--disable-background-timer-throttling',
        '--disable-backgrounding-occluded-windows',
        '--disable-renderer-backgrounding',
      ],
    },
  },
  projects: [
    {
      name: 'sf-auth-setup',
      testMatch: /.*\.setup\.ts/,
    },
    {
      name: 'salesforce-tests',
      dependencies: ['sf-auth-setup'],
      use: {
        ...devices['Desktop Chrome'],
        storageState: 'playwright/.auth/sf-user.json',
      },
    },
  ],
});

Tip: The 3 Chromium launch args above (--disable-background-timer-throttling, etc.) are critical for Salesforce. Without them, headless Chromium throttles timers and CSS rendering for background tabs, causing Lightning components to stall mid-render and produce false failures in CI.

A few things to note in this config:

• dotenv with SF_ENV: The config loads a different .env file depending on which sandbox you target. This is the foundation of refresh-proof configuration.
• retries: 2 in CI: Salesforce Lightning UI can have intermittent loading delays. A retry policy handles transient failures. You can learn more about Playwright test retry strategies to fine-tune this.
• Project dependencies: The sf-auth-setup project runs first to handle login, and all other tests reuse the saved auth state.
• forbidOnly: Prevents accidental commits of test.only from running in your pipeline and silently skipping tests.

The Playwright report for CI and local runs generated by this config gives your team a clear view of what passed, what failed, and what was retried, which is critical during post-refresh debugging.

With the project structure in place, the most important piece is the authentication layer. That is where most sandbox-refresh pain originates.

Building a refresh-proof authentication layer

Authentication is the number one thing that breaks after a sandbox refresh. Passwords reset, OAuth tokens expire, and MFA settings may change. Your Playwright authentication setup needs to handle all of this through external configuration, not hardcoded values.

The setup project approach

Playwright officially recommends using project dependencies (introduced in v1.31) instead of the legacy globalSetup. This approach preserves tracing, screenshots, and worker isolation for the auth step itself:

import { test as setup } from '@playwright/test';
const authFile = 'playwright/.auth/sf-user.json';

setup('authenticate to salesforce', async ({ page }) => {
  // Navigate to Salesforce login
  await page.goto(process.env.SF_LOGIN_URL!);

  // Fill credentials from environment variables
  await page.getByLabel('Username').fill(process.env.SF_USERNAME!);
  await page.getByLabel('Password').fill(process.env.SF_PASSWORD!);
  await page.getByRole('button', { name: 'Log In' }).click();

  // Wait for Salesforce Lightning to fully load
  await page.waitForURL('**/lightning/**', { timeout: 30_000 });

  // Save authenticated state
  await page.context().storageState({ path: authFile });
});

Handling MFA after a refresh

Salesforce multi-factor authentication (MFA) is enforced by default. After a sandbox refresh, MFA settings from production carry over, which means your CI/CD test user may suddenly require a verification code. The Salesforce login and MFA setup with Playwright guide covers this in depth, but here is the summary for CI/CD:

1. Create a dedicated integration user profile in your Salesforce org.
2. Set Login IP Ranges on that profile to include your CI/CD runner IP ranges (GitHub Actions publishes their IP ranges in their documentation).
3. This bypasses MFA for requests originating from trusted IPs.

The frontdoor.jsp technique (API-to-browser bridge)

The most resilient authentication approach for CI/CD uses the Salesforce Connected App with the JWT Bearer Token flow to obtain an access token via API, then bridges that token into a browser session using Salesforce's frontdoor.jsp endpoint:

import { request } from '@playwright/test';

export async function getSalesforceSession() {
  const apiContext = await request.newContext();
  const response = await apiContext.post(
    `${process.env.SF_LOGIN_URL}/services/oauth2/token`,
    {
      form: {
        grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
        assertion: process.env.SF_JWT_TOKEN!,
      },
    }
  );

  const data = await response.json();
  return {
    accessToken: data.access_token,
    instanceUrl: data.instance_url,
  };
}

import { Page } from '@playwright/test';

export async function loginViaFrontdoor(
  page: Page,
  instanceUrl: string,
  accessToken: string,
  targetUrl = '/lightning/page/home'
) {
  const frontdoorUrl = `${instanceUrl}/secur/frontdoor.jsp?sid=${encodeURIComponent(accessToken)}&retURL=${encodeURIComponent(targetUrl)}`;

  await page.goto(frontdoorUrl, { waitUntil: 'domcontentloaded' });
  await page.waitForURL('**/lightning/**');
}

This frontdoor.jsp approach completely bypasses the login form and MFA prompts. The Connected App metadata survives the refresh (it is part of the org's metadata), so you only need to re-authorize the integration user after a refresh. No password management, no TOTP codes, no IP range gymnastics.

The authentication layer is now externalized and configurable. The next piece is making sure every other environment-specific value (URLs, org details, test data) follows the same pattern.

Environment-driven configuration for multiple sandboxes

Running Salesforce Playwright tests in CI/CD across multiple sandboxes requires a configuration strategy that maps each sandbox to its own set of variables. The environment variables in Playwright pattern is the backbone of this approach.

Structure your .env files by sandbox

Create a separate .env file for each sandbox your team uses:

SF_ENV=dev
SF_BASE_URL=https://mycompany--dev.sandbox.my.salesforce.com
SF_LOGIN_URL=https://test.salesforce.com
SF_USERNAME=[email protected]
SF_PASSWORD=DevPassword123!SecurityToken
SF_API_VERSION=v60.0

SF_ENV=uat
SF_BASE_URL=https://mycompany--uat.sandbox.my.salesforce.com
SF_LOGIN_URL=https://test.salesforce.com
SF_USERNAME=[email protected]
SF_PASSWORD=UATPassword456!SecurityToken
SF_API_VERSION=v60.0

Switching sandboxes from the command line

With this setup, targeting a specific sandbox is a single environment variable away:

SF_ENV=dev npx playwright test
SF_ENV=uat npx playwright test
SF_ENV=staging npx playwright test

Parameterized tests across sandboxes

For teams that need to validate tests across multiple sandboxes in a single pipeline run, Playwright parameterized tests let you matrix across environments:

const sandboxes = (process.env.SF_SANDBOXES || 'dev').split(',');

export default defineConfig({

  projects: sandboxes.flatMap((env) => [
    {
      name: `${env}-setup`,
      testMatch: /.*\.setup\.ts/,
      use: { baseURL: process.env[`SF_BASE_URL_${env.toUpperCase()}`] },
    },
    {
      name: `${env}-tests`,
      dependencies: [`${env}-setup`],
      use: {
        baseURL: process.env[`SF_BASE_URL_${env.toUpperCase()}`],
        storageState: `playwright/.auth/sf-user-${env}.json`,
      },
    },
  ]),
});

This configuration dynamically generates Playwright projects for each sandbox, complete with isolated auth state files. When a sandbox is refreshed, you update its secrets in your CI/CD platform and the pipeline adapts automatically.

Validating environment configuration at startup

A small but high-impact addition is validating that all required environment variables are present before tests run. Without this, a missing secret produces a cryptic runtime error 5 minutes into the pipeline instead of an immediate failure:

const requiredVars = ['SF_BASE_URL', 'SF_LOGIN_URL', 'SF_USERNAME', 'SF_PASSWORD'];
for (const varName of requiredVars) {
  if (!process.env[varName]) {
    throw new Error(`Missing required environment variable: ${varName}`);
  }
}

This environment-driven foundation is what makes the CI/CD pipeline itself refresh-proof. Now, it is time to wire everything into a real pipeline.

Running Salesforce Playwright tests in CI/CD with GitHub Actions

GitHub Actions is one of the most common CI/CD platforms for Playwright test suites. Here is a production-ready workflow that handles sandbox-specific configuration, authentication, and artifact collection. For a deeper walkthrough, the TestDino guide on Playwright in GitHub Actions covers the fundamentals.

The workflow file

name: Salesforce Playwright Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 6 * * 1-5'  # Weekday mornings
  workflow_dispatch:
    inputs:
      sandbox:
        description: 'Target sandbox (dev, uat, staging)'
        required: true
        default: 'dev'
        type: choice
        options:
          - dev
          - uat
          - staging

env:
  SF_ENV: ${{ github.event.inputs.sandbox || 'dev' }}

jobs:
  playwright-tests:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    environment: salesforce-${{ github.event.inputs.sandbox || 'dev' }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - name: Install dependencies
        run: npm ci
      - name: Install Playwright browsers
        run: npx playwright install --with-deps chromium
      - name: Run Salesforce Playwright tests
        run: npx playwright test
        env:
          SF_BASE_URL: ${{ secrets.SF_BASE_URL }}
          SF_LOGIN_URL: ${{ secrets.SF_LOGIN_URL }}
          SF_USERNAME: ${{ secrets.SF_USERNAME }}
          SF_PASSWORD: ${{ secrets.SF_PASSWORD }}
          SF_API_VERSION: ${{ secrets.SF_API_VERSION }}
          CI: true
      - name: Upload test report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-report-${{ env.SF_ENV }}
          path: playwright-report/
          retention-days: 14
      - name: Upload traces on failure
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-traces-${{ env.SF_ENV }}
          path: test-results/
          retention-days: 7

Key design decisions in this workflow

GitHub Environments for sandbox isolation: Each sandbox (salesforce-dev, salesforce-uat, salesforce-staging) is configured as a separate GitHub Environment with its own set of secrets. When a sandbox is refreshed, you update only that environment's secrets. No code changes required.

workflow_dispatch for manual sandbox targeting: After a refresh, your team can manually trigger the pipeline against the refreshed sandbox to verify everything works before merging PRs.

Scheduled runs for early detection: The weekday morning cron job catches refresh-related breakages before the team starts working. If someone refreshed a sandbox the previous evening, the morning run surfaces the issue immediately.

For larger test suites, Playwright test sharding can split the execution across multiple CI runners to keep feedback loops fast. You can use TestDino's free sharding calculator to determine the optimal number of shards for your suite size and target CI duration.

The pipeline is now wired up. But Salesforce's UI has unique characteristics that need specific handling in your test code.

Handling Salesforce-specific UI challenges in Playwright

Generic Playwright guides assume you are testing a standard React or Angular app. Salesforce Lightning Experience is built on the Aura framework and Lightning Web Components, both of which introduce UI patterns that need special attention in your test selectors and wait strategies. Following best practices for Playwright helps, but Salesforce adds its own layer of complexity.

Shadow DOM in Lightning Web Components

Lightning Web Components encapsulate their internal DOM inside shadow roots. This means standard CSS selectors cannot reach elements inside a component's boundary. Playwright's built-in locators (getByRole, getByLabel, getByText) natively pierce open shadow roots, which is a significant advantage over older tools. The piercing the Shadow DOM in Salesforce guide covers this in detail.

import { test, expect } from '@playwright/test';

test('create a new Account record', async ({ page }) => {
  await page.goto('/lightning/o/Account/new');

  // WRONG: Dynamic ID that changes every render
  // await page.fill('#input-341', 'Test Account');

  // RIGHT: Semantic locator that survives releases and refreshes
  await page.getByRole('textbox', { name: 'Account Name' }).fill('Test Account');
  await page.getByRole('button', { name: 'Save' }).click();
  await expect(page.locator('.toastMessage')).toContainText('created');
});

The right Playwright locators strategy for Salesforce prioritizes ARIA roles, labels, and visible text over CSS selectors tied to auto-generated class names or dynamic IDs. The handling Salesforce dynamic IDs guide explains why Salesforce generates IDs like input-341 that change every render.

Dealing with Salesforce's loading states

Salesforce Lightning pages go through multiple loading phases: the framework loads, then the page layout loads, then individual components fetch their data. Playwright's auto waiting handles basic element readiness, but you often need explicit waits for Salesforce-specific loading indicators:

import { Page } from '@playwright/test';

export async function waitForLightningReady(page: Page) {
  // Wait for the Lightning spinner to disappear

  await page.locator('.slds-spinner_container').waitFor({
    state: 'detached',
    timeout: 15_000,
  });

  // Wait for network to settle (Aura actions complete)
  await page.waitForLoadState('networkidle');
}

Handling Visualforce iframes

If your Salesforce org includes Visualforce pages embedded in Lightning, those pages render inside iframes from a different subdomain (*.visualforce.com). You need Playwright's frameLocator() to interact with elements inside them:

import { test, expect } from '@playwright/test';

test('interact with a Visualforce page', async ({ page }) => {
  await page.goto('/lightning/n/MyVFPage');
  const vfFrame = page.frameLocator('iframe[title="MyVFPage"]');
  await vfFrame.getByRole('textbox', { name: 'Input Field' }).fill('Test Value');
  await vfFrame.getByRole('button', { name: 'Submit' }).click();
});

Using the page object model for Salesforce

Organizing your Salesforce-specific selectors and actions into page objects keeps your tests maintainable across refreshes. The Playwright page object model is especially valuable for Salesforce because the UI structure tends to be consistent across orgs (even after refreshes), but the selectors for finding elements need careful encapsulation.

import { Page } from '@playwright/test';

export class SalesforceLoginPage {
  constructor(private page: Page) {}
  async login(username: string, password: string) {
    await this.page.goto(process.env.SF_LOGIN_URL!);
    await this.page.getByLabel('Username').fill(username);
    await this.page.getByLabel('Password').fill(password);
    await this.page.getByRole('button', { name: 'Log In' }).click();
    await this.page.waitForURL('**/lightning/**', { timeout: 30_000 });
  }
}

Tip: Use the TestDino Playwright skill in VS Code to generate page objects and test files from natural language descriptions. It reads your project's existing fixtures and config, so the generated code stays consistent with your Salesforce-specific patterns.

With UI-level challenges addressed, the final piece is building an automated recovery workflow so your pipeline heals itself after a refresh.

Post-refresh recovery: keeping your pipeline green

Even with a fully externalized config and robust auth layer, a sandbox refresh still requires someone to update the new credentials and verify the pipeline. The goal is to minimize that manual effort to under 10 minutes.

Automating post-refresh setup with SandboxPostCopy

Salesforce provides the SandboxPostCopy Apex interface to automate post-refresh remediation. This runs automatically after the sandbox finishes refreshing, before anyone touches the org:

global class PostRefreshAutomation implements SandboxPostCopy {
    global void runApexClass(SandboxContext context) {
        // 1. Remove .invalid from CI/CD automation user emails
        List<User> testUsers = [
            SELECT Id, Email FROM User
            WHERE Username LIKE 'automation%@company.com%'
        ];
        for (User u : testUsers) {
            if (u.Email.endsWith('.invalid')) {
                u.Email = u.Email.removeEnd('.invalid');
            }
        }

        update testUsers;

        // 2. Point integrations to sandbox-safe endpoints
        Integration_Setting__c setting = Integration_Setting__c.getOrgDefaults();
        setting.Payment_Gateway_URL__c = 'https://sandbox-mock.company.com';
        upsert setting;
    }
}

You designate this class during the refresh request in Salesforce Setup. It automatically strips .invalid from your test user emails and reconfigures integration endpoints, eliminating 2 manual steps from the post-refresh checklist.

The post-refresh checklist

Here is what remains after the SandboxPostCopy script runs:

1. Reset the test user password in the refreshed sandbox. Navigate to Setup, find the integration user, and set a new password.
2. Update CI/CD secrets with the new password and any changed URLs. In GitHub Actions, go to Settings > Environments > your sandbox environment > update the relevant secrets.
3. Re-authorize the Connected App if you are using JWT auth. Run sf org login jwt with the new sandbox URL to pre-authorize the integration user.
4. Trigger a manual pipeline run using workflow_dispatch to validate the new configuration.

Automating post-refresh validation

You can extend your pipeline with a dedicated validation workflow that runs a lightweight smoke test immediately after secrets are updated:

name: Post-Refresh Validation
on:
  workflow_dispatch:
    inputs:
      sandbox:
        description: 'Refreshed sandbox to validate'
        required: true
        type: choice
        options:
          - dev
          - uat
          - staging

jobs:
  validate:
    runs-on: ubuntu-latest
    environment: salesforce-${{ github.event.inputs.sandbox }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - name: Run smoke tests only
        run: npx playwright test --grep @smoke
        env:
          SF_BASE_URL: ${{ secrets.SF_BASE_URL }}
          SF_LOGIN_URL: ${{ secrets.SF_LOGIN_URL }}
          SF_USERNAME: ${{ secrets.SF_USERNAME }}
          SF_PASSWORD: ${{ secrets.SF_PASSWORD }}
      - name: Notify team on success
        if: success()
        run: echo "Sandbox ${{ github.event.inputs.sandbox }} validated successfully"
      - name: Notify team on failure
        if: failure()
        run: echo "Sandbox ${{ github.event.inputs.sandbox }} validation FAILED"

Using Playwright tags like @smoke lets you run a focused subset of tests for post-refresh validation without executing the entire suite.

Dealing with flaky tests after a refresh

Sandbox refreshes sometimes introduce transient failures: components load slower on a fresh org, data seeding has not completed, or cached assets are missing. These are not real test failures, and they should not block your team.

A robust retry strategy combined with Playwright flaky test detection helps separate genuine regressions from refresh-related noise. You can estimate the engineering cost of flaky tests in your suite using TestDino's flaky cost calculator to build a business case for investing in stability.

If you are running tests inside Playwright Docker containers in your CI pipeline, make sure the container image includes the correct browser binaries. The official Playwright Docker images (mcr.microsoft.com/playwright) come pre-installed with all browsers and OS-level dependencies, which eliminates a common class of CI failures unrelated to sandbox refreshes.

For teams debugging specific test failures after a refresh, the Playwright debugging guide with traces is invaluable. Traces capture every network request, DOM snapshot, and console log during a test run, giving you a complete reconstruction of what happened when the test failed against the refreshed sandbox.

Conclusion

Running Salesforce Playwright tests in CI/CD across sandbox refreshes comes down to one rule: never hardcode anything a refresh can change.

Externalize credentials, URLs, and org config into environment variables and CI/CD secrets. Use SandboxPostCopy to automate org-side recovery, and frontdoor.jsp to bypass login-form fragility. Together, these cut post-refresh recovery from a full day to under 10 minutes.

Shadow DOM, dynamic loading, and iframes are manageable with semantic locators and smart wait patterns. Tag a subset of tests as smoke tests to validate a refreshed sandbox in minutes. The teams that handle refreshes well are the ones who built their test automation framework with change as the default assumption.

FAQs