Python自动化测试环境搭建指南：从零到跑通第一个用例

说实话，自动化测试环境搭建这件事，看起来是个“装个Python、pip install几个包”的活儿，但我见过太多人在这一步折腾几天都跑不通第一个用例。早些年我刚转到自动化测试岗时也吃过这个亏——兴冲冲写好了脚本，结果卡在驱动版本不匹配、依赖冲突、pytest不识别用例这些莫名其妙的报错上。折腾多了以后，我慢慢形成了一套比较固定的搭建流程，按这套流程走，基本半小时内就能把一套干净的Python自动化测试环境跑起来。这篇文章就是把这套流程完整地复盘出来，包括选型逻辑、操作命令、配置文件和最常见的一批坑，给正准备入门或者正在被环境问题折磨的朋友一个可直接照做的蓝本。

这套环境不光能跑Web UI自动化（Selenium）、接口自动化（requests + pytest），也能覆盖App自动化（Appium）的基础依赖。我会尽量把每个环节“为什么这么做”也讲清楚，因为你只有理解了背后的取舍，后面遇到报错时才不会慌。

1. 先把要装的东西拆开：自动化测试环境的四层结构

很多人搭环境装得一团乱，根源是没搞清楚环境里到底有哪几类东西。Python自动化测试环境不是“装个Python就完事”，它至少要分成四层：

• 解释器层：就是Python本体，负责运行你的代码。这层最关键的是版本选择。
• 依赖管理层：包括pip和虚拟环境，负责把项目用到的第三方库装进来，并且做到项目之间互不干扰。
• 测试框架层：pytest、unittest这类执行用例、收集用例、输出测试报告的基础设施。
• 功能支撑层：根据你的测试目标来定，做Web自动化就装Selenium，做App自动化就装Appium客户端，做接口测试就装requests。

把这四层拆开思考之后，整个环境的逻辑就很清晰了：底层是解释器，上面是依赖管理，再上层是框架，最后是具体业务的支撑库。你每装一个东西都要能回答“我装它属于哪一层、解决什么问题”，这样就不会瞎装一通了。

1.1 一套可以抄作业的版本工具清单

先给出一套我长期在用的组合，这套组合兼顾稳定性和生态兼容性，适合绝大多数自动化测试项目：

这套组合里，pytest框架是核心，围绕它的周边插件可以根据项目需求再加。需要说明的是，webdriver-manager是一个非常好用的辅助库，它解决了“浏览器驱动和浏览器版本不匹配”这个经典问题，下面的章节我会细讲。

1.2 版本不追新的取舍逻辑

为什么Python用3.10或3.11而不是最新的3.12、3.13？先说结论：第三方库的兼容速度往往落后于Python官方的发布速度。

Python 3.12刚出来那阵子，很多知名的库还没发对应版本的wheel包，你用pip安装时经常需要现场编译，一旦机器上没有对应的编译工具链，就会报出一堆红色错误。3.13就更不用说了，目前生态还有待完善。3.8虽然稳定，但已经偏老，一些新库已经宣布不支持3.8了。3.10和3.11是当前“生态兼容性最好”的区间，尤其是3.11，官方自己也说了性能上有大幅提升，跑起测试脚本明显更快。

pytest的版本同理，8.x已经比较成熟，但7.x的生态兼容性更好。如果公司里有一些比较老的插件或者自定义插件，7.x踩坑的概率更低。Selenium的版本要注意，Selenium 3和Selenium 4的API差别很大，Selenium 3里的find_element_by_id这类方法在Selenium 4里被彻底去掉了，如果你在网上找到的是老教程，直接照抄一定会报AttributeError。所以统一用Selenium 4.x。

2. 基础层实操：从解释器安装到虚拟环境隔离

定好版本之后，就可以开始动手安装了。这一层操作虽然简单，但也是最容易埋雷的地方。很多人后面出现的奇怪报错，追根溯源都是基础层没做好。

2.1 解释器安装：PATH和pyenv是关键

Windows下安装Python相对简单，去官网下载对应版本的安装包就行。但有一个细节我必须要强调：安装时务必勾选“Add Python to PATH”。

如果没勾选，你打开CMD输入python，系统会提示“python不是内部或外部命令”。这个提示卡住的初学者不计其数。解决办法有两种：一是重新运行安装包，勾选Add to PATH后执行Modify安装；二是手动把Python安装目录和Scripts目录加到系统环境变量Path里。我更推荐第一种，简单不容易错。

Linux/macOS下情况不太一样，系统自带的Python往往不是给你做开发用的，直接动它容易把系统组件搞坏。我推荐用pyenv来管理多个Python版本。基本操作是这样的：

# 安装pyenv后，安装并切换指定版本 pyenv install 3.11.9 pyenv global 3.11.9 python --version

这样做的最大好处是，你可以在同一台机器上同时保留3.10和3.11等多个版本，随时切换，互不影响。团队里如果有的项目锁定3.10，有的锁定3.11，也不会打架。

装好解释器后，先用命令验证一下：

python --version pip --version

能正常输出版本号，这层就算过关了。

2.2 pip配置国内镜像源：省下一半的等待时间

pip是Python的包管理工具，默认情况下它从PyPI官方源下载软件包，国内访问这个源经常时快时慢，遇到大包直接超时。解决这个问题的方法很成熟——配置国内镜像源。

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

执行完这行命令后，pip会把镜像源配置写入用户目录下的配置文件里，之后所有install操作都会走清华源，速度会快很多。除了清华源，阿里云源（mirrors.aliyun.com/pypi/simple/）也不错，我个人用清华源多，稳定性和同步速度都很好。

这里有个经验：不建议用pip install xxx -i https://pypi.tuna.tsinghua.edu.cn/simple这种临时指定源的方式。虽然能解决问题，但每次装包都得手动带上参数，如果中间有人换了一台机器或忘了带参数，又会掉回慢速状态。一次性写进全局配置，省心得多。

2.3 虚拟环境：让每个项目的依赖井水不犯河水

虚拟环境是环境搭建里最容易被忽略但最重要的一环。简单解释一下：不同的测试项目可能依赖同一个库的不同版本。比如项目A需要selenium 4.15，项目B需要selenium 3.141。如果全都装到全局环境，后装的会把先装的覆盖掉，项目A再跑就会报错。

用Python内置的venv创建虚拟环境，就是给每个项目圈一个独立的“依赖小房间”。创建和激活的步骤如下：

# Windows python -m venv .venv .venv\Scripts\activate # Linux/macOS python -m venv .venv source .venv/bin/activate

激活成功最明显的标志是：命令行前缀变成了(.venv)。有些人看到这个变化还不够确认，我一般会再执行一下where python或which python，确认当前指向的是项目目录下的.venv路径，才算真正进入了虚拟环境。

注意Windows PowerShell如果提示“无法加载文件...因为在此系统上禁止运行脚本”，那是因为执行策略限制。可以先执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser放行，再激活。激活后如果要退出虚拟环境，直接执行deactivate。

依赖装好后，导出到requirements.txt是个好习惯，这样换机器或者别人拉取代码时，一条命令就能复现整个环境：

pip freeze > requirements.txt # 在另一台机器/另一个虚拟环境中 pip install -r requirements.txt

2.4 VSCode里的解释器选择

现在做自动化测试的人用VSCode的很多，安装好Python插件后，VSCode会自动识别你机器上的Python解释器。但要注意：VSCode默认使用的解释器未必是你激活的那个虚拟环境。

我吃过这个亏：在终端里明明激活了.venv，pytest命令也能跑通，但VSCode的代码检查一直提示slience无法导入之类的报错。后来发现是VSCode右下角选中的解释器还是全局Python。

正确配置方法：按Ctrl+Shift+P，输入Python: Select Interpreter，在弹出的列表里选中项目下的.venv\Scripts\python.exe。这样VSCode的终端、调试器、代码补全就都会基于同一个虚拟环境，避免“终端能跑、编辑器报错”的割裂情况。

3. 测试框架层：pytest的安装与工程化配置

基础层搞定后，接下来是测试框架。这部分直接决定你后续写用例的效率和工程化程度。

3.1 为什么选pytest而不是unittest

Python标准库自带unittest，很多人觉得“既然自带就不用装了”。但如果做的是真正的自动化测试项目，我强烈建议用pytest。两者的差距主要在几个方面：

pytest还有一点很讨喜：它天然兼容unittest风格的用例。也就是说，你现在用unittest写的测试类，放到pytest里也能跑。这意味着升级框架的成本很低，你完全可以新项目用pytest，老代码不用急着重写。环境搭建阶段直接就用pytest，把自己的工程往这个方向上规划，是更省力的选择。

安装非常简单：

pip install pytest

想验证装没装上，执行pytest --version，能输出版本号就行。

3.2 一个最小可运行的测试工程长什么样

很多人环境装好了却不知道怎么组织代码，一会儿写一堆脚本在根目录，一会儿又放在某个临时文件夹里，最后连自己都找不到用例在哪。我建议从一开始就按下面的结构来组织：

test_project/ ├── .venv/ # 虚拟环境目录 ├── requirements.txt # 依赖清单 ├── pytest.ini # pytest配置文件 ├── conftest.py # pytest全局fixture ├── common/ # 公共封装模块 │ ├── __init__.py │ └── base.py └── testcases/ # 测试用例目录 ├── __init__.py ├── test_login.py └── test_order.py

每个文件的职责说一下：

• pytest.ini是核心配置文件，我通常在里面写这些内容：

[pytest] minversion = 7.0 testpaths = testcases python_files = test_*.py python_classes = Test* python_functions = test_* addopts = -v -s

配置里的testpaths告诉pytest去哪找用例，python_files规定哪些文件算测试文件，addopts是默认运行时自动加上的参数。-v表示输出详细日志，-s表示显示print输出。这样设置后，你在命令行直接敲pytest，不需要带任何参数，pytest就会自动找到testcases目录下的所有用例并跑起来。

• conftest.py是pytest的全局配置钩子文件。比如你希望所有用例执行前都创建一个测试数据，或者启动浏览器，就可以把对应的fixture写在conftest.py里。它的作用范围是当前目录及其子目录，放在项目根目录下，就能作用于整个项目。

• common/base.py放一些与被测系统打交道的基础封装，比如请求封装、浏览器操作封装。测试用例层只写业务步骤和断言，不直接堆底层代码。

3.3 从命令行跑通第一个用例

按照上面的规划，我在testcases目录下创建一个test_demo.py，内容先写一个最简单的冒烟用例：

import pytest def test_sum(): a = 1 b = 2 assert a + b == 3 def test_demo_print(): print("环境搭建成功，pytest已经可以正常收集用例了")

然后在命令行先确认当前处于.venv虚拟环境，再执行：

pytest

如果一切正常，你会看到类似下面的输出片段：

collected 2 items test_demo.py::test_sum PASSED test_demo.py::test_demo_print PASSED

看到PASSED字样，说明整套pytest框架已经正常工作了。如果你在配置里加了-s，test_demo_print里的print内容也会显示出来。

4. 扩展层：把Selenium、Appium和接口测试的依赖补齐

框架跑通之后，接下来就是按你的业务目标去装支撑库。我把它分成三个方向，你根据自己的需求选择性地安装。一般公司里的自动化测试团队，这三块早晚都会碰到。

4.1 Selenium 4 + webdriver-manager：告别驱动器版本地狱

Selenium是做Web UI自动化绕不开的库。安装就一条命令：

pip install selenium

但光装Selenium还不够。Selenium本身不直接控制浏览器，它需要通过WebDriver驱动去跟浏览器通信，而驱动是每个浏览器单独维护的。如果你的Chrome浏览器自动升级到了某个版本，而驱动还是旧版，运行脚本时就会报一个经典错误：

selenium.common.exceptions.SessionNotCreatedException: Message: session not created: This version of ChromeDriver only supports Chrome version xxx

以前的解决办法是自己去ChromeDriver官网或其他渠道下载匹配版本的驱动，然后手动放到PATH或指定路径。但浏览器一升级就得重新下载，非常折磨人。

现在更聪明的做法是用webdriver-manager这个库，它会在运行时检测当前浏览器版本，自动下载匹配的驱动，并对驱动做缓存。

pip install webdriver-manager

使用示例：

from selenium import webdriver from webdriver_manager.chrome import ChromeDriverManager from selenium.webdriver.chrome.service import Service service = Service(ChromeDriverManager().install()) driver = webdriver.Chrome(service=service) driver.get("https://www.baidu.com") print(driver.title) driver.quit()

这个方案是我目前最推荐的，尤其是新项目或者个人学习，把“下载驱动”这个环节彻底自动化了。团队中如果有统一的基础镜像，也可以直接在镜像里预装好驱动，但webdriver-manager依然是可回退的后备方案。

另外提一下selenium 4自带的Selenium Manager功能。新版selenium在初始化driver时会自动尝试去找驱动，但在部分网络环境或特殊配置下，它可能不生效或下载失败。相比之下webdriver-manager的表现更可控，这也是我用它作为首选的另一个原因。

4.2 Appium环境的边界：不是pip install那么简单

如果你要做App自动化测试，环境会明显复杂一些，因为除了Python客户端还需要外围服务。

需要安装的东西大致有这几项：

• Node.js环境：Appium Server依赖Node.js运行。
• Appium Server：通过npm安装，执行npm install -g appium。
• Android SDK / adb：连接真机或模拟器时需要，adb工具来自Android Platform Tools。
• Python客户端：pip install appium-python-client。

Python端的安装很简单，剩下Node.js和Android SDK属于独立于Python环境之外的东西。环境搭建的坑往往在Android SDK路径配置、adb版本不一致、设备连接不稳定这些方面。

我特别想提醒一点：不要让Appium的依赖和你的pytest项目塞在同一个虚拟环境里，或者至少要把appium-python-client和相关服务放在一起统一管理，否则包依赖很容易互相干扰。在我自己的工程里，Web自动化和App自动化用的是两个独立虚拟环境，这样App那边即使把环境搞坏了，也不会影响Web测试的日常运行。

4.3 接口测试的轻量准备：requests就够

接口自动化测试在环境层面的要求其实很低，一个requests库加pytest就够了。

pip install requests

requests是Python社区最常用的HTTP请求库，它的API设计非常直观。配合pytest写接口用例时，我一般会封装一个简单的方法，放在common/base.py里：

import requests class HttpRequest: def __init__(self, base_url): self.base_url = base_url def get(self, path, params=None, headers=None): return requests.get(self.base_url + path, params=params, headers=headers)

这样测试用例里只关注业务断言，不用关心URL拼接和请求细节。

如果你要生成漂亮的测试报告，可以再装两个插件：

pip install allure-pytest pytest-html

allure-pytest用于生成Allure报告数据，pytest-html则可以直接生成一个简洁的HTML报告。执行用例时这样运行：

pytest --html=report.html

跑完之后根目录下会生成report.html文件，浏览器打开就能看到每个用例的执行结果。这块算是投入小、见效快的提升环境体验的手段。

5. 环境验证与高频报错排查指南

环境全部装完之后，别急着写一大堆用例，先花两分钟做一次系统性验证，把“环境本身是否健康”这件事确认到位。这样后续出了问题，你能明确区分究竟是环境问题还是脚本问题。

5.1 一条命令快速体检环境

我习惯在项目的虚拟环境里执行这样一个组合命令：

python -c "import pytest; import selenium; import requests; print('pytest:', pytest.__version__); print('selenium:', selenium.__version__); print('requests:', requests.__version__)"

这条命令会同时验证三个关键库能不能正常导入并打印版本号。如果输出正常，说明依赖装得没问题。如果你打算做App自动化，再把appium模块加进去验证一下：

python -c "from appium import webdriver; print('appium client ok')"

再进一步，用pytest自带的收集功能看看用例是否能被正确发现：

pytest --collect-only -q

如果输出的是collected N items，说明测试文件路径、用例命名规则和配置都是协调的。如果输出的是no tests ran或者collected 0 items，那就要检查文件名是不是以test_开头、用例函数是不是以test_开头，以及pytest.ini里的testpaths是否指对了目录。

5.2 这些年我反复遇到的环境坑位

环境搭建的坑，看起来五花八门，其实高度重复。在这里把我踩过十几遍的和读者反馈频率高的集中列出来，每种都给出判断方法和解法。

这里重点展开两个最容易让人懵的场景。

第一个是“pip装到了别的地方”。你在venv里执行pip install，结果程序运行时还是提示找不到模块。最可能就是安装时没有激活venv，或者venv激活后但在另一个终端窗口里运行代码。我建议在安装完依赖之后，执行一下pip list，看列表里的库在不在。如果再谨慎一点，执行python -c "import sys; print(sys.executable)"，看看当前脚本解释器指向的是不是venv。

第二个是selenium里的find_element系列。网上有一些老教程还在用driver.find_element_by_id("kw")这种写法，这套API在selenium 4里被移除了。如果你看到这样的代码，需要改成新写法：

from selenium.webdriver.common.by import By driver.find_element(By.ID, "kw")

这类问题不是环境问题，而是代码版本与库版本不匹配的问题。遇到时不要怀疑环境没装好，先检查一下参考资料的时效性。

5.3 依赖冲突的整体排查思路

虚拟环境很大程度上解决了项目之间的依赖冲突，但同一个项目内也可能出现两个库各自依赖不同版本的情况。比如库A依赖requests 2.28，库B依赖requests 2.31，pip在安装时一般会自动协调成2.31，若协调失败就会出现依赖冲突。

判断依赖冲突时，pipdeptree是一个很好用的工具：

pip install pipdeptree pipdeptree

它会以树状图的形式打印出当前环境里所有库的依赖关系，能直观看到哪些包对同一个版本有不同要求。用它定位到冲突源后，通常是升级或降级其中一个包解决问题。如果项目紧急，临时办法是在requirements.txt里固定冲突包的版本，或者用pip install --force-reinstall重新安装其中一个包。

依赖冲突这个问题，我的切身建议是：不要在同一个环境里装花里胡哨的一大堆库。自动化测试环境要做到“按需扩容”，需要什么再装什么，用不到的库坚决不装。真要用到分析工具，建议在单独的虚拟环境里搞。这样环境会始终保持干净，排查问题的时间也会大幅缩短。

6. 三个能立竿见影的小习惯

环境搭建这个事本身不难，难的是把环境“养”得干净、稳定、可复现。最后分享三个我实际工作里一直在用的习惯，每个都能省掉不少后期折腾。

第一，所有依赖变更都写进requirements.txt，并区分环境。我一般会维护三个文件：requirements.txt（基础运行依赖）、requirements-dev.txt（开发调试工具）、requirements-report.txt（报告插件类）。为什么分开？因为生产跑测试的环境不需要装报告插件，而开发环境需要。分开管理后，换环境部署时不会把没用的包也一起装上，减少冲突概率。

第二，每建一个测试项目，先把最小冒烟用例跑通，再开始写业务逻辑。这跟我文章里的验证逻辑一脉相承——先确认环境是好的，再往上盖楼。否则你写了50个用例，跑挂以后根本分不清是环境问题还是用例问题。

第三，把整套环境固化成文档或脚本。我习惯在项目根目录放一个setup.sh或者setup.bat，里面写好创建虚拟环境、配置pip源、安装依赖、验证环境的完整命令。这样团队来新人，或者自己换电脑时，一键就能复现整套环境，不用重新摸索。自动化和标准化的思想，不光用在测试脚本上，也应该用在环境搭建本身。

这套Python自动化测试环境搭建流程，我自己一直在用，也带过不少刚入行的同事按这个流程操作，整体反馈是“能少走很多弯路”。核心就是先把四层结构想清楚，再按层落地，最后把验证和排查的方法储备好。环境稳定了，你后面写用例、跑回归、出报告才会顺心。