编写Playwright测试

我们的Playwright测试是使用Playwright测试框架编写的。我们使用这些测试来测试我们的示例并确保它们按预期工作，从而确保我们的包按预期工作。

在本指南中，我们将向您展示如何为我们的示例编写Playwright测试、创建新的示例并对其进行测试。

针对现有示例进行测试

如果您想使用现有示例，您可以在utils/ExampleRunner/example-info.json文件中找到示例列表。您可以使用exampleName属性引用您想要使用的示例。例如，如果您想使用annotationToolModes示例，可以使用以下代码片段：

import { test } from '@playwright/test';
import { visitExample } from './utils/index';

test.beforeEach(async ({ page }) => {
  await visitExample(page, 'annotationToolModes');
});

test.describe('Annotation Tool Modes', async () => {
  test('should do something', async ({ page }) => {
    // Your test code here
  });
});

针对新示例进行测试

我们的Playwright测试是针对我们的示例运行的，如果您想添加一个新示例，可以将其添加到相应包的根目录下的examples文件夹中，例如，packages/tools/examples/{your_example_name}/index.ts，然后在utils/ExampleRunner/example-info.json文件中将其注册到正确的类别下，例如，如果它与工具相关，可以放入现有的tools-basic类别。如果找不到适合您示例的类别，可以创建一个新类别，并将其添加到example-info.json文件中的categories对象中。

{
  "categories": {
    "tools-basic": {
      "description": "Tools library"
    },
    "examplesByCategory": {
      "tools-basic": {
        "your_example_name": {
          "name": "Good title for your example",
          "description": "Good description of what your example demonstrates"
        }
      }
    }
  }
}

完成此操作后，您可以通过使用tests/utils/visitExample.ts文件中的visitExample函数来针对该示例编写测试。例如，如果您想针对your_example_name示例编写测试，可以使用以下代码片段：

import { test } from '@playwright/test';
import { visitExample } from './utils/index';

test.beforeEach(async ({ page }) => {
  await visitExample(page, 'your_example_name');
});

test.describe('Your Example Name', async () => {
  test('should do something', async ({ page }) => {
    // Your test code here
  });
});

这还会使您的示例出现在我们的文档页面上，以便用户可以了解如何使用该示例，因此通过添加新示例您可以增加双重价值。

截图

检查测试是否按预期工作的一个好方法是在测试的不同阶段捕获截图。您可以使用位于tests/utils/checkForScreenshot.ts中的checkForScreenshot函数来捕获截图。您还应提前规划好截图，截图需要在tests/utils/screenshotPaths.ts文件中定义。例如，如果您想在添加测量后捕获截图，可以这样定义截图路径：

const screenShotPaths = {
  your_example_name: {
    measurementAdded: 'measurementAdded.png',
    measurementRemoved: 'measurementRemoved.png',
  },
};

即使截图尚不存在也没关系，这将在下一步中解决。一旦定义了截图路径，就可以在测试中使用checkForScreenshot函数来捕获截图。例如，如果您想在添加测量后捕获.cornerstone-canvas元素的截图，可以使用以下代码片段：

import { test } from '@playwright/test';
import {
  visitExample,
  checkForScreenshot,
  screenshotPath,
} from './utils/index';

test.beforeEach(async ({ page }) => {
  await visitExample(page, 'your_example_name');
});

test.describe('Your Example Name', async () => {
  test('should do something', async ({ page }) => {
    // Your test code here to add a measurement
    const locator = page.locator('.cornerstone-canvas');
    await checkForScreenshot(
      page,
      locator,
      screenshotPath.your_example_name.measurementAdded
    );
  });
});

首次运行测试时，测试将自动失败，但它会为您生成截图。您会注意到在tests/screenshots文件夹中有三项新条目，分别是在chromium/your-example.spec.js/measurementAdded.png、firefox/your-example.spec.js/measurementAdded.png和webkit/your-example.spec.js/measurementAdded.png文件夹下。您现在可以再次运行测试，它将使用这些截图来与示例的当前状态进行比较。请在提交或对其进行测试之前验证基准截图是否正确。

模拟鼠标拖拽

如果您想模拟鼠标拖拽，可以使用位于tests/utils/simulateDrag.ts中的simulateDrag函数。您可以使用此函数来模拟对元素的鼠标拖拽。例如，如果您想模拟对.cornerstone-canvas元素的鼠标拖拽，可以使用以下代码片段：

import {
  visitExample,
  checkForScreenshot,
  screenShotPaths,
  simulateDrag,
} from './utils/index';

test.beforeEach(async ({ page }) => {
  await visitExample(page, 'stackManipulationTools');
});

test.describe('Basic Stack Manipulation', async () => {
  test('should manipulate the window level using the window level tool', async ({
    page,
  }) => {
    await page.getByRole('combobox').selectOption('WindowLevel');
    const locator = page.locator('.cornerstone-canvas');
    await simulateDrag(page, locator);
    await checkForScreenshot(
      page,
      locator,
      screenShotPaths.stackManipulationTools.windowLevel
    );
  });
});

我们的模拟拖拽工具可以模拟对任何元素的拖拽，并避免超出边界。它会计算元素的边界框，确保拖拽动作保持在元素的边界内。这对于大多数工具应该已经足够好，比提供自定义的x和y坐标更好，因为自定义坐标容易出错，并且使代码难以维护。

运行测试

编写测试后，可以通过使用以下命令来运行它们：

yarn test:e2e:ci

如果您想使用头部模式，可以使用以下命令：

yarn test:e2e:headed

您将在终端中看到测试结果，如果想要详细报告，可以使用以下命令：

yarn playwright show-report tests/playwright-report

手动服务示例以便开发

默认情况下，当您运行测试时，它会调用yarn build-and-serve-static-examples命令首先提供示例服务，然后运行测试，如果您想手动提供示例服务，可以使用相同的命令。示例将可在http://localhost:3000上获得。这可以加速您的开发过程，因为Playwright将跳过构建和服务步骤，并使用3000端口上的现有服务器。

Playwright VSCode扩展和录制测试

如果您正在使用VSCode，可以使用Playwright扩展来帮助您编写测试。该扩展提供了一个测试运行程序和许多强大功能，例如使用鼠标选择定位器、录制新测试等。您可以通过在VSCode的扩展选项卡中搜索Playwright或者访问Playwright扩展页面来安装该扩展。