跳转到主要内容

身份验证

简介

Playwright 在称为浏览器上下文的隔离环境中执行测试。这种隔离模型提高了可重现性,并防止了级联测试失败。测试可以加载现有的已验证状态。这消除了在每次测试中进行身份验证的需要,并加快了测试执行速度。

核心概念

无论您选择哪种身份验证策略,您都可能会将已验证的浏览器状态存储在文件系统上。

我们建议创建 `playwright/.auth` 目录并将其添加到您的 `.gitignore` 中。您的身份验证例程将生成已验证的浏览器状态并将其保存到此 `playwright/.auth` 目录中的文件中。之后,测试将重用此状态并已验证地启动。

危险

浏览器状态文件可能包含敏感的 cookie 和标头,这些信息可能用于冒充您或您的测试账户。我们强烈不建议将其提交到私有或公共仓库。

mkdir -p playwright/.auth
echo $'\nplaywright/.auth' >> .gitignore

基本:所有测试共用一个账户

对于**没有服务器端状态**的测试,这是**推荐**的方法。在**设置项目**中验证一次,保存验证状态,然后重用它来启动每个已验证的测试。

何时使用

  • 当您可以想象所有测试同时使用同一个帐户运行,而互不影响时。

何时不使用

  • 您的测试会修改服务器端状态。例如,一个测试检查设置页面的渲染,而另一个测试正在更改设置,并且您并行运行测试。在这种情况下,测试必须使用不同的帐户。
  • 您的认证是浏览器特定的。

详情

创建 `tests/auth.setup.ts`,它将为所有其他测试准备已验证的浏览器状态。

tests/auth.setup.ts
import { test as setup, expect } from '@playwright/test';
import path from 'path';

const authFile = path.join(__dirname, '../playwright/.auth/user.json');

setup('authenticate', async ({ page }) => {
// Perform authentication steps. Replace these actions with your own.
await page.goto('https://github.com/login');
await page.getByLabel('Username or email address').fill('username');
await page.getByLabel('Password').fill('password');
await page.getByRole('button', { name: 'Sign in' }).click();
// Wait until the page receives the cookies.
//
// Sometimes login flow sets cookies in the process of several redirects.
// Wait for the final URL to ensure that the cookies are actually set.
await page.waitForURL('https://github.com/');
// Alternatively, you can wait until the page reaches a state where all cookies are set.
await expect(page.getByRole('button', { name: 'View profile and more' })).toBeVisible();

// End of authentication steps.

await page.context().storageState({ path: authFile });
});

在配置中创建一个新的 `setup` 项目,并将其声明为所有测试项目的依赖。此项目将始终在所有测试之前运行并进行身份验证。所有测试项目都应使用已通过身份验证的状态作为 `storageState`。

playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
projects: [
// Setup project
{ name: 'setup', testMatch: /.*\.setup\.ts/ },

{
name: 'chromium',
use: {
...devices['Desktop Chrome'],
// Use prepared auth state.
storageState: 'playwright/.auth/user.json',
},
dependencies: ['setup'],
},

{
name: 'firefox',
use: {
...devices['Desktop Firefox'],
// Use prepared auth state.
storageState: 'playwright/.auth/user.json',
},
dependencies: ['setup'],
},
],
});

由于我们在配置中指定了 `storageState`,因此测试在启动时就已通过身份验证。

tests/example.spec.ts
import { test } from '@playwright/test';

test('test', async ({ page }) => {
// page is authenticated
});

请注意,当存储状态过期时,您需要删除它。如果您不需要在测试运行之间保留状态,请将浏览器状态写入testProject.outputDir,该目录在每次测试运行之前会自动清理。

在 UI 模式下进行身份验证

为了提高测试速度,UI 模式默认不会运行 `setup` 项目。我们建议在现有身份验证过期时,不时手动运行 `auth.setup.ts` 进行身份验证。

首先在过滤器中启用 `setup` 项目,然后点击 `auth.setup.ts` 文件旁边的三角形按钮,然后再次在过滤器中禁用 `setup` 项目。

中等:每个并行工作者一个账户

对于**修改服务器端状态**的测试,这是**推荐**的方法。在 Playwright 中,工作进程并行运行。在这种方法中,每个并行工作进程只验证一次。工作进程运行的所有测试都重用相同的验证状态。我们将需要多个测试账户,每个并行工作进程一个。

何时使用

  • 您的测试修改共享的服务器端状态。例如,一个测试检查设置页面的渲染,而另一个测试正在更改设置。

何时不使用

  • 您的测试不修改任何共享服务器端状态。在这种情况下,所有测试都可以使用单个共享帐户。

详情

我们将为每个工作进程进行一次身份验证,每个工作进程使用唯一的账户。

创建 `playwright/fixtures.ts` 文件,该文件将覆盖 `storageState` fixture,以便每个工作进程只进行一次身份验证。使用testInfo.parallelIndex来区分不同的工作进程。

playwright/fixtures.ts
import { test as baseTest, expect } from '@playwright/test';
import fs from 'fs';
import path from 'path';

export * from '@playwright/test';
export const test = baseTest.extend<{}, { workerStorageState: string }>({
// Use the same storage state for all tests in this worker.
storageState: ({ workerStorageState }, use) => use(workerStorageState),

// Authenticate once per worker with a worker-scoped fixture.
workerStorageState: [async ({ browser }, use) => {
// Use parallelIndex as a unique identifier for each worker.
const id = test.info().parallelIndex;
const fileName = path.resolve(test.info().project.outputDir, `.auth/${id}.json`);

if (fs.existsSync(fileName)) {
// Reuse existing authentication state if any.
await use(fileName);
return;
}

// Important: make sure we authenticate in a clean environment by unsetting storage state.
const page = await browser.newPage({ storageState: undefined });

// Acquire a unique account, for example create a new one.
// Alternatively, you can have a list of precreated accounts for testing.
// Make sure that accounts are unique, so that multiple team members
// can run tests at the same time without interference.
const account = await acquireAccount(id);

// Perform authentication steps. Replace these actions with your own.
await page.goto('https://github.com/login');
await page.getByLabel('Username or email address').fill(account.username);
await page.getByLabel('Password').fill(account.password);
await page.getByRole('button', { name: 'Sign in' }).click();
// Wait until the page receives the cookies.
//
// Sometimes login flow sets cookies in the process of several redirects.
// Wait for the final URL to ensure that the cookies are actually set.
await page.waitForURL('https://github.com/');
// Alternatively, you can wait until the page reaches a state where all cookies are set.
await expect(page.getByRole('button', { name: 'View profile and more' })).toBeVisible();

// End of authentication steps.

await page.context().storageState({ path: fileName });
await page.close();
await use(fileName);
}, { scope: 'worker' }],
});

现在,每个测试文件都应该从我们的 fixtures 文件中导入 `test`,而不是从 `@playwright/test` 导入。配置中不需要任何更改。

tests/example.spec.ts
// Important: import our fixtures.
import { test, expect } from '../playwright/fixtures';

test('test', async ({ page }) => {
// page is authenticated
});

高级场景

使用 API 请求进行身份验证

何时使用

  • 您的 Web 应用程序支持通过 API 进行身份验证,这比与应用程序 UI 交互更容易/更快。

详情

我们将使用APIRequestContext发送 API 请求,然后像往常一样保存已通过身份验证的状态。

设置项目

tests/auth.setup.ts
import { test as setup } from '@playwright/test';

const authFile = 'playwright/.auth/user.json';

setup('authenticate', async ({ request }) => {
// Send authentication request. Replace with your own.
await request.post('https://github.com/login', {
form: {
'user': 'user',
'password': 'password'
}
});
await request.storageState({ path: authFile });
});

或者,在工作器 fixture

playwright/fixtures.ts
import { test as baseTest, request } from '@playwright/test';
import fs from 'fs';
import path from 'path';

export * from '@playwright/test';
export const test = baseTest.extend<{}, { workerStorageState: string }>({
// Use the same storage state for all tests in this worker.
storageState: ({ workerStorageState }, use) => use(workerStorageState),

// Authenticate once per worker with a worker-scoped fixture.
workerStorageState: [async ({}, use) => {
// Use parallelIndex as a unique identifier for each worker.
const id = test.info().parallelIndex;
const fileName = path.resolve(test.info().project.outputDir, `.auth/${id}.json`);

if (fs.existsSync(fileName)) {
// Reuse existing authentication state if any.
await use(fileName);
return;
}

// Important: make sure we authenticate in a clean environment by unsetting storage state.
const context = await request.newContext({ storageState: undefined });

// Acquire a unique account, for example create a new one.
// Alternatively, you can have a list of precreated accounts for testing.
// Make sure that accounts are unique, so that multiple team members
// can run tests at the same time without interference.
const account = await acquireAccount(id);

// Send authentication request. Replace with your own.
await context.post('https://github.com/login', {
form: {
'user': 'user',
'password': 'password'
}
});

await context.storageState({ path: fileName });
await context.dispose();
await use(fileName);
}, { scope: 'worker' }],
});

多角色登录

何时使用

  • 您的端到端测试中有多个角色,但您可以在所有测试中重用账户。

详情

我们将在设置项目中进行多次身份验证。

tests/auth.setup.ts
import { test as setup, expect } from '@playwright/test';

const adminFile = 'playwright/.auth/admin.json';

setup('authenticate as admin', async ({ page }) => {
// Perform authentication steps. Replace these actions with your own.
await page.goto('https://github.com/login');
await page.getByLabel('Username or email address').fill('admin');
await page.getByLabel('Password').fill('password');
await page.getByRole('button', { name: 'Sign in' }).click();
// Wait until the page receives the cookies.
//
// Sometimes login flow sets cookies in the process of several redirects.
// Wait for the final URL to ensure that the cookies are actually set.
await page.waitForURL('https://github.com/');
// Alternatively, you can wait until the page reaches a state where all cookies are set.
await expect(page.getByRole('button', { name: 'View profile and more' })).toBeVisible();

// End of authentication steps.

await page.context().storageState({ path: adminFile });
});

const userFile = 'playwright/.auth/user.json';

setup('authenticate as user', async ({ page }) => {
// Perform authentication steps. Replace these actions with your own.
await page.goto('https://github.com/login');
await page.getByLabel('Username or email address').fill('user');
await page.getByLabel('Password').fill('password');
await page.getByRole('button', { name: 'Sign in' }).click();
// Wait until the page receives the cookies.
//
// Sometimes login flow sets cookies in the process of several redirects.
// Wait for the final URL to ensure that the cookies are actually set.
await page.waitForURL('https://github.com/');
// Alternatively, you can wait until the page reaches a state where all cookies are set.
await expect(page.getByRole('button', { name: 'View profile and more' })).toBeVisible();

// End of authentication steps.

await page.context().storageState({ path: userFile });
});

之后,为每个测试文件或测试组指定 `storageState`,**而不是**在配置中设置它。

tests/example.spec.ts
import { test } from '@playwright/test';

test.use({ storageState: 'playwright/.auth/admin.json' });

test('admin test', async ({ page }) => {
// page is authenticated as admin
});

test.describe(() => {
test.use({ storageState: 'playwright/.auth/user.json' });

test('user test', async ({ page }) => {
// page is authenticated as a user
});
});

另请参阅有关在 UI 模式下进行身份验证的内容。

同时测试多个角色

何时使用

  • 您需要在单个测试中测试多个已通过身份验证的角色如何协同工作。

详情

在同一个测试中使用多个具有不同存储状态的BrowserContextPage

tests/example.spec.ts
import { test } from '@playwright/test';

test('admin and user', async ({ browser }) => {
// adminContext and all pages inside, including adminPage, are signed in as "admin".
const adminContext = await browser.newContext({ storageState: 'playwright/.auth/admin.json' });
const adminPage = await adminContext.newPage();

// userContext and all pages inside, including userPage, are signed in as "user".
const userContext = await browser.newContext({ storageState: 'playwright/.auth/user.json' });
const userPage = await userContext.newPage();

// ... interact with both adminPage and userPage ...

await adminContext.close();
await userContext.close();
});

使用 POM fixture 测试多个角色

何时使用

  • 您需要在单个测试中测试多个已通过身份验证的角色如何协同工作。

详情

您可以引入 fixture,它们将提供一个作为每个角色进行身份验证的页面。

下面是一个创建 fixture 的示例,用于两个页面对象模型 - admin POM 和 user POM。它假设 `adminStorageState.json` 和 `userStorageState.json` 文件是在全局设置中创建的。

playwright/fixtures.ts
import { test as base, type Page, type Locator } from '@playwright/test';

// Page Object Model for the "admin" page.
// Here you can add locators and helper methods specific to the admin page.
class AdminPage {
// Page signed in as "admin".
page: Page;

// Example locator pointing to "Welcome, Admin" greeting.
greeting: Locator;

constructor(page: Page) {
this.page = page;
this.greeting = page.locator('#greeting');
}
}

// Page Object Model for the "user" page.
// Here you can add locators and helper methods specific to the user page.
class UserPage {
// Page signed in as "user".
page: Page;

// Example locator pointing to "Welcome, User" greeting.
greeting: Locator;

constructor(page: Page) {
this.page = page;
this.greeting = page.locator('#greeting');
}
}

// Declare the types of your fixtures.
type MyFixtures = {
adminPage: AdminPage;
userPage: UserPage;
};

export * from '@playwright/test';
export const test = base.extend<MyFixtures>({
adminPage: async ({ browser }, use) => {
const context = await browser.newContext({ storageState: 'playwright/.auth/admin.json' });
const adminPage = new AdminPage(await context.newPage());
await use(adminPage);
await context.close();
},
userPage: async ({ browser }, use) => {
const context = await browser.newContext({ storageState: 'playwright/.auth/user.json' });
const userPage = new UserPage(await context.newPage());
await use(userPage);
await context.close();
},
});

tests/example.spec.ts
// Import test with our new fixtures.
import { test, expect } from '../playwright/fixtures';

// Use adminPage and userPage fixtures in the test.
test('admin and user', async ({ adminPage, userPage }) => {
// ... interact with both adminPage and userPage ...
await expect(adminPage.greeting).toHaveText('Welcome, Admin');
await expect(userPage.greeting).toHaveText('Welcome, User');
});

会话存储

重用已验证状态涵盖了基于Cookie本地存储IndexedDB 的身份验证。很少有情况下,会话存储用于存储与登录状态相关的信息。会话存储特定于特定域,并且不会跨页面加载持久化。Playwright 不提供 API 来持久化会话存储,但可以使用以下代码片段来保存/加载会话存储。

// Get session storage and store as env variable
const sessionStorage = await page.evaluate(() => JSON.stringify(sessionStorage));
fs.writeFileSync('playwright/.auth/session.json', sessionStorage, 'utf-8');

// Set session storage in a new context
const sessionStorage = JSON.parse(fs.readFileSync('playwright/.auth/session.json', 'utf-8'));
await context.addInitScript(storage => {
if (window.location.hostname === 'example.com') {
for (const [key, value] of Object.entries(storage))
window.sessionStorage.setItem(key, value);
}
}, sessionStorage);

在某些测试中避免身份验证

您可以在测试文件中重置存储状态,以避免为整个项目设置的身份验证。

未登录.spec.ts
import { test } from '@playwright/test';

// Reset storage state for this file to avoid being authenticated
test.use({ storageState: { cookies: [], origins: [] } });

test('not signed in test', async ({ page }) => {
// ...
});