TypeScript

介绍

¥Introduction

Playwright 开箱即用地支持 TypeScript。你只需用 TypeScript 编写测试，Playwright 就会读取它们，转换为 JavaScript 并运行。

¥Playwright supports TypeScript out of the box. You just write tests in TypeScript, and Playwright will read them, transform to JavaScript and run.

请注意，Playwright 不会检查类型，即使存在非关键 TypeScript 编译错误，也会运行测试。我们建议你与 Playwright 一起运行 TypeScript 编译器。例如 GitHub actions：

¥Note that Playwright does not check the types and will run tests even if there are non-critical TypeScript compilation errors. We recommend you run TypeScript compiler alongside Playwright. For example on GitHub actions:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    ...
    - name: Run type checks
      run: npx tsc -p tsconfig.json --noEmit
    - name: Run Playwright tests
      run: npx playwright test

对于本地开发，你可以在 watch 模式下运行 tsc，如下所示：

¥For local development, you can run tsc in watch mode like this:

npx tsc -p tsconfig.json --noEmit -w

tsconfig.json

Playwright 将为它加载的每个源文件选取 tsconfig.json。请注意，Playwright 仅支持以下 tsconfig 选项：allowJs、baseUrl、paths 和 references。

¥Playwright will pick up tsconfig.json for each source file it loads. Note that Playwright only supports the following tsconfig options: allowJs, baseUrl, paths and references.

我们建议在测试目录中设置一个单独的 tsconfig.json，以便你可以专门针对测试更改一些首选项。这是一个示例目录结构。

¥We recommend setting up a separate tsconfig.json in the tests directory so that you can change some preferences specifically for the tests. Here is an example directory structure.

src/
    source.ts

tests/
    tsconfig.json  # test-specific tsconfig
    example.spec.ts

tsconfig.json  # generic tsconfig for all typescript sources

playwright.config.ts

tsconfig 路径映射

¥tsconfig path mapping

Playwright 支持 tsconfig.json 中声明的 路径映射。确保 baseUrl 也已设置。

¥Playwright supports path mapping declared in the tsconfig.json. Make sure that baseUrl is also set.

这是一个与 Playwright 一起使用的示例 tsconfig.json：

¥Here is an example tsconfig.json that works with Playwright:

tsconfig.json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@myhelper/*": ["packages/myhelper/*"] // This mapping is relative to "baseUrl".
    }
  }
}

你现在可以使用映射路径导入：

¥You can now import using the mapped paths:

example.spec.ts

import { test, expect } from '@playwright/test';
import { username, password } from '@myhelper/credentials';

test('example', async ({ page }) => {
  await page.getByLabel('User Name').fill(username);
  await page.getByLabel('Password').fill(password);
});

tsconfig 解析

¥tsconfig resolution

默认情况下，Playwright 将通过向上查找目录结构并查找 tsconfig.json 或 jsconfig.json 来查找每个导入文件最近的 tsconfig。这样，你可以创建一个仅用于测试的 tests/tsconfig.json 文件，Playwright 会自动选择它。

¥By default, Playwright will look up a closest tsconfig for each imported file by going up the directory structure and looking for tsconfig.json or jsconfig.json. This way, you can create a tests/tsconfig.json file that will be used only for your tests and Playwright will pick it up automatically.

# Playwright will choose tsconfig automatically
npx playwright test

或者，你可以指定一个 tsconfig 文件在命令行中使用，Playwright 将使用它来处理所有导入的文件，而不仅仅是测试文件。

¥Alternatively, you can specify a single tsconfig file to use in the command line, and Playwright will use it for all imported files, not only test files.

# Pass a specific tsconfig
npx playwright test --tsconfig=tsconfig.test.json

使用 TypeScript 手动编译测试

¥Manually compile tests with TypeScript

有时，Playwright Test 将无法正确转换你的 TypeScript 代码，例如当你使用 TypeScript 的实验性或最新功能（通常在 tsconfig.json 中配置）时。

¥Sometimes, Playwright Test will not be able to transform your TypeScript code correctly, for example when you are using experimental or very recent features of TypeScript, usually configured in tsconfig.json.

在这种情况下，你可以在将测试发送给 Playwright 之前执行自己的 TypeScript 编译。

¥In this case, you can perform your own TypeScript compilation before sending the tests to Playwright.

首先在测试目录中添加一个 tsconfig.json 文件：

¥First add a tsconfig.json file inside the tests directory:

{
    "compilerOptions": {
        "target": "ESNext",
        "module": "commonjs",
        "moduleResolution": "Node",
        "sourceMap": true,
        "outDir": "../tests-out",
    }
}

在 package.json 中，添加两个脚本：

¥In package.json, add two scripts:

{
  "scripts": {
    "pretest": "tsc --incremental -p tests/tsconfig.json",
    "test": "playwright test -c tests-out"
  }
}

pretest 脚本在测试中运行 typescript。test 将运行已生成到 tests-out 目录的测试。-c 参数将测试运行器配置为在 tests-out 目录中查找测试。

¥The pretest script runs typescript on the tests. test will run the tests that have been generated to the tests-out directory. The -c argument configures the test runner to look for tests inside the tests-out directory.

然后 npm run test 将构建测试并运行它们。

¥Then npm run test will build the tests and run them.