测试框架

HUTB 的测试框架目前只支持 Ubuntu 平台，执行命令make smoke_tests进行测试。

测试命令：

CarlaUE4.exe --carla-rpc-port=3654 --carla-streaming-port=0 -nosound
# -m (module)：以模块运行
# -v (verbose)：打印详细信息
python -m nose2 -v smoke.test_spawnpoints.TestSpawnpoints

测试内容

冒烟测试

同步模式 smoke.test_sync

测试在同步模式下各种功能能否正常工作

验证世界重载功能 (test_reloading_map)
- 测试在同步模式下连续重载世界地图 4 次
- 确保每次重载后都能正确应用同步模式设置（固定时间步长 0.05 秒）
- 包含内存清理等待时间，避免 UE4 资源冲突
验证相机同步 (_test_camera_on_synchronous_mode) 测试 RGB 相机在同步模式下的数据一致性

验证内容：
- 每一帧的帧号是否正确递增（+1）
- 相机图像的帧号是否与世界快照的帧号一致
- 相机所获取图像的时间戳image.timestamp是否与模拟时间world.get_snapshot().timestamp.elapsed_seconds匹配
验证多传感器变换同步 (test_sensor_transform_on_synchronous_mode)
- 测试多种传感器（LIDAR、GNSS、雷达、IMU）在车辆移动时的数据同步
- 验证要点：
- 所有传感器在同一帧内都能收到数据
- 传感器数据中的变换矩阵与实际传感器变换一致
- 队列中没有数据积压或丢失
- 传感器数据帧号与世界快照帧号匹配
验证批量命令同步 (test_apply_batch_sync)

测试 apply_batch_sync API 在不同时序下的行为

三种测试场景：
- 立即执行：在同一帧内生成车辆（帧号不变）
- 下一帧执行：在下一帧生成车辆（帧号 +1）
- 手动触发：批量命令后手动 tick（帧号 +1）

传感器 smoke.test_sensor_determinism

测试传感器数据确定性的验证工具，确保在相同输入条件下，传感器产生的数据是完全可重复的。

测试每个搭载碰撞传感器的车辆与墙碰撞后能够收集到碰撞事件。

碰撞

smoke.test_collision_determinism

道具加载

smoke.test_props_loading

传感器节拍时间

smoke.test_sensor_tick_time

地图

smoke.test_map

快照

smoke.test_snapshot

雷达

smoke.test_lidar

流

smoke.test_streamming

生成点

smoke.test_spawnpoints

蓝图

smoke.test_blueprint

碰撞传感器

smoke.test_collision_sensor

世界

smoke.test_world

几何变换

smoke.test_geoconversion

Windows 平台

脚本src\test>check.bat用于启动windows平台下的测试，运行的第一个测试用例为：

python -m nose2 -v smoke.test_sync smoke.test_sensor_determinism smoke.test_collision_determinism smoke.test_props_loading smoke.test_sensor_tick_time smoke.test_map smoke.test_snapshot smoke.test_lidar smoke.test_streamming smoke.test_spawnpoints smoke.test_blueprint smoke.test_collision_sensor smoke.test_world smoke.test_geoconversion

整个脚本会依次运行 smoke_test_list.txt 文件中的所有测试用例。

问题解决

Town03 测试时发现先显示第一视角的VR模式，然后再切换到 Air 模式

测试失败：

conda activate hutb
cd PythonAPI/test
python -m nose2 -v smoke.test_spawnpoints.TestSpawnpoints
python -m nose2 -v smoke.test_collision_sensor.TestCollisionSensor

smoke.test_sync.TestSynchronousMode

报错信息（Town03 中因为，无效的参与者描述符导致测试碰撞失败；smoke.test_spawnpoints.TestSpawnpoints 在生成位置的生成碰撞导致生成失败）：

调试：虚幻编辑器中启动带参数的场景。

Spawn failed because of invalid actor description

报错信息：

2026-05-27T00:11:26.3312324Z ERROR: test_single_car (smoke.test_collision_sensor.TestCollisionSensor)
2026-05-27T00:11:26.3313865Z ----------------------------------------------------------------------
2026-05-27T00:11:26.3314303Z Traceback (most recent call last):
2026-05-27T00:11:26.3315000Z   File "C:\actions-runner\_work\hutb\hutb\PythonAPI\test\smoke\test_collision_sensor.py", line 47, in test_single_car
2026-05-27T00:11:26.3315776Z     event_list = self.run_collision_single_car_against_wall(bp_veh)
2026-05-27T00:11:26.3316678Z   File "C:\actions-runner\_work\hutb\hutb\PythonAPI\test\smoke\test_collision_sensor.py", line 21, in run_collision_single_car_against_wall
2026-05-27T00:11:26.3317486Z     vehicle = self.world.spawn_actor(bp_vehicle, veh_transf)
2026-05-27T00:11:26.3318012Z RuntimeError: Spawn failed because of invalid actor description

原因：mini-2 （没有）等车生成不了。原来有41种车型，扩展到54种。

python ..\examples\manual_control.py -p 3654 --filter vehicle.mini-2.mini-2

解决：删除车辆工厂中没有资产的车辆。

The collision sensor have failed for the cars

报错信息：

FAIL: test_single_car (smoke.test_collision_sensor.TestCollisionSensor)
----------------------------------------------------------------------
Traceback (most recent call last):
File "D:\hutb\PythonAPI\test\smoke\test_collision_sensor.py", line 56, in test_single_car
    self.fail("The collision sensor have failed for the cars: %s" % cars_failing)
AssertionError: The collision sensor have failed for the cars:  vehicle.byd-v2.byd-v2 vehicle.hq.hq

原因：未产生碰撞事件。

解决：参考碰撞检测器的必要配置

Spawn failed because of collision at spawn position

报错信息：

2026-05-27T00:11:26.3319177Z FAIL: test_spawn_points (smoke.test_spawnpoints.TestSpawnpoints)
...
"C:\actions-runner\_work\hutb\hutb\PythonAPI\test\smoke\test_spawnpoints.py", line 74, in test_spawn_points
2026-05-27T00:11:26.3321283Z     if spawn_errors else "Spawn errors detected (no details)"
2026-05-27T00:11:26.3321745Z AssertionError: True is not false : Spawn errors detected:
2026-05-27T00:11:26.3322565Z   - idx=13, bp=vehicle.bus-2.bus-2, actor_id=0, loc=(191.080,55.840,0.300), rot=(0.00,180.00,0.00), error=Spawn failed because of collision at spawn position

原因：

vehicle.bus-2.bus-2、vehicle.bus-1.bus-1 车太大了，在生成点产生冲突。

解决：在车辆工厂中暂时移除。

内存泄漏

vehicle.wuling-2.wuling-2（不确定）会导致内存急剧（消耗了28G）上升直到场景出现 Out of video memory trying to allocate a rendering resource，注释了也没用。

vehicle.bydsong-1、 vehicle.volkswagen.t2_2021、vehicle.wj.wj、vehicle.hongqi-2.hongqi-2、vehicle.byd_bus.byd_bus、vehicle.mini-4.mini-4、hongqi-1、vehicle.bus-2.bus-2、

使用LOD技术：Level of Detail (LOD) 技术可以根据距离摄像机的远近来加载不同精细程度的模型和纹理，从而降低GPU和内存的负担。

解决：打包后不会出现内存爆炸的问题。
Python 3.9 报错：TypeError: dataclass() got an unexpected keyword argument 'slots'

复现：pip install --force-reinstall hutb/hutb/Build/UE4Carla/ce082bb54/WindowsNoEditor/PythonAPI/carla/dist/hutb-2.9.16-cp39-cp39-win_amd64.whl
```
# 安装的是 pip-26.1.1-pyhc872135_0，最新的为：26.5.0
conda create -n hutb_3.9 python=3.9 --yes
conda deactivate && conda remove -n hutb_3.9 --all --yes
```
报错信息：
```
(hutb_3.9) D:\hutb\PythonAPI\examples\air>pip --version
...
    from pip._internal.models.scheme import SCHEME_KEYS, Scheme
File "D:\hutb\Build\dependencies\prerequisites\miniconda3\envs\hutb_3.9\lib\site-packages\pip\_internal\models\scheme.py", line 13, in <module>
    @dataclass(frozen=True, slots=True)
TypeError: dataclass() got an unexpected keyword argument 'slots'
```
原因：类的装饰器中移除slots=True参数，因为 slots参数是在 Python 3.10 中引入的。

解决：
```
python -m pip install --upgrade pip
```
D:\hutb\Build\dependencies\prerequisites\miniconda3\envs\hutb_3.9\lib\site-packages\pip_internal\models\scheme.py D:\hutb\Build\dependencies\prerequisites\miniconda3\envs\hutb_3.9\lib\site-packages\pip_internal\models\release_control.py D:\hutb\Build\dependencies\prerequisites\miniconda3\envs\hutb_3.9\lib\site-packages\pip_internal\models\selection_prefs.py

CI/CD

参考链接进行软件的安装。