# api-test-framework

**Repository Path**: taikun928/api-test-framework

## Basic Information

- **Project Name**: api-test-framework
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-07
- **Last Updated**: 2026-02-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# api-test-framework

                                                                                                                                                                                                                                    
  - api-test-framework 提供现券与期货两类自动化回归测试，核心由 src/test_framework.py（通用框架）、src/test_runner.py（现券/期货 runner）和 src/strategy_api.py（封装策略接口）构成。                                          
  - 目录：                                                                                                                                                                                                                          
      - config/：test_config.json、logging_config.json；期货订阅/验资/费用、报告及测试用例路径都在这里。                                                                                                                            
      - testcases/：CSV 用例，期货版本通常以 *_full_*.csv 命名并带 Enable 列控制是否执行；现券用 bond_testcases.csv。                                                                                                               
      - reports/、logs/：执行产物。                                                                                                                                                                                                 
      - src/：框架、runner、工具、策略 API 适配、资金/持仓校验类等 Python 代码。                                                                                                                                                    
      - 根目录下 run.sh、run_tests.py、run_rc.sh 等脚本负责启动。                                                                                                                                                                   
                                                                                                                                                                                                                                    
  运行方式                                                                                                                                                                                                                          
                                                                                                                                                                                                                                    
  1. 调整 config/test_config.json：                                                                                                                                                                                                 
      - future_config.SubList 为订阅合约；                                                                                                                                                                                          
      - IsCheckAccount 控制是否在期货用例中做资金比对；                                                                                                                                                                             
      - test_settings 中指定 bond/fut/fut_riskcontrol 的用例与报告路径。                                                                                                                                                            
  2. 准备好 testcases/*.csv，确保 Enable=1 的行数据完整。                                                                                                                                                                           
  3. Linux/CentOS 执行 chmod +x run.sh && sed -i 's/\r$//' run.sh；运行 ./run.sh（内部等价于 python3 run_tests.py --test-type fut|bond|all）。                                                                                      
  4. 结果：logs/strategy_test_*.log 记录详细过程；reports/bond_test_report.csv 或 reports/fut_test_report_<timestamp>.csv 记录每个 TestCase 的期望与实际。                                                                          
                                                                                                                                                                                                                                    
  核心逻辑                                                                                                                                                                                                                          
                                                                                                                                                                                                                                    
  - TestFramework 负责：                                                                                                                                                                                                            
      - 初始化 StrategyAPIClient（含行情订阅、查询接口）；                                                                                                                                                                          
      - 注册 TestCase 并读取结果；                                                                                                                                                                                                  
      - run_tests 会按顺序执行每个 TestCase 的 test_function，收集 RunResult/ActualResult/RunMessage/耗时等字段；                                                                                                                   
      - 通过 utils.write_report 输出 CSV。                                                                                                                                                                                          
  - BondTestRunner：                                                                                                                                                                                                                
      - _create_bond_test_function 只做“下单→可选撤单→等待 order status 匹配 expected”三步；                                                                                                                                        
      - 适合验证本币订单的状态流转。                                                                                                                                                                                                
  - FutTestRunner：                                                                                                                                                                                                                 
      - _create_fut_test_function 完整覆盖“验资→查询持仓→下单→tkernel 回报→量投回报→撤单/成交处理→资金/持仓核对”链路；                                                                                                              
      - check_future_order 校验 tkernel/量投回报字段与 ExpectErrorID；                                                                                                                                                              
      - check_future_account、check_future_position 用于验证资金及仓位变化；                                                                                                                                                        
      - 报告文件自动附带时间戳：./reports/fut_test_report_<YYYYMMDD_HHMMSS>.csv。                                                                                                                                                   
  - StrategyAPIClient：                                                                                                                                                                                                             
      - 继承 stcquant.api.strategy_mode，负责订阅、下单、撤单、查询账户/持仓/合约以及缓存回报；                                                                                                                                     
      - place_fut_order 会根据 CustomPriceType 自动从最新行情计算限价，extend 字段写入 CaseName；                                                                                                                                   
      - get_tkernel_order_response、get_order_response、get_trade_response 等供 runner 轮询。                                                                                                                                       
                                                                                                                                                                                                                                    
  现券流程概述                                                                                                                                                                                                                      
                                                                                                                                                                                                                                    
  load CSV → add TestCase → place_order → (optional cancel_order)                                                                                                                                                                   
        → wait_for_order_status → result recorded → report写入                                                                                                                                                                      
                                                                                                                                                                                                                                    
  期货流程概述                                                                                                                                                                                                                      
                                                                                                                                                                                                                                    
  load CSV → add TestCase                                                                                                                                                                                                           
   → (optional) query_fut_account (prev_account)                                                                                                                                                                                    
   → query_fut_position (prev_position)                                                                                                                                                                                             
   → place_fut_order → tkernel回报                                                                                                                                                                                                  
        ├─ status≠'a' → 校验→done                                                                                                                                                                                                   
        └─ status='a' → 等量投主推 → (optional cancel_fut_order)                                                                                                                                                                    
             → check_future_order → wait_for_order_status                                                                                                                                                                           
             → (非撤单) get_trade_response → (optional) query_fut_account(post) → check_future_account                                                                                                                              
             → query_fut_position → check_future_position                                                                                                                                                                           
   → report写入                                                                                                                                                                                                                     
                                                                                                                                                                                                                                    
  常见问题                                                                                                                                                                                                                          
                                                                                                                                                                                                                                    
  - tkernel 或量投回报中的 error_id 非 0（例如 -1316511328）会被判定为失败，即便订单最终成交；如遇此类业务错误码需在代码或配置中统一处理。                                                                                          
  - 期货用例中 Direction 只能为 0/1，OffsetFlag 只能为 0/1；否则不会查询持仓。                                                                                                                                                      
  - Enable 列缺失会导致加载器 (utils.read_testcases) 默认不过滤，全部用例都会执行。                                                                                                                                                 
  - 运行前确保 strategy_api 订阅的合约已在 SubList 中，否则会等待行情超时。                                                                                                                                                         
                                                                                                                                                                                                                                    
  维护提示                                                                                                                                                                                                                          
                                                                                                                                                                                                                                    
  - 变更 test_config.json/strategy*.ini 后应仔细校验 JSON/INI 格式；                                                                                                                                                                
  - 回放问题时优先查看 logs/strategy_test_<date>.log，内含每一步的参数、tkernel/量投回报、资金核验日志；                                                                                                                            
  - 长时间运行前可用 clean_outputs.py 清理旧 logs/、reports/（默认保留最近 5 天）。