IDEA多模块工程：Java与Python自动化测试框架统一管理实战

讲个真实场景。我接手某个自动化测试框架改造的时候，团队同时维护着两套代码：Java 这边用 TestNG 写接口用例已经跑了两三年，Python 那边用 pytest 处理数据校验和运维脚本也形成了规模。每次发布前，负责 Java 的同学跑完要导一份报告，负责 Python 的同学再另起环境跑一遍，最后手工把结果拼在一起给负责人看。时间全浪费在没有技术含量的合并上。

后来我下决心把两套东西收进同一个 IDEA 工程里统一管理。这篇保姆级教程，就是记录我当时从环境准备、模块搭建、相互协作到最终统一报告的完整过程，里面的每一步都是我实际跑通过的。如果你也需要在 IDEA 里同时维护 Python 和 Java 自动化框架，这篇应该能帮你少走很多弯路。

我不是想跟你说"两种语言二选一"，而是想说：只要选对一个工程结构，两种语言完全可以和平共处，并且共用一份配置文件、共用一套测试报告、共用同一个运行入口。下面进入正题。

1. 为什么把Python和Java自动化框架放在同一个IDEA工程里？先把动机说透

1.1 自动化测试的两类典型需求，对应两种语言生态

先说结论：语言选型的背后，通常不是你个人的偏好，而是被测系统和团队技术栈决定的。

我做过的这类项目里，最常见的组合是：被测系统一部分接口由 Java 服务提供，另一部分是 Python 写的算法模块或数据处理服务。于是测试这边也自然裂成两派：Java 派喜欢 TestNG、JUnit、RestAssured，追求企业级体系的稳定和 CI 集成的平滑；Python 派喜欢 pytest、requests、Allure，看重脚本编写的速度和 json 数据处理的灵活度。

举个具体例子，我们当时的自动化框架需要覆盖两类场景：

• 接口自动化：对订单服务发起 POST 请求、校验响应码和返回字段，这部分用 Java 写，因为被测服务本身是 Java，团队里最熟的就是那套技术栈。
• 数据造数/校验脚本：测试前需要往库里插入一批模拟交易记录，测试后要统计结果数据，这部分用 Python 写，因为脚本短、改起来快。

这两种场景如果分开维护，环境独立、报告独立，沟通成本会成倍增加。把它们放进同一个工程，不是要消灭某一门语言，而是让它们各司其职，同时降低维护成本。

1.2 IDEA 对多语言工程的支持，是"最不折腾"的方案

有朋友会问：Java 代码用 IDEA，Python 代码用另一套 IDE，不是更省事吗？我的体会恰恰相反。两套 IDE 意味着两套快捷键、两套环境变量、两套运行配置，你每天要在这两个工具之间来回切换，时间一长非常割裂。

IDEA 有一个很核心的能力：一个 Project 下可以创建多个 Module，并且每个 Module 可以绑定不同的 SDK。Java 模块绑定 JDK，Python 模块绑定 Python 解释器，互不干扰。再加上 IDEA 的运行面板里可以为不同 Module 创建不同类型的运行配置，所以我可以在同一个窗口里先跑 Java 用例，再切到 Python 配置跑 pytest，全程不用换软件。

关于版本选择，我自己的建议是：优先用旗舰版（Ultimate），因为它内置了 Python 支持，开箱即用。社区版（Community）虽然可以通过插件市场装第三方插件获得基础 Python 能力，但功能和稳定性都会受限。如果你所在团队没有旗舰版的授权，社区版也勉强能跑，只是别对补全和调试抱太高期待。

还有一个容易被忽略的点：一个工程统一管理之后，Git 提交、代码 Review、CI 触发都方便了。以前两份代码放两个仓库，现在可以在根目录下一次 commit 把 Java 和 Python 的改动都带上。下面这张表是我当时对比多方案时记的结论：

所以，综合下来，在 IDEA 里建多模块工程是最适合"跨语言团队"的方案。

2. 动手前必须准备的环境：JDK版本、Python插件与SDK关联，一个都不能少

2.1 JDK 与 IDEA 版本匹配，别贪新

这一节全是前期准备，做不好后面全是坑。别小看环境问题，我见过太多项目一开始跑不起来，最后发现是 JDK 版本太新导致插件不兼容。

我建议安装JDK 11 或 JDK 17 这种 LTS 版本。为什么？因为自动化框架里用到的第三方库很多，它们未必及时适配最新版本 JDK。TestNG、RestAssured 这类库对 LTS 版本支持最好。安装完成后，在 IDEA 的设置里找到 Java SDK 的设置，把已经安装的 JDK 加进去。如果你不想手动配置全局环境变量，直接让 IDEA 自己管理 JDK 路径也行，但团队统一的话，最好在根目录的.sdkmanrc或说明文档里写清楚版本号。

还有个小提醒：IDEA 和 JDK 之间也有版本兼容关系。如果你用的是较老的 IDEA 版本，却强行绑定 JDK 21，偶尔会出现"编译器后端崩溃"之类的诡异错误。同样是 LTS，11 和 17 二选一基本不会踩雷。

2.2 安装 Python 插件并绑定解释器

如果你用的是旗舰版，内置的 Python 插件默认是启用的。如果你用的是社区版，去插件市场搜索 Python 插件，找到第三方社区维护的那个装好。

装完插件还不算完，关键一步是把 Python SDK 和工程关联起来。操作路径是：打开项目结构设置（Windows 下快捷键是 Ctrl+Alt+Shift+S），在平台设置里找到 SDKs，点加号，选择 Python SDK。这时你会看到两个选择：

• 选择系统解释器：直接用你本机安装的 Python，简单，但容易污染全局环境。
• 新建虚拟环境（Virtualenv）：在项目目录下建独立环境，依赖隔离，强烈推荐。

我当时的做法是：在 Python 模块目录下手动创建一个 venv，然后绑定这个虚拟环境里的解释器。这样 requirements 随便装，坏了就删掉重建，不影响系统其他项目。如果是 Windows 系统，解释器路径一般指向venv\Scripts\python.exe；Linux 和 macOS 下是venv/bin/python。

2.3 推荐的多 Module 工程布局

先把目录结构定了，后面写代码才不乱。我最终用的布局是这样：

auto-framework/ # 工程根目录 ├── config/ # 共享配置目录 │ ├── config.json # 环境地址、超时、账号等 │ └── logback.xml # 日志配置（可选） ├── java-module/ # Java 自动化模块 │ ├── pom.xml │ └── src/test/java/... ├── python-module/ # Python 自动化模块 │ ├── requirements.txt │ ├── conftest.py │ └── tests/... └── docs/ # 文档

为什么要用多 Module 而不是普通子目录？因为 IDEA 的多 Module 模式允许每个模块独立指定 SDK、独立管理依赖。Java 模块用 Maven 管理 jar 包，Python 模块用 venv 管理 pip 包，两者互不污染。创建方法也很简单：右键工程根节点，选择 New -> Module，一路按向导创建就行。Java 模块选 Maven，Python 模块选 Python 并指定解释器。

这个结构建议写在 README 里，让团队每个人 clone 下来第一步就知道该怎么做。

3. Java 自动化模块：用 Maven + TestNG + RestAssured 把接口用例跑起来

3.1 pom.xml 里最关键的依赖，少一个就跑不起来

在 IDEA 中新建 Maven 模块后，第一件事是编辑pom.xml。我以订单服务接口测试为例，核心依赖是这些：

<dependencies> <!-- 测试框架 --> <dependency> <groupId>org.testng</groupId> <artifactId>testng</artifactId> <version>7.10.2</version> </dependency> <!-- 接口测试 --> <dependency> <groupId>io.rest-assured</groupId> <artifactId>rest-assured</artifactId> <version>5.5.0</version> </dependency> <!-- JSON 解析，用于读取共享配置 --> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.17.2</version> </dependency> <!-- Allure 报告适配 --> <dependency> <groupId>io.qameta.allure</groupId> <artifactId>allure-testng</artifactId> <version>2.29.0</version> </dependency> </dependencies>

这里我不写死版本号以外的详细插件配置，因为不同团队用的 Maven 仓库源不一样。建议第一次引入依赖后，让 IDEA 自动下载，本地仓库里有了以后，后续构建会快很多。如果公司内网有私服，记得在settings.xml里配好镜像地址，否则下载依赖能卡一整天。

3.2 第一个 TestNG 接口用例，把数据驱动写进代码里

我习惯用一个订单接口作为冒烟用例。需求很简单：向POST /api/orders发送订单编号和数量，校验返回状态码。先写一个标准的 TestNG 测试类：

import io.restassured.RestAssured; import io.restassured.http.ContentType; import org.testng.annotations.DataProvider; import org.testng.annotations.Test; import static org.hamcrest.Matchers.*; public class OrderApiTest { @DataProvider(name = "orderData") public Object[][] orderData() { return new Object[][]{ {"A1001", 2, 200}, {"A1002", -1, 400} }; } @Test(dataProvider = "orderData") public void testCreateOrder(String orderNo, int quantity, int expectedCode) { RestAssured.baseURI = "http://localhost:8080"; RestAssured.given() .contentType(ContentType.JSON) .body("{\"orderNo\":\"" + orderNo + "\",\"quantity\":" + quantity + "}") .when() .post("/api/orders") .then() .statusCode(expectedCode); } }

几个关键点说一下：

• @DataProvider是 TestNG 自带的数据驱动方式，用例方法每接收一组参数就会执行一次，测试报告里每条数据都是独立用例。
• RestAssured.given()...when()...then()是接口测试的经典链式写法，可读性非常好。
• 状态码直接作为参数传进去，方便后续扩展不同场景：鉴权失败、参数缺失、数据重复等。

拿到一个能跑的用例，比什么都重要。千万不要一上来就堆几十个用例，否则后期报错排查成本极高。

3.3 在 IDEA 里配置 TestNG 运行器

写完测试类，右键点击类名，选择 Run 如果想直接用 IDEA 默认配置，一般能跑。但如果想固定使用 TestNG 而不是 JUnit，需要确认运行配置中的 Test Runner 确实是 TestNG。

我的操作习惯是：新建一个运行配置，类型选 TestNG，Class 选择OrderApiTest，然后保存。以后只需要点一下运行按钮就能复跑。测试结果会在 IDEA 底部的 Run 面板显示，绿色代表通过，红色代表失败。失败时堆栈信息按包名折叠，点击任意一行就能跳到对应代码，非常方便。

Java 侧先跑通这一个冒烟用例，你的 Java 模块骨架就算搭起来了。

4. Python 自动化模块：pytest + requests + 数据驱动写同样一套接口用例

4.1 创建 Python 模块并激活虚拟环境

在根工程下新建 Python Module 后，IDEA 会提示你选择解释器。这里我强烈建议用虚拟环境。新建完模块后，在 IDEA 的 Terminal 窗口执行：

cd python-module python -m venv venv

然后回到项目结构设置里，把 Python 模块的 SDK 指向刚才创建的venv解释器。如果你不确定自己选没选对，可以看 IDEA 的 Python Packages 面板，如果能看到项目里安装的第三方库，说明绑定成功。

接着写requirements.txt：

pytest==8.3.2 requests==2.32.3 allure-pytest==2.13.5

然后在 Terminal 执行：

pip install -r requirements.txt

安装完成后，可以顺手跑一下pytest --version确认环境没问题。

4.2 conftest.py 与 fixture，给 Python 模块搭好地基

pytest 里最常用的功能就是 fixture（夹具）。fixture 的好处是复用，比如"获取基础路径"、"建立 HTTP Session"、"登录认证"，这些每个用例都要用的东西，写成 fixture 后一个文件搞定。

我在python-module/conftest.py里这样封装：

import json from pathlib import Path import pytest import requests # 定位到项目根目录下的 config 目录 CONFIG_DIR = Path(__file__).resolve().parents[1] / "config" @pytest.fixture(scope="session") def base_url(): with open(CONFIG_DIR / "config.json", encoding="utf-8") as f: cfg = json.load(f) return cfg["base_url"] @pytest.fixture(scope="session") def http_session(base_url): session = requests.Session() session.headers.update({"Accept": "application/json"}) yield session session.close()

这里有两个细节值得展开：

第一，我用了Path(__file__).resolve().parents[1]来定位配置目录，这样不管你在哪个目录下执行 pytest，都不会因为相对路径报错。很多新手在这步踩坑，直接用../config/config.json，结果换台机器或者换个运行方式就找不到文件了。

第二，http_session是 session 级别的 fixture，整个测试过程只创建一次 Session，对后端服务压力也小，性能比每个用例都重新握手要快不少。

4.3 pytest 用例与参数化，写法比 Java 更简洁

在tests目录下新建测试文件test_create_order.py，内容如下：

import pytest @pytest.mark.parametrize("order_no, quantity, expected_code", [ ("A1001", 2, 200), ("A1002", -1, 400), ]) def test_create_order(http_session, base_url, order_no, quantity, expected_code): resp = http_session.post( f"{base_url}/api/orders", json={"orderNo": order_no, "quantity": quantity} ) assert resp.status_code == expected_code

pytest 的parametrize和 Java 的@DataProvider是完全对应的概念，但语法上更直观：一行一个参数组合，用例名称也会自动带上参数名，方便在报告里区分。

在 IDEA 里运行 pytest 也有一个 hidden trap：默认运行配置可能是 unittest。这时你要手动新建一个运行配置，把 Test Runner 选成 pytest。位置在运行配置面板的 Execution 选项里。选对之后，点击运行按钮，IDEA 的 Run 面板会显示每个用例的执行结果，并支持单独点击某个测试方法重跑。

到这里，Python 侧也通了。此时你已经有了两个能独立运行的模块，接下来才是真正拉开差距的部分：怎么让它们在一个工程里协作。

5. Java 和 Python 在同一工程里的三种协作方式，这才是混合框架真正加分的点

5.1 数据协同：一份 JSON 配置，两边共用

先建一个config/config.json：

{ "base_url": "http://localhost:8080", "timeout": 10, "test_account": { "username": "autotest", "password": "change-me" } }

Java 侧读取配置，可以用 Jackson：

import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import java.io.File; public class ConfigReader { public static String getBaseUrl() throws Exception { ObjectMapper mapper = new ObjectMapper(); JsonNode cfg = mapper.readTree(new File("../config/config.json")); return cfg.get("base_url").asText(); } }

Python 侧读取同一份配置：

import json from pathlib import Path cfg = json.loads(Path("../config/config.json").read_text(encoding="utf-8")) base_url = cfg["base_url"]

这样做最大的好处是：切换环境（本地、测试环境、预发布环境）时，只改一个文件。Java 用例和 Python 用例都会同时感知到。省去了以前两套环境变量各自管的痛苦。为了稳妥，我建议在自动化框架里增加一个环境变量AUTO_ENV，用它对 config.json 里的多环境配置做二次选择。但就算从简，单文件也能覆盖大多数团队需求。

5.2 执行协同：Java 用例里动态调用 Python 脚本

有时候需要 Java 负责断言，但测试数据需要 Python 脚本生成。比如订单数据造数脚本tools/gen_order_data.py，Java 侧可以用 JDK 自带的ProcessBuilder调用它：

import java.io.File; public class PythonInvoker { public static int runScript(String scriptPath) throws Exception { ProcessBuilder pb = new ProcessBuilder("python", scriptPath); pb.directory(new File("python-module")); pb.redirectErrorStream(true); Process process = pb.start(); return process.waitFor(); } }

然后在 TestNG 的测试方法里调用：

@Test public void testWithPythonPreparedData() throws Exception { int exitCode = PythonInvoker.runScript("tools/gen_order_data.py"); assert exitCode == 0 : "Python 造数脚本执行失败"; // 后续继续走 Java 断言逻辑 }

这里要特别强调一个点：跨语言调用不是越多越好。我见过有人把核心接口断言也用 Python 再写一遍，最后两边逻辑不一致，维护成本反而更高。我的建议是只让 Python 做"Java 不方便做的事"，比如批量造数、数据清洗、非结构化文件处理。反过来，Python 侧也可以调用 Maven 命令跑 Java 用例，但一般情况下没必要，因为报告合并和 CI 调度已经能解决问题。

5.3 报告协同：Allure 统一多语言测试报告

报告统一是我的心头好。以前两套报告，负责人每次都要看两个页面。现在用 Allure 做合并，一条命令解决。

Java 侧引入allure-testng后，跑完mvn test会在target/allure-results目录下生成 JSON 结果文件。Python 侧跑 pytest 时加上参数：

pytest python-module/tests \ --alluredir=python-module/allure-results \ --junitxml=python-module/junit-results.xml

这里同时生成 Allure 结果和 JUnit XML。JUnit XML 是很多 CI 系统自动识别测试结果的标准格式，兼容性最好。两条命令都跑完后，在工程根目录执行：

allure generate java-module/target/allure-results python-module/allure-results -o merged-report --clean

然后用allure open merged-report打开合并后的报告。一个页面里既有 Java 用例，又有 Python 用例，用例分层、失败截图、执行时间一目了然。这条方案我在项目里用了大半年，团队再也没有为"你那份报告呢"这种事情吵过架。

6. 实操排雷清单：这些坑我踩过，不希望你再来一遍

6.1 Python SDK 不被识别，是最常见的起手式问题

现象：IDEA 在文件右上角显示红色波浪线，提示 no interpreter configured。原因一般有两个：一是装完 Python 插件后没有重启 IDEA；二是创建 Module 时没有绑定解释器。

解决方法很直接：打开项目结构设置，在 SDKs 里手动添加解释器，选中虚拟环境里那个python.exe（Windows）或bin/python（Linux/macOS）。绑定之后，IDEA 会花几十秒做一次索引，之后补全和运行配置就都正常了。如果你用的是社区版加第三方插件，这一步偶尔还会出问题，我的建议是遇到识别失败的，优先切换成旗舰版的干净环境再试。

6.2 运行配置里选错执行器，会导致用例"不跑"或"全红"

IDEA 的智能识别虽然好用，但有一种场景特别坑：同一个 Python 文件里有unittest风格代码，也有 pytest 用例，IDEA 默认会用 unittest 执行，结果 pytest 里的参数化用例根本跑不起来，还会冒出"cannot find test"之类的报错。

解决办法：在运行配置中手动把 Default Test Runner 设置成 pytest。Java 侧也一样，如果你写的是 TestNG 注解，但默认执行器是 JUnit，IDEA 会给出"no tests were found"的提示。遇到这种提示，先看一眼执行器类型，而不要怀疑自己的代码写错了。这一个排查动作能帮你省下至少一个小时。

6.3 IDEA 索引慢、内存吃紧，把无关目录排除掉

多语言工程里的依赖目录很占资源，尤其是 Python 虚拟环境，动辄几万个文件。我一开始没处理，IDEA 每次扫描都要卡十几秒，后来做了两件事：

第一，在项目视图里右键.venv、target、build、.pytest_cache这些目录，选择 Mark Directory as -> Excluded，让 IDEA 不再索引它们。第二，调整 IDEA 的内存参数。在 Help 菜单里找到 Edit Custom VM Options，把-Xmx提高到合适值。我的机器配置是-Xmx2048m，跑 Java + Python 双模块还比较稳定。这里要谨慎，别一上来就调 4G、8G，内存过大反而可能拖累整个系统。

6.4 Git 共用与 .idea 目录，别因为配置问题让全队返工

关于.idea目录到底要不要提交，团队内部一直有争议。我的建议是：提交，但有选择性。.idea里保存的运行配置（比如 TestNG 配置、pytest 配置）对全队都有价值，适合共享。但workspace.xml、shelf、任务列表这些纯个人状态不应该提交，否则每个人打开工程都会收到一堆无关变更。

.gitignore可以这样写：

.idea/workspace.xml .idea/shelf/ .idea/tasks.xml **/target/ **/.venv/ **/__pycache__/ **/.pytest_cache/ allure-results/ merged-report/

6.5 路径分隔符与环境变量，Windows 和 macOS 的差异要提前防

团队里有人用 Windows，有人用 macOS 时，路径写法最容易出问题。我在 Java 里写读取共享配置时，用的是new File("../config/config.json")，这在 Windows 和 macOS 上都能工作。在 Python 里，我坚持用Path(__file__).resolve().parents[1]这样的方式，而不是字符串拼接。

还有一个细节：ProcessBuilder 调用 Python 时，Windows 下解释器命令可能是venv\Scripts\python.exe，macOS 下是venv/bin/python。所以跨平台场景下，最好把 Python 解释器路径也做成配置项，放在 config.json 里按系统区分，否则很容易出现本地跑得好好的、到同事电脑上就报"无法识别 python 命令"的尴尬。

说句掏心窝的话：混合框架最怕的不是语言不同，而是没有统一的约定。只要配置文件共管、报告共出、运行入口共用一个 IDEA 工程，Python 和 Java 互为补充，这件事就成了。别一开始求大而全，先把今天这套最小闭环跑通，后续再一点点加用例、加模块，你会回来感谢自己的。