在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

sickcodes/Docker-OSX

菜单

开发与测试

相关源文件

本页面介绍了 Docker-OSX 的开发工作流程和测试流程。内容涵盖如何设置开发环境、构建和测试不同的镜像变体，以及如何为项目做出贡献。有关作为最终用户使用 Docker-OSX 的信息，请参阅 安装与基本用法，有关解决常见问题的指导，请参阅 故障排除。

开发环境设置

为 Docker-OSX 设置开发环境需要特定的依赖项来支持虚拟化和测试。

先决条件

  • 支持 KVM 的 Linux 主机
  • 启用实验性功能的 Docker
  • Git
  • 对 QEMU/KVM 和容器化的基本理解
  • 用于 GUI 测试的 X11 服务器

基本设置步骤

  1. Fork 并克隆 Docker-OSX 仓库
  2. 配置 Docker 的实验性功能以支持 squash
  3. 设置 X11 显示以测试 GUI 元素
  4. 安装 KVM 并确保其配置正确

来源： tests/test.sh157-169 tests/test.sh196-225

开发工作流

Docker-OSX 的开发工作流程遵循以下通用步骤

  1. 分支创建：从 master 分支创建功能分支或 bug 修复分支
  2. 开发：对 Dockerfile 或脚本进行代码更改
  3. 本地测试：使用测试框架测试更改
  4. 文档：更新文档以反映更改
  5. Pull Request：提交更改以供审查

分支策略

  • master：主稳定分支
  • 功能分支：用于新功能（feature/name）
  • Bug 修复分支：用于 bug 修复（bugfix/issue-number）
  • 版本分支：用于特定的 macOS 版本支持

测试基础设施

Docker-OSX 采用全面的测试基础设施来确保镜像的质量和功能。

测试组件

测试系统包括

  1. 镜像构建测试：验证所有镜像变体是否都能成功构建
  2. 启动测试：确认镜像是否启动到预期状态
  3. 功能测试：验证特定功能，如 VNC、自动登录或 USB 直通
  4. 视觉验证：截图对比以验证预期的视觉状态

来源： tests/test.sh122-142 tests/boot-images.sh27-39

自动化测试流程

自动化测试流程如下

  1. 环境设置：使用必需的依赖项设置测试环境
  2. 镜像构建：构建每个镜像变体（naked、auto 等）和版本（Catalina、Big Sur 等）
  3. 启动测试：启动每个镜像并捕获截图
  4. 视觉验证：将截图与参考镜像进行比较
  5. 结果收集：报告成功或失败

来源： tests/boot-images.sh39-69

测试脚本结构

主要的 test.sh 脚本协调整个测试过程

  1. 它提供了安装依赖项（Docker、VNC、QEMU）的函数
  2. 包含不同镜像变体的构建函数
  3. 处理镜像标记和推送到 Docker Hub
  4. 调用 boot-images.sh 来验证成功启动

boot-images.sh 脚本专注于启动验证

  1. 在容器中运行每个镜像变体
  2. 捕获启动过程的截图
  3. 与参考截图进行比较以进行验证
  4. 测试后终止容器

测试不同的 macOS 版本

Docker-OSX 支持多个 macOS 版本，每个版本都需要特定的测试

版本标签测试参考镜像
High Sierrahigh-sierrahigh-sierra_master.png
Mojavemojavemojave_master.png
Catalinacatalinacatalina_master.png
Big Surbig-surbig-sur_master.png
Montereymontereymonterey_master.png
Venturaventuraventura_master.png
Sonomasonomasonoma_master.png

来源： tests/test.sh134-142 tests/boot-images.sh27-35

持续集成

Docker-OSX 项目使用持续集成 (CI) 来自动测试更改和构建镜像。

CI 工作流

来源： tests/test.sh334-345

CI 环境变量

测试脚本支持各种环境变量来配置 CI 流程

可变目的示例
BRANCH要测试的 Git 分支master
REPO存储库 URLhttps://github.com/sickcodes/Docker-OSX.git
MIRROR_COUNTRY用于包下载的镜像国家代码US
VNC_PASSWORDVNC 测试密码testing
DOCKER_USERNAME用于推送镜像的 Docker Hub 用户名username
DOCKER_PASSWORD用于推送镜像的 Docker Hub 密码password
NO_CACHE构建时是否使用缓存--no-cache

来源： tests/test.sh34-113 tests/test.sh115-119

开发最佳实践

开发 Docker-OSX 时，请遵循以下最佳实践

  1. 测试所有变体：更改应针对所有镜像变体进行测试
  2. 版本兼容性：确保与所有支持的 macOS 版本兼容
  3. 记录更改：更新文档和 CHANGELOG 以记录所有重大更改
  4. 最小化镜像大小：优化 Dockerfile 命令以减小镜像大小
  5. 错误处理：在脚本中添加适当的错误处理和日志记录
  6. 保持向后兼容性：尽可能避免破坏性更改

常见开发任务

添加对新 macOS 版本的支持

  1. 创建新的 Dockerfile 或修改现有的 Dockerfile，添加特定于版本的配置
  2. 在 test.sh 中将新版本添加到 VERSION_BUILDS 数组
  3. 创建用于启动测试的参考截图
  4. 测试新版本的构建和启动
  5. 更新文档以包含新版本

修改构建脚本

  1. 修改构建脚本或 Dockerfile
  2. 测试受影响的镜像变体的构建
  3. 验证所有镜像是否仍能正确启动
  4. 检查是否存在性能回归
  5. 更新 CHANGELOG 以包含更改的详细信息

来源： CHANGELOG.md3-20 tests/test.sh269-279

排除开发问题

开发中常见问题及解决方案

问题解决方案
Docker 构建失败检查 Docker 日志，确保启用了实验性功能
KVM 不可用验证 KVM 模块是否已加载，检查权限
X11 显示问题确保 X11 套接字可用且权限正确
启动测试失败手动比较截图，检查 macOS 中的 UI 更改
CI 构建超时优化构建步骤，考虑拆分成多个作业
推送到 Docker Hub 失败验证凭据和权限

来源： tests/test.sh281-294

未来发展

Docker-OSX 的当前开发目标包括

  1. 通过优化的 KVM 配置提高性能
  2. 在新 macOS 版本发布时添加对新版本支持
  3. 增强 USB 设备直通功能
  4. 提高网络性能
  5. 减小镜像大小和构建时间
  6. 为特定功能添加更多自动化测试

为 Docker-OSX 做贡献

要为 Docker-OSX 做贡献

  1. Fork 存储库
  2. 创建功能分支
  3. 进行您的更改
  4. 遵循本文档中的程序测试你的更改
  5. 提交一个带有清晰更改描述的 pull request
  6. 更新 CHANGELOG 以包含你的更改
  7. 回应审查意见

有关使用 Docker-OSX 的更全面指南，请参阅 安装与基本用法 以及此 wiki 中的其他页面。

来源： CHANGELOG.md tests/test.sh tests/boot-images.sh