diff --git a/docs/usage/fastdeploy_unit_test_guide.md b/docs/usage/fastdeploy_unit_test_guide.md new file mode 100644 index 000000000..98184724b --- /dev/null +++ b/docs/usage/fastdeploy_unit_test_guide.md @@ -0,0 +1,31 @@ +# FastDeploy Unit Test Specification +1. Test Naming Conventions + - Test files must start with test_. + - Test methods are recommended to follow the format test_func_behavior or test_func for clarity and readability. + +2. Directory Structure + - All unit tests should be placed under the test/ directory and organized into subdirectories following the FastDeploy module structure for easier maintenance and navigation.Reference: [vllm](https://github.com/vllm-project/vllm/tree/main/tests) + +3. Coverage Scope,Each key module/class/function must be covered, including: + + - Normal Path: Standard input and main workflow. + - Boundary Input: Empty values, extremely large/small values, and boundary conditions. + - Abnormal Input: Invalid parameters, incorrect formats, etc. Ensure that exception handling matches expectations (e.g., check exception content). + +4. Case Writing & Execution + + - Test cases should support one-click execution in both CI and local environments via pytest or unittest. + - Use explicit assert statements to validate module behavior or return values; avoid relying solely on printed outputs. + - Each test case should maintain strong atomicity, focusing on a single behavior and avoiding mixing multiple functions in one test. + - Tests must be independent of execution order and global state, ensuring complete decoupling between cases. + - Custom operators must have C++-level unit tests, or forward/backward tests based on Paddle single-layer networks. Refer to Xiaoguang’s documentation on custom operator development toolkit and non-official operator development specification (trial). + +5. WebServer-related Tests + + - Avoid starting a WebServer directly in unit tests unless absolutely necessary for end-to-end validation. + - Prefer using mock for network requests and module interactions to achieve more stable and controllable atomic-level testing. + - If HTTP requests must be tested: + - QA will provide a port injection specification (ports are written into environment variables, which test cases can directly load). This spec and scripts are expected to be ready by next Wednesday. + - Test cases should read ports from environment variables instead of hardcoding them, ensuring reusability in CI multi-instance concurrency and easier local debugging. + +Image diff --git a/docs/zh/usage/fastdeploy_unit_test_guide.md b/docs/zh/usage/fastdeploy_unit_test_guide.md new file mode 100644 index 000000000..cfa499104 --- /dev/null +++ b/docs/zh/usage/fastdeploy_unit_test_guide.md @@ -0,0 +1,32 @@ +# Fastdeploy 单测规范 +1. 测试命名规范 + - 测试文件以 test_ 开头； + - 测试方法命名建议采用 test_func_behavior 格式，或 test_func，保持语义清晰。 + +2. 目录结构 + + - 所有单测应统一放在 test/ 目录，并根据 FastDeploy 模块结构划分子目录，便于维护和定位。可参考[vllm](https://github.com/vllm-project/vllm/tree/main/tests) + +3. 覆盖范围，每个关键模块/类/函数需覆盖 + + - 正常路径 （标准输入，主流程） + - 边界输入 （空值、极大/极小值、边界条件） + - 异常输入 （非法参数、错误格式等，需校验异常行为是否符合预期，例如exception的内容） + +4. Case编写与执行 + + - 测试用例应支持在 CI 、本地环境中通过 pytest 或 unittest 一键运行 + - 使用明确的 assert 判断模块行为或返回值，避免仅打印输出 + - 每个测试用例应具备良好的原子性，每个用例聚焦一个行为，避免多个功能混测 + - 测试之间保持独立，不依赖运行顺序、不共享全局状态，即用例之间必须是解耦的 + - 自定义算子需要有C++级别的单测或者是基于Paddle单层组网的前反向测试 ，参考晓光的文档 开发套件自定义算子和框架非正式算子开发规范(试运行) + +5. WebServer 相关测试 + + - 除非必要，请避免在单测中直接起 WebServer 进行端到端测试 + - 推荐使用 mock 替代网络请求、模块上下游调用等，以实现更稳定、可控的模块级原子性测试 + - 如果确需通过 HTTP 发起请求 + - QA 会提供一套端口注入规范（将端口写入环境变量，Case可直接加载变量内容）（预计下周三完成规范和脚本编写）类似下图 + - 测试用例中读取环境变量，避免硬编码端口，保障 CI 多实例并发下可复用，且便于本地调试 + +Image diff --git a/mkdocs.yml b/mkdocs.yml index 297e8ec97..5f4a354a1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -138,3 +138,4 @@ nav: - 'Log Description': usage/log.md - 'Code Overview': usage/code_overview.md - 'Environment Variables': usage/environment_variables.md + - 'FastDeploy Unit Test Guide': usage/fastdeploy_unit_test_guide.md