README.md · 王泰/EasyAutoTest

# EasyAutoTest

## 介绍

端到端自动化测试框架，基于Java8+SpringBoot2.7+TestNG7.4+Playwright1.41.2开发，使用了**页面对象模式**和**数据驱动模式**方便后期版本迭代维护。

**变大变长，再创辉煌**

```ini
,------.                        ,---.            ,--.        ,--------.              ,--.
|  .---' ,--,--. ,---.,--. ,--./  O  \ ,--.,--.,-'  '-. ,---.'--.  .--',---.  ,---.,-'  '-.
|  `--, ' ,-.  |(  .-' \  '  /|  .-.  ||  ||  |'-.  .-'| .-.    |  |  | .-. :(  .-''-.  .-'
|  `---.\ '-'  |.-'  `) \   ' |  | |  |'  ''  '  |  |  ' '-'    |  |  \   --..-'  `) |  |
`------' `--`--'`----'.-'  /  `--' `--' `----'   `--'   `---'   `--'   `----'`----'  `--'
```

## 目录解释

```ini
- src
    - main
        - config   配置类
        - core     基类和一些扩展，例如截图监听，发邮件，报告
        - job      定时任务
        - dev      开发过程中会使用的工具，安装浏览器，脚本录制，查看trace.zip
        - utils    工具类的代码
        - testcase 存放测试case，测试类都已Test结尾，继承BasePageTest类
        - page     存放页面对象，每个页面一个对象，包含页面元素定位和控件操作，不要把对象中元素暴露出去。
        - AutoTestApplication.java 启动类
    - resources  配置文件
        - application.yaml 配置文件
        - testng.xml testng配置文件
- data       存放测试过程中使用到的数据,json,excel等
- report     存放测试报告
- screenshot 存放错误测试case的截图
- trace      存放错误case录制追踪
- videos     存放错误case录制视频
```

## 系统要求

> https://playwright.dev/java/docs/intro#system-requirements

- Java 8 or higher.
- Windows 10+, Windows Server 2016+ or Windows Subsystem for Linux (WSL).
- MacOS 12 Monterey, MacOS 13 Ventura, or MacOS 14 Sonoma.
- Debian 11, Debian 12, Ubuntu 20.04 or Ubuntu 22.04.

**注意**：**playwright在centos上部署官方是不支持的**，[github issue](https://github.com/microsoft/playwright/issues/9194)

> 实在想跑就用docker跑吧

## 开发阶段

> 如果你是一个图快的人，直接去`Record.java`去执行脚本录制吧！
>
> 然后代码贴进来就能跑，但是这个代码基本不可迭代。

### 第一步 修改配置

> 根据自己的需求修改如下配置，也可以使用**默认**，**默认**，**默认**的。

**application.yaml**

```yaml
spring:
  #邮箱配置
  mail:
    host: smtp.qq.com
    # 邮箱
    username: 93xxx66@qq.com
    # 邮箱的授权码
    password: nsssssssssss
    #默认UTF-8
    default-encoding: UTF-8
    properties:
      mail:
        smtp:
          auth: true
          starttls:
            enable: true
            required: true
easy:
  # 是否开启发送邮件，默认false
  send-email: false
  # 收件人邮箱列表
  send-to:
    - example1@example.com
    - example2@example.com
  # 是否用自定义增强报告
  enhanced-report: false
  # playwright启动参数
  launch-options:
    # 是否启用无头模式
    headless: true
    # 等待浏览器实例启动时间
    timeout: 10000
    # 慢模式毫秒数，模拟人的等待操作时间
    slow-mo: 100
  context-options:
    # 设置默认操作超时时间为10秒
    timeout: 10000
  # 定时任务
  cronjob:
    # 是否开启定时任务，默认开启
    enabled: true
    # 指定两次任务执行之间的延迟时间，单位毫秒
    fixedDelayMillis: 30000
  trace-options:
    # 是否开启错误trace
    trace-enable: true
    # 是否开启错误截图，鸡肋 经常截图不准
    screenshot-enable: false
    # 是否开启错误录屏，这个有点儿鸡肋
    video-enable: false
  retry-options:
    # 最大重试次数
    max-retry-count: 3
  cleanfile:
    # 定时删除几天前的文件
    days: 1
```

**testng.xml**

> 目前并行级别只支持"classes"级别。

```xml
<!DOCTYPE suite SYSTEM "http://beust.com/testng/testng-1.0.dtd" >
<suite name="自动化端到端测试" parallel="classes" thread-count="3" verbose="2">
    <test name="autoui-test">
        <packages>
            <package name="com.laker.autotest.testcase.*"/>
        </packages>
    </test>
</suite>
```

### 第二步 写测试Case

> 在框架中我已经预写了几个case供大家参考。

以百度搜索“lakernote”示例，分为如下几步。

**第一步** 确认有几个页面对象，这里只有一个页面

- 新建`BaiduHomePage.java`继承`BasePage`
- 当前页面的Url`https://www.baidu.com`

```java
public class BaiduHomePage extends BasePage {
    private final String URL = "https://www.baidu.com";
    public BaiduHomePage(Page initPage) {
        super(initPage);
    }
    @Override
    protected String pageUrl() {
        return URL;
    }
```

**第二步** 确认每个页面的元素有哪些，如何定位以及对应的操作

- 搜索框 `searchTermInput`
- 结果列表内容 `contentLeft`
- 搜索操作 `search(searchTerm)`

> 注意：
>
> 1.页面对象中的元素设计时不要被外部访问
>
> 2.当前每个元素都是在对象初始化时定位的，对于动态页面有可能不对，在具体的元素操作时
>
> 可以调用waitfor();

```java
public class BaiduHomePage extends BasePage {
    private final String URL = "https://www.baidu.com";
    private final Locator searchTermInput;
    private final Locator contentLeft;

public BaiduHomePage(Page initPage) {
        super(initPage);
        // 搜索框
        searchTermInput = getComponentById("kw");
        // 结果列表内容
        contentLeft = getComponentById("content_left");
    }

@Override
    protected String pageUrl() {
        return URL;
    }

public void search(String searchTerm) {
        searchTermInput.click();
        searchTermInput.fill(searchTerm);
        searchTermInput.press("Enter");

}

public String getContentLeftContent() {
        return contentLeft.innerText();
    }
}
```

**第三步** 新建测试case

注意继承`BasePageTest`

```java
public class BaiduPageTest extends BasePageTest {

@Test
    public void search() {
        BaiduHomePage baiduHomePage = new BaiduHomePage(page);
        baiduHomePage.search("lakernote");
        String contentLeftContent = baiduHomePage.getContentLeftContent();
        Assert.assertTrue(contentLeftContent.contains("lakernote-CSDN博客"));
    }

}
```

### 第三步 启动测试

运行`AutoTestApplication.java`中main函数即可。

**观察日志如下**：

```ini
2024-03-12 21:58:24.916  INFO 6756 --- [   scheduling-1] com.laker.autotest.job.CronJob           : Starting TestNG job at Tue Mar 12 21:58:24 GMT+08:00 2024
...
... TestNG 7.4.0 by Cédric Beust (cedric@beust.com)
...

Skipping browsers download because `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` env variable is set
2024-03-12 21:58:31.910  INFO 6756 --- [t=autoui-test-2] com.laker.autotest.core.BasePageTest     : CsdnPageTest 1993142577 Browser launched
2024-03-12 21:58:32.083  INFO 6756 --- [t=autoui-test-3] com.laker.autotest.core.BasePageTest     : GiteePageTest 1692776273 Browser launched
2024-03-12 21:58:32.243  INFO 6756 --- [t=autoui-test-1] com.laker.autotest.core.BasePageTest     : CsdnPageTest 1993142577 Context and page created
...
2024-03-12 21:59:22.694  WARN 6756 --- [t=autoui-test-3] c.l.autotest.core.retry.RetryAnalyzer    : Retrying test 自动化端到端测试 com.laker.autotest.testcase.GiteePageTest.搜索并star,remaining 0 attempts.
2024-03-12 21:59:31.093  INFO 6756 --- [t=autoui-test-3] com.laker.autotest.core.BasePageTest     : GiteePageTest 1692776273 Browser closed

===============================================
自动化端到端测试
Total tests run: 7, Passes: 4, Failures: 0, Skips: 0, Retries: 3
===============================================

2024-03-12 21:59:31.133  INFO 6756 --- [   scheduling-1] com.laker.autotest.job.CronJob           : TestNG job completed at Tue Mar 12 21:59:31 GMT+08:00 2024
```

### 第四步 查看测试报告

![](docs/images/report.png)

### 第五步 查看异常Trace

![](docs/images/trace.png)

## 打包部署

### 第一步 本地打包并上传

```sh
mvn clean package
```

然后把`easy-autotest.jar`上传到服务器

> 目录为`target/easy-autotest.jar`

### 第二步 服务器安装Chrome浏览器和其依赖

> **注意不支持Centos**。

```sh
# 程序会自动安装 chromium
# 或者执行如下命令，观察安装进度
java -jar easy-autotest.jar install --with-deps chromium
```

### 第三步 启动自动化测试

```sh
nohup java -jar easy-autotest.jar &
```

## FQA

### 定时执行和发邮件

这里在框架中自带了定时执行和发邮件，也可以用Jenkins来替代这两个功能。

### 脚本录制

参考：Record.java

### 失败截图

参考：ScreenshotListener.java

### 失败重试

参考：

- RetryAnnotationTransformer.java
- RetryAnalyzer.java

### 内置浏览器下载加速

**playwright**默认会从Azure `https://playwright.azureedge.net `下载，国内网访问有时下载很慢。

设置`PLAYWRIGHT_DOWNLOAD_HOST`为国内的下载源即可。

```java
Playwright.CreateOptions createOptions = new Playwright.CreateOptions();
Map<String, String> env = new HashMap<>();
env.put("PLAYWRIGHT_DOWNLOAD_HOST", "https://registry.npmmirror.com/-/binary/playwright");
createOptions.setEnv(env);
Playwright.create(createOptions);
```

### 自动等待问题

在执行操作之前，Playwright会对元素进行一系列可操作性检查，以确保这些操作按预期执行。它会自动等待所有相关检查通过，然后才执行请求的操作。如果在给定的超时时间内未通过所需的检查，操作将因超时错误而失败。

例如，对于 Locator.click()，Playwright 将确保：

- 定位器解析为恰好一个元素

- 元素是可见的
- 元素是稳定的，意味着不在动画过程中或已完成动画
- 元素可接收事件，意味着不被其他元素遮挡 元
- 素是启用的

以下是每个操作执行的所有可操作性检查的完整列表：

| Action                                                       | [Visible](https://playwright.dev/java/docs/actionability#visible) | [Stable](https://playwright.dev/java/docs/actionability#stable) | [Receives Events](https://playwright.dev/java/docs/actionability#receives-events) | [Enabled](https://playwright.dev/java/docs/actionability#enabled) | [Editable](https://playwright.dev/java/docs/actionability#editable) |
| :----------------------------------------------------------- | :----------------------------------------------------------: | :----------------------------------------------------------: | :----------------------------------------------------------: | :----------------------------------------------------------: | :----------------------------------------------------------: |
| [Locator.check()](https://playwright.dev/java/docs/api/class-locator#locator-check) |                             Yes                              |                             Yes                              |                             Yes                              |                             Yes                              |                              -                               |
| [Locator.click()](https://playwright.dev/java/docs/api/class-locator#locator-click) |                             Yes                              |                             Yes                              |                             Yes                              |                             Yes                              |                              -                               |
| [Locator.dblclick()](https://playwright.dev/java/docs/api/class-locator#locator-dblclick) |                             Yes                              |                             Yes                              |                             Yes                              |                             Yes                              |                              -                               |
| [Locator.setChecked()](https://playwright.dev/java/docs/api/class-locator#locator-set-checked) |                             Yes                              |                             Yes                              |                             Yes                              |                             Yes                              |                              -                               |
| [Locator.tap()](https://playwright.dev/java/docs/api/class-locator#locator-tap) |                             Yes                              |                             Yes                              |                             Yes                              |                             Yes                              |                              -                               |
| [Locator.uncheck()](https://playwright.dev/java/docs/api/class-locator#locator-uncheck) |                             Yes                              |                             Yes                              |                             Yes                              |                             Yes                              |                              -                               |
| [Locator.hover()](https://playwright.dev/java/docs/api/class-locator#locator-hover) |                             Yes                              |                             Yes                              |                             Yes                              |                              -                               |                              -                               |
| [Locator.dragTo()](https://playwright.dev/java/docs/api/class-locator#locator-drag-to) |                             Yes                              |                             Yes                              |                             Yes                              |                              -                               |                              -                               |
| [Locator.screenshot()](https://playwright.dev/java/docs/api/class-locator#locator-screenshot) |                             Yes                              |                             Yes                              |                              -                               |                              -                               |                              -                               |
| [Locator.fill()](https://playwright.dev/java/docs/api/class-locator#locator-fill) |                             Yes                              |                              -                               |                              -                               |                             Yes                              |                             Yes                              |
| [Locator.clear()](https://playwright.dev/java/docs/api/class-locator#locator-clear) |                             Yes                              |                              -                               |                              -                               |                             Yes                              |                             Yes                              |
| [Locator.selectOption()](https://playwright.dev/java/docs/api/class-locator#locator-select-option) |                             Yes                              |                              -                               |                              -                               |                             Yes                              |                              -                               |
| [Locator.selectText()](https://playwright.dev/java/docs/api/class-locator#locator-select-text) |                             Yes                              |                              -                               |                              -                               |                              -                               |                              -                               |
| [Locator.scrollIntoViewIfNeeded()](https://playwright.dev/java/docs/api/class-locator#locator-scroll-into-view-if-needed) |                              -                               |                             Yes                              |                              -                               |                              -                               |                              -                               |
| [Locator.blur()](https://playwright.dev/java/docs/api/class-locator#locator-blur) |                              -                               |                              -                               |                              -                               |                              -                               |                              -                               |
| [Locator.dispatchEvent()](https://playwright.dev/java/docs/api/class-locator#locator-dispatch-event) |                              -                               |                              -                               |                              -                               |                              -                               |                              -                               |
| [Locator.focus()](https://playwright.dev/java/docs/api/class-locator#locator-focus) |                              -                               |                              -                               |                              -                               |                              -                               |                              -                               |
| [Locator.press()](https://playwright.dev/java/docs/api/class-locator#locator-press) |                              -                               |                              -                               |                              -                               |                              -                               |                              -                               |
| [Locator.pressSequentially()](https://playwright.dev/java/docs/api/class-locator#locator-press-sequentially) |                              -                               |                              -                               |                              -                               |                              -                               |                              -                               |
| [Locator.setInputFiles()](https://playwright.dev/java/docs/api/class-locator#locator-set-input-files) |                              -                               |                              -                               |                              -                               |                              -                               |                              -                               |

### 断言相关问题

Playwright 包括自动重试的断言功能，通过等待条件满足来消除不稳定性，类似于在操作之前进行自动等待。

| Assertion                                                    | Description                       |
| :----------------------------------------------------------- | :-------------------------------- |
| [assertThat(locator).isAttached()](https://playwright.dev/java/docs/api/class-locatorassertions#locator-assertions-to-be-attached) | Element is attached               |
| [assertThat(locator).isChecked()](https://playwright.dev/java/docs/api/class-locatorassertions#locator-assertions-to-be-checked) | Checkbox is checked               |
| [assertThat(locator).isDisabled()](https://playwright.dev/java/docs/api/class-locatorassertions#locator-assertions-to-be-disabled) | Element is disabled               |
| [assertThat(locator).isEditable()](https://playwright.dev/java/docs/api/class-locatorassertions#locator-assertions-to-be-editable) | Element is editable               |
| [assertThat(locator).isEmpty()](https://playwright.dev/java/docs/api/class-locatorassertions#locator-assertions-to-be-empty) | Container is empty                |
| [assertThat(locator).isEnabled()](https://playwright.dev/java/docs/api/class-locatorassertions#locator-assertions-to-be-enabled) | Element is enabled                |
| [assertThat(locator).isFocused()](https://playwright.dev/java/docs/api/class-locatorassertions#locator-assertions-to-be-focused) | Element is focused                |
| [assertThat(locator).isHidden()](https://playwright.dev/java/docs/api/class-locatorassertions#locator-assertions-to-be-hidden) | Element is not visible            |
| [assertThat(locator).isInViewport()](https://playwright.dev/java/docs/api/class-locatorassertions#locator-assertions-to-be-in-viewport) | Element intersects viewport       |
| [assertThat(locator).isVisible()](https://playwright.dev/java/docs/api/class-locatorassertions#locator-assertions-to-be-visible) | Element is visible                |
| [assertThat(locator).containsText()](https://playwright.dev/java/docs/api/class-locatorassertions#locator-assertions-to-contain-text) | Element contains text             |
| [assertThat(locator).hasAttribute()](https://playwright.dev/java/docs/api/class-locatorassertions#locator-assertions-to-have-attribute) | Element has a DOM attribute       |
| [assertThat(locator).hasClass()](https://playwright.dev/java/docs/api/class-locatorassertions#locator-assertions-to-have-class) | Element has a class property      |
| [assertThat(locator).hasCount()](https://playwright.dev/java/docs/api/class-locatorassertions#locator-assertions-to-have-count) | List has exact number of children |
| [assertThat(locator).hasCSS()](https://playwright.dev/java/docs/api/class-locatorassertions#locator-assertions-to-have-css) | Element has CSS property          |
| [assertThat(locator).hasId()](https://playwright.dev/java/docs/api/class-locatorassertions#locator-assertions-to-have-id) | Element has an ID                 |
| [assertThat(locator).hasJSProperty()](https://playwright.dev/java/docs/api/class-locatorassertions#locator-assertions-to-have-js-property) | Element has a JavaScript property |
| [assertThat(locator).hasText()](https://playwright.dev/java/docs/api/class-locatorassertions#locator-assertions-to-have-text) | Element matches text              |
| [assertThat(locator).hasValue()](https://playwright.dev/java/docs/api/class-locatorassertions#locator-assertions-to-have-value) | Input has a value                 |
| [assertThat(locator).hasValues()](https://playwright.dev/java/docs/api/class-locatorassertions#locator-assertions-to-have-values) | Select has options selected       |
| [assertThat(page).hasTitle()](https://playwright.dev/java/docs/api/class-pageassertions#page-assertions-to-have-title) | Page has a title                  |
| [assertThat(page).hasURL()](https://playwright.dev/java/docs/api/class-pageassertions#page-assertions-to-have-url) | Page has a URL                    |
| [assertThat(response).isOK()](https://playwright.dev/java/docs/api/class-apiresponseassertions#api-response-assertions-to-be-ok) | Response has an OK status         |

Learn more in the [assertions guide](https://playwright.dev/java/docs/test-assertions).

### 安装浏览器相关问题

#### 1.安装浏览器

支持参数为：

- `install` 运行无参数的命令将安装默认浏览器
- `install webkit` 安装特定浏览器
- `install --help` 查看所有支持的浏览器

#### 2.安装系统依赖

支持参数为：

- `install-deps`  系统依赖项可以自动安装
- `install-deps chromium` 为单个浏览器安装依赖项
- `install --with-deps chromium` 将install-deps与install结合使用，以便通过一条命令安装浏览器和操作系统依赖项

#### 3.管理浏览器二进制文件

Playwright 将 Chromium、WebKit 和 Firefox 浏览器下载到操作系统特定的缓存文件夹中：

- `%USERPROFILE%\AppData\Local\ms-playwright` on Windows
- `~/Library/Caches/ms-playwright` on MacOS
- `~/.cache/ms-playwright` on Linux

这些浏览器安装后将占用几百兆的磁盘空间：

```sh
du -hs ~/Library/Caches/ms-playwright/*
281M  chromium-XXXXXX
187M  firefox-XXXX
180M  webkit-XXXX
```

您可以使用环境变量来覆盖默认行为。在安装 Playwright 时，要求它将浏览器下载到特定位置：

> PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers

### 复用登录状态
>- https://blog.csdn.net/abu935009066/article/details/136496682

1.在Record.java中录制登录操作，录制后会自动更新或生成`auth.json`文件。
> - 关闭录制器一定要在Playwright Inspector点击关闭，否则可能存储到`auth.json失败。
> - 如果录制器没有关闭，可以手动删除`auth.json`文件，然后重新录制登录操作。
> - `auth.json`文件存储在项目根目录下。
> - `auth.json`文件中存储了登录状态的cookie信息，可以用于后续的测试。
> - 确保`auth.json`仅在本地使用，因为它包含敏感信息。将其添加到`.gitignore`。

2.在application.yaml中启用 `easy.context-options.login-state: true`。

### 同时测试UI和API
参考：[CsdnApiAndPageTest.java](https://gitee.com/lakernote/easy-auto-test/blob/master/src/main/java/com/laker/autotest/testcase/CsdnApiAndPageTest.java)
> page对象有很多内置的事件监听，可以监听到几乎所有的页面事件，例如：弹窗，network请求，元素的加载完成等事件，可以在这些事件中做定制开发。
### 制作docker镜像
- https://github.com/microsoft/playwright-java/blob/main/utils/docker/README.md
- https://playwright.dev/java/docs/docker
- https://github.com/microsoft/playwright-java/blob/main/utils/docker/Dockerfile.jammy
- https://mcr.microsoft.com/en-us/product/playwright/java/about
> 此 Docker 映像包含启动浏览器所需的所有依赖项以及执行测试所需的 Java 运行时。
```dockerfile
# 基于 Playwright for Java 官方 Docker 镜像
FROM mcr.microsoft.com/playwright/java:v1.40.0-jammy

ARG DEBIAN_FRONTEND=noninteractive
ARG TZ=America/Los_Angeles

# 设置工作目录
WORKDIR /app

# 复制打包好的 JAR 文件到工作目录
COPY easy-autotest.jar /app/easy-autotest.jar

# 设置默认启动命令
CMD ["java", "-jar", "easy-autotest.jar"]

# 提供执行权限
RUN chmod +x /app/easy-autotest.jar
```

### 单独设置某次操作/等待超时时间
在 Playwright 的 Java API 中，可以通过传递一个xxxOptions(ClickOptions,WaitForSelectorOptions)对象来设置超时时间。
```java
page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Save"))
    .click(new Locator.ClickOptions().setTimeout(60000));
```
### 模拟文件上传
```java
// 等待文件选择器
FileChooser fileChooser = page.waitForFileChooser(() -> {
    // 触发文件上传
    page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Browse files")).click();
});
final Path videoPath = Paths.get("C:\\Test resource\\mp4\\file_example_MP4_1280_10MG.mp4");
// 选择文件
fileChooser.setFiles(videoPath);
// 注意这里并不会等着上传完成，所以你要找个元素等着它上传完成。
// 例如   page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Save")).click(new Locator.ClickOptions().setTimeout(60000));
```

### 模拟文件下载
```java
final Page.WaitForDownloadOptions waitForDownloadOptions = new Page.WaitForDownloadOptions();
// 设置超时时间
waitForDownloadOptions.setTimeout(60000);
// 等待下载
Download download = page.waitForDownload(waitForDownloadOptions, () -> {
    // 触发下载
    page.getByLabel("Disclaimer").getByRole(AriaRole.BUTTON, new Locator.GetByRoleOptions().setName("Accept")).click();
});
// 保存文件
download.saveAs(Paths.get("./", download.suggestedFilename()));
```
### 切换浏览器
- 用程序下载chromium,firefox,webkit浏览器，然后使用在`easy.browser`中设置浏览器类型。
- 用电脑上用户下载的chrome,egde等浏览器，然后在`easy.launch-options.channel`中设置浏览器路径。
> 注意使用chrome和egde时，一定 一定 一定要把已经打开的chrome和edge给关了，否则会报错。

王泰/EasyAutoTest

简介

发行版

贡献者

近期动态

王泰/EasyAutoTest .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

王泰/EasyAutoTest