Transformer Lab 后端测试指南数据库测试与 API 测试的配置、运行与源码解析【免费下载链接】transformerlab-appThe open source research environment for AI researchers to seamlessly train, evaluate, and scale models from local hardware to GPU clusters.项目地址: https://gitcode.com/GitHub_Trending/tr/transformerlab-app本指南面向 Transformer Lab 后端开发者系统讲解项目 API 侧 PyTest 测试体系的两大分层test/db/数据库层测试与test/api/API 层测试及其实战运行方式并结合 pytest.ini、conftest.py 与典型测试用例源码深入剖析测试环境变量、数据库后端选择SQLite/PostgreSQL、Alembic 迁移与种子数据流程、自动鉴权客户端等底层实现帮助读者掌握在该仓库中编写与执行后端测试的完整方法论。测试体系总览Transformer Lab 仓库在 api/test/ 目录下维护着一套完整、可分层执行的 PyTest 测试套件。根目录的 README.md 将现有测试明确划分为两大类test/db/*数据库层测试验证 SQLAlchemy 数据访问层、配置读写、迁移脚本等与持久化相关的逻辑执行速度快test/api/*API 层测试覆盖 FastAPI 路由、服务层与各类业务功能需要先激活 conda 环境或等价 Python 环境再运行执行速度相对较慢。这两层测试在物理目录上分属 api/test/db/ 与 api/test/api/由 pytest.ini 统一管理收集规则testpaths test指定从test目录开始递归收集norecursedirs排除了test/tmp、*/venv/*、*/site-packages/*等临时插件与虚拟环境目录避免第三方包中的测试被误收集。安装依赖与运行测试依赖安装README 给出的两条安装命令对应两个测试层级二者均基于uv pip install --system方式向当前 Python 环境注入依赖# 数据库层快速测试所需依赖 uv pip install --system pytest pytest-asyncio jsonschema shellcheck-py# API 层较慢测试所需依赖 uv pip install --system pytest pytest-asyncio jsonschema requests shellcheck-py两个命令的差异仅在于 API 层额外需要requests——它用于构造真实 HTTP 请求例如 api/test/server/conftest.py 中轮询/healthz的就绪探测。pytest-asyncio是异步测试的基础设施jsonschema用于校验接口响应结构shellcheck-py用于对 shell 脚本类内容做静态检查。从源码层面看这些测试真正依赖的运行时组件远不止于此API 层测试依赖 FastAPI 的TestClient来自fastapi.testclient基于httpx、SQLAlchemy 异步会话与 Alembic 迁移。完整依赖清单可参见 api/pyproject.toml 的[project] dependencies其中与测试直接相关的关键版本包括fastapi0.125.0、sqlalchemy[asyncio]2.0.51、aiosqlite0.20.0、asyncpg0.30.0、alembic1.18.5、pytest-asyncio所配合的pydantic2.13.4,3.0。运行命令README 明确要求从项目根目录仓库根目录执行# 数据库层快速测试 pytest test/db/ # API 层较慢测试 pytest test/api/注README 中的test/db/、test/api/对应仓库根路径下的 api/test/db/ 与 api/test/api/运行前需先将工作目录切换到api/目录下README 所称的 root of the project 即 API 项目根。由于 pytest.ini 设置了asyncio_mode auto所有async def测试函数会被自动识别为异步用例而无需手动添加pytest.mark.asyncioasyncio_default_fixture_loop_scope module则让异步 fixture 默认复用模块级事件循环保证asyncpg连接池等资源在模块内稳定复用。默认排除 live_server 测试pytest.ini 中有一项关键配置markers live_server: mark test as requiring a live server addopts -m not live_server即默认运行会排除所有标记为live_server的用例这类用例需要一个已在外部启动的真实服务进程通常由 CI/CD 流程拉起。如需显式运行它们使用pytest -m live_server该标记对应的live_serverfixture 定义在 api/test/server/conftest.py它固定探测http://127.0.0.1:8338/healthz以 2 秒间隔轮询、最长等待 120 秒直至返回{message: OK}才向测试注入 base URL服务器由外部启动fixture 不做清理。数据库层测试test/db/深度解析测试入口与运行环境api/test/db/test_db.py 是数据库层的核心用例文件其开头部分的初始化逻辑揭示了数据库层测试的运行约定import os # Create test directories before setting environment variables os.makedirs(./test/tmp/, exist_okTrue) os.environ[TFL_HOME_DIR] ./test/tmp/ # Note: TFL_WORKSPACE_DIR is not set so that get_workspace_dir() will use the org-based # workspace directory (./test/tmp/orgs/team-id/workspace) after migrationTFL_HOME_DIR被重定向到./test/tmp/使所有本地文件、SQLite 数据库文件llmlab.sqlite3与工作区文件都落在测试临时目录内不影响真实用户数据刻意不设置TFL_WORKSPACE_DIR从而走组织化org-based工作区目录逻辑覆盖迁移后的路径解析行为。测试通过pytestmark pytest.mark.asyncio(loop_scopemodule)为整个模块固定模块级事件循环与 pytest.ini 的默认值呼应并声明pytest_plugins (pytest_asyncio,)。关键 Fixture 与生命周期pytest.fixture(scopesession, autouseTrue) def manage_test_tmp_dir(): yield # delete the database: db_path os.path.join(./test/tmp, llmlab.sqlite3) if os.path.exists(db_path): os.remove(db_path)manage_test_tmp_dir是 session 级自动 fixture在整个测试会话结束后清理test/tmp/llmlab.sqlite3保证测试产物不残留。pytest.fixture(scopemodule, autouseTrue) async def setup_db(): await db.init() yield await db.close()setup_db是模块级自动 fixture负责在模块开始时初始化数据库会话transformerlab.db.session的init()并在结束时关闭。单次初始化、整模块复用一个会话避免了多次连接导致的异步连接池失效问题。此外还提供了一个业务级 fixturetest_experiment若已存在同名实验则先删除通过experiment_service.experiment_create(test_experiment, {})创建新实验测试结束后再删除确保每个用例拿到干净的实验上下文。核心用例Config 读写与唯一约束TestConfig类下的三个用例覆盖了配置系统的核心行为test_config_set_and_get验证config_set/config_get的基础读写——普通字符串值可写可读、覆盖写生效、不存在的 key 返回None、值为None时读回None、空字符串读回test_team_wide_config_does_not_create_duplicates验证团队级配置的唯一性。对同一(team_id, key)连续两次config_set第二次必须原地更新而非插入新行——测试通过 SQLAlchemyselect(Config).where(...)断言该key只存在一行且值为最新值。这与迁移脚本 1f7cb465d15a_add_unique_constraint_job_id_quota_usage.py、84accba9dc2c_config_unique_constraint.py 所建立的唯一约束直接对应test_user_specific_config_does_not_create_duplicates同样的唯一性验证下沉到用户级配置(user_id, team_id, key)维度。迁移环境回归测试api/test/db/test_alembic_env.py 是数据库层中极具工程价值的回归测试它守护的是Alembicenv.py的 configparser 插值缺陷当 PostgreSQL 密码包含}、?、!、{等字符时urllib.parse.quote_plus会将其转义为%7D、%3F、%21、%7B若env.py再把含%的 DSN 通过config.set_main_option(sqlalchemy.url, ...)喂给 Alembic 的 Config底层是configparser就会抛出ValueError: invalid interpolation syntax。该文件通过两条用例锁定修复test_env_handles_percent_encoded_password_in_database_url在子进程中以离线模式alembic upgrade head --sql执行迁移使用包含}?!{的合成密码 DSN断言 stderr 中不出现invalid interpolation syntax同时断言出现了Context impl说明 env.py 至少已正常加载test_database_url_is_percent_encoded_for_special_passwords通过monkeypatch设置带特殊字符的密码并重载 api/transformerlab/db/constants.py断言DATABASE_URL中的密码段已被百分号编码为a%7Db%3Fc%21d%7Be并在注释中记录了 configparser 仍会拒绝该 URL 的失败模式为未来的 env.py 工作留档。API 层测试test/api/深度解析会话级测试环境搭建conftest.pyapi/test/api/conftest.py 是整个 API 测试套件的基石它在导入测试用例之前完成环境准备os.makedirs(test/tmp/, exist_okTrue) os.makedirs(test/tmp/webapp, exist_okTrue) # Create webapp directory for static files os.environ[TFL_HOME_DIR] test/tmp/ os.environ[TRANSFORMERLAB_JWT_SECRET] test-jwt-secret-for-testing-only os.environ[TRANSFORMERLAB_REFRESH_SECRET] test-refresh-secret-for-testing-only os.environ[EMAIL_METHOD] dev # Use dev mode for tests (no actual email sending)四个环境变量的作用分别是将本地文件与工作区重定向到测试临时目录为 JWT 与刷新令牌提供仅测试用的固定密钥将邮件发送方式固定为dev模式避免测试触发真实邮件外发。数据库后端自动选择SQLite 或 PostgreSQLconftest 最值得关注的设计是根据环境变量自动选择数据库后端_use_postgres all(os.environ.get(k) for k in (DATABASE_HOST, DATABASE_NAME, DATABASE_USER, DATABASE_PASSWORD)) if _use_postgres: # Let constants.py build the PostgreSQL URL from DATABASE_HOST/NAME/USER/PASSWORD test_db_path None else: # Use temporary file-based SQLite database for tests (easier to debug than in-memory) test_db_dir os.path.join(test, tmp, db) os.makedirs(test_db_dir, exist_okTrue) test_db_path os.path.join(test_db_dir, test_llmlab.sqlite3) os.environ[DATABASE_URL] fsqliteaiosqlite:///{test_db_path}若同时设置了DATABASE_HOST/NAME/USER/PASSWORD四个变量则走 PostgreSQL由 api/transformerlab/db/constants.py 拼装连接串CI 的 Postgres 工作流即采用此路径否则回退到文件型 SQLitesqliteaiosqlite:///test/tmp/db/test_llmlab.sqlite3README 中文件型比内存型更易调试的设计意图在此落地。配套的cleanup_test_dbsession 级自动 fixture在测试结束后清理 SQLite 数据库及其-wal、-shm伴生文件若使用 PostgreSQL 则无需磁盘清理直接跳过。初始化流程Alembic 迁移 默认管理员种子clientfixturesession 级在应用启动前完成两步关键初始化asyncio.run(run_alembic_migrations()) asyncio.run(seed_default_admin_user())run_alembic_migrations()来自 api/transformerlab/db/session.py与生产环境走同一套 Alembic 迁移api/alembic/保证测试 schema 与生产一致seed_default_admin_user()来自 api/transformerlab/services/experiment_init.py负责植入默认管理员账号adminexample.com / admin123——这正是后续鉴权客户端登录所依赖的账号。注释还说明了一个重要的连接策略session.py会自动检测 pytest 环境并改用NullPool每次 checkout 都新建连接避免事件循环切换导致的连接池失效问题。自动鉴权客户端AuthenticatedTestClient为了让测试代码保持简洁conftest 封装了AuthenticatedTestClient(TestClient)自动为所有请求注入管理员身份构造时通过POST /auth/jwt/loginadminexample.com/admin123获取access_token并调用/users/me/teams取第一个团队作为X-Team-Id重写request()对所有非/auth/路径自动附加Authorization: Bearer token与X-Team-Id头若调用方未显式指定使多用户/多团队上下文下的鉴权测试开箱即用。基于这一封装测试用例可以像 api/test/api/test_api.py 那样写出行级断言def test_root(client): response client.get(/) assert response.status_code 200典型用例模式配置接口api/test/api/test_config.py通过/config/set?k...v...与/config/get/{key}验证配置读写断言响应结构{key, value, team_wide}健康检查api/test/api/test_server_info.py覆盖/healthz在multiuser、local模式下的响应并断言未认证端点绝不泄露存储 URIuri not in data[storage]同时用pytest.mark.parametrize验证 AWS/GCP/Azure 远程存储开关对 provider 上报的影响分块上传流水线api/test/api/test_model_download.py_seed_model帮助函数完整走一遍/upload/init→/upload/{id}/chunk→/upload/{id}/complete→/model/fileupload的分块上传链路再对/model/files的文件清单与/model/file的 Range 响应头accept-ranges: bytes做断言是服务层与路由层联动测试的典型范例。编写新测试的实践建议结合上述源码模式在 api/test/ 中新增测试时可遵循以下约定放置位置纯数据访问与迁移逻辑放入 api/test/db/快、不依赖网络与 conda 环境之外的服务路由、服务层与多租户业务逻辑放入 api/test/api/复用clientfixtureAPI 测试直接声明client参数即可获得已迁移、已种子的数据库与自动鉴权上下文不要自行创建 TestClient异步用例无需装饰器asyncio_mode auto下直接写async def test_*环境隔离所有测试必须依赖TFL_HOME_DIRtest/tmp/的沙箱目录绝不读写真实用户目录需要真实服务进程的用例打上pytest.mark.live_server标记默认pytest会自动跳过仅在 CI 或显式pytest -m live_server时执行数据库后端无关性新用例应同时在 SQLite 与 PostgreSQL 两种后端下通过CI 会对两者分别跑避免写出依赖具体方言的 SQL。小结Transformer Lab 的测试体系以 api/test/README.md 为入口形成了数据库层快测 API 层全量测的分层格局数据库层依赖pytest-asyncio与模块级事件循环通过 session 级清理与唯一约束断言守护数据层正确性API 层则通过 conftest.py 的环境变量沙箱、SQLite/PostgreSQL 自动切换、Alembic 迁移 管理员种子以及自动鉴权客户端构建出贴近生产且可独立运行的测试环境。理解这一体系是向 Transformer Lab 贡献后端代码、保障功能回归的前提。【免费下载链接】transformerlab-appThe open source research environment for AI researchers to seamlessly train, evaluate, and scale models from local hardware to GPU clusters.项目地址: https://gitcode.com/GitHub_Trending/tr/transformerlab-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考