# ZOSPy 的单元测试

[ZOSPy]使用[PyTest]进行单元测试。Hatch 用于自动测试不同的 Python 版本，并在隔离环境中运行测试。使用 hatch 运行测试还可以确保软件包能够正确安装。

## 如何运行

- 安装[hatch](https://hatch.pypa.io) ：参见[贡献指南](contributing.md#1-setting-up-a-development-environment)。
- 运行所有 Python 版本的所有测试：
    ```shell
    hatch test -a
    ```
- 或者，仅针对当前 Python 版本运行测试：
    ```shell
    hatch test
    ```
- 测试可以在扩展模式或独立模式下运行。默认情况下，测试在独立模式下运行。要在扩展模式下运行测试，请使用`--extension`命令行选项。例如：
    ```shell
    hatch test -- --extension
    ```
    为了加快测试运行速度，在扩展模式下测试时会禁用UI更新。如果需要UI更新，可以使用`--update-ui`选项启用。
- 在扩展模式下运行测试时，首先打开OpticStudio，启用交互式扩展模式，并取消选中“断开连接时自动关闭”。

## 命令行选项

- **`--extension`** ：由于 ZOS-API仅限于每个会话只有一个连接，因此无法同时在扩展模式和独立模式下测试ZOSPy。指定命令行标志`--extension`指示PyTest在扩展模式下连接到Zemax OpticStudio。确保已激活交互式扩展模式，并且未选中`Auto Close on Disconnect` 。
- **`--output-directory <OUTPUT_DIRECTORY>`** ：如果指定，所有创建的 OpticStudio 系统都将保存到此目录。
- **`--opticstudio-directory <OPTICSTUDIO_DIRECTORY>`** ：如果指定，则OpticStudio安装目录的路径将设置为此值。如果在同一系统上安装了多个OpticStudio版本，并且您想要使用特定版本，则此功能特别有用。
- **`--update-ui`** ：如果指定，则在扩展模式下测试时启用UI更新。这对于调试目的很有用。

## 生成测试参考数据

`zospy.analyses`的单元测试依赖于参考数据来检查分析结果的有效性。如果首次使用特定版本的ZOSPy运行单元测试，则这些数据尚不存在。可以通过运行来生成

```shell
hatch run generate-reference-data
```

生成的参考数据文件将被添加到`tests/data/reference` 。

参考数据文件是使用`scripts/generate_test_reference_data/tests.yaml`中的规范生成的。如果添加了新的分析测试，则需要使用针对这些测试的参考规范来扩展此文件。下面显示了记录的示例规范。

```yaml
- # OpticStudio model as defined in scripts/generate_test_reference_data/systems.py
  model: simple_system
  # ZOSPy analysis, specified as a module relative to zospy.analyses
  analysis: raysandspots.ray_fan
  # Unit test file, relative to tests/analyses
  file: test_raysandspots.py
  # Unit test for which this reference data is intended
  test: test_ray_fan_returns_correct_result
  # Parameters that are parametrized using @pytest.mark.parametrize
  parametrized: [plot_scale, number_of_rays, tangential, sagittal]
  # List with the parameter sets in parameter_name: parameter_value format
  parameters:
    - plot_scale: 0
      number_of_rays: 20
      tangential: Aberration_Y
      sagittal: Aberration_X
    - plot_scale: 1
      number_of_rays: 40
      tangential: Aberration_Y
      sagittal: Aberration_X
```


[PyTest]: https://docs.pytest.org
[ZOSPy]: https://hatch.pypa.io