SeleniumBase 交互式产品导览Tours完全指南基于 5 种 JavaScript 向导库的引导式网页演练【免费下载链接】SeleniumBaseAPIs for browser automation, testing, and bypassing bot-detection. Includes CDP Mode: A stealthy configuration for chromium that passes every bot detection test.项目地址: https://gitcode.com/GitHub_Trending/se/SeleniumBaseSeleniumBase 的 Tours 功能允许测试脚本在任何网站上创建交互式产品导览walkthrough / guided tour通过高亮元素、气泡提示与逐步讲解引导用户熟悉页面功能。本指南以 examples/tour_examples/ReadMe.md 为核心完整覆盖五种向导库IntroJS、Bootstrap Tour、DriverJS、Shepherd、Hopscotch的创建、步骤添加、播放、自动播放与导出能力并深入 seleniumbase/fixtures/base_case.py 与 seleniumbase/core/tour_helper.py 的源码实现帮助读者快速上手编写自己的产品导览测试。一、什么是 SeleniumBase ToursSeleniumBase Tours 是一套内置在BaseCase类中的引导式导览能力它可以在任意网站上生成分步交互式讲解每一步都会在页面元素旁弹出一条带标题和说明文字的提示气泡并用高亮、遮罩等方式把用户注意力引导到指定控件上。整套体系封装了 5 个成熟的开源 JavaScript 向导库使用者无需接触任何前端代码只用几个 Python API 就能完成导览的构建与播放向导库用途特点IntroJS默认向导库轻量、易定制支持步骤编号、进度条与键盘导航Bootstrap Tour基于 Bootstrap 风格的导览支持步骤级自动前进duration参数DriverJS以高亮遮罩著称支持按钮文案与动画配置Shepherd主题最丰富提供 6 种内置主题样式HopscotchLinkedIn 出品的导览框架气泡样式简洁默认锚定在元素底部从源码看这 5 个库的 CSS/JS 资源地址统一在 seleniumbase/fixtures/constants.py 中维护IntroJS 5.1.0、Bootstrap Tour 0.12.0、DriverJS 0.9.8、Hopscotch 0.3.1、Shepherd 1.8.1、Tether 1.4.7、jQuery 3.7.1运行时由 seleniumbase/core/tour_helper.py 中的activate_*系列函数动态注入页面因此不需要修改被测网站的代码。二、快速开始运行内置示例仓库的 examples/tour_examples 目录下提供了 11 个可直接运行的示例脚本覆盖了全部 5 种向导库bootstrap_google_tour.py # Bootstrap Tour 版 Google 导览 bootstrap_xkcd_tour.py # Bootstrap Tour 版 xkcd 导览 driverjs_maps_tour.py # DriverJS 版 Google Maps 导览 google_tour.py # 综合演示 4 种库的旗舰示例 hopscotch_google_tour.py # Hopscotch 版 Google 导览 introjs_google_tour.py # IntroJS 版 Google 导览 maps_introjs_tour.py # IntroJS 版 Google Maps 导览可自动播放 octocat_tour.py # GitHub Octocat 导览 shepherd_google_tour.py # Shepherd 版 Google 导览 xkcd_tour.py # xkcd 导览示例一Google Maps 自动播放导览IntroJScd examples/tour_examples pytest maps_introjs_tour.py --interval1--interval1是 pytest 命令行参数含义是每 1 秒自动前进一个导览步骤。在 maps_introjs_tour.py 中脚本先用wait_for_element()等待地图页关键控件搜索框、缩放按钮、底图小组件就绪再创建 IntroJS 导览依次讲解搜索框、搜索按钮、路线、卫星视图、缩放与菜单等功能最后调用self.export_tour(filenamemaps_introjs_tour.js)导出导览并self.play_tour()播放。示例二综合导览同时演示 4 种向导库cd examples/tour_examples pytest google_tour.pygoogle_tour.py 是官方最完整的综合示例先使用--ucundetected 模式启动浏览器依次创建并播放 Shepherddark / light 两个主题、Bootstrap3 秒自动播放、IntroJSGoogle Maps 页共 4 段导览并在结束时调用self.export_tour()导出 JavaScript 文件。注意Tours 需要真实浏览器窗口才能演示效果。源码中 play_tour 会在 headless、headless2 或 xvfb 模式下直接跳过播放因此请使用带显示环境的浏览器运行。三、创建导览选择向导库与主题创建一段导览有两种等价写法使用create_tour(theme...)统一入口或使用各库专用的创建方法。3.1 统一入口create_tour()self.create_tour(nameNone, themeNone)是推荐入口。根据 base_case.py 中 create_tour 的实现theme的取值与内部路由规则如下theme取值实际创建的导览说明bootstrapBootstrap TourhopscotchHopscotchintro/introjsIntroJSdriver/driverjsDriverJSshepherd/light/arrowsShepherdlight/arrows 主题darkShepherddark 主题squareShepherdsquare 主题square-darkShepherdsquare-dark 主题defaultShepherddefault 主题不传 / 其他值IntroJS默认向导库3.2 各库专用创建方法每种库也提供了独立方法语义与统一入口完全等价self.create_shepherd_tour(nameNone, themeNone) # 等价 create_tour(themeshepherd) self.create_bootstrap_tour(nameNone) # 等价 create_tour(themebootstrap) self.create_introjs_tour(nameNone) # 等价 create_tour(themeintrojs) self.create_driverjs_tour(nameNone) # 等价 create_tour(themedriverjs) self.create_hopscotch_tour(nameNone) # 等价 create_tour(themehopscotch)3.3 Shepherd 主题详解Shepherd 是唯一支持主题定制的库。从 create_shepherd_tour 源码 可以看到主题会映射为 Shepherd 的 CSS class主题对应的 CSS class效果light默认shepherd-theme-arrows浅色 箭头样式arrowsshepherd-theme-arrows与light完全一致别名darkshepherd-theme-dark深色主题defaultshepherd-theme-default默认朴素样式squareshepherd-theme-square方形直角风格square-darkshepherd-theme-square-dark方形深色风格这些样式文件同样在 constants.py 的Shepherd类中定义播放前由activate_shepherd()一次性注入全部 6 套主题 CSS。四、添加导览步骤add_tour_step()参数详解创建导览对象后通过add_tour_step()逐个添加步骤。这是整个 Tours API 的核心方法其真实签名来自 base_case.pyself.add_tour_step( message, # 必填步骤要显示的文字内容 selectorNone, # 要锚定的元素 CSS 选择器不传则锚定到屏幕顶部 nameNone, # 多导览并存时的导览名 titleNone, # 消息上方的可选标题 themeNone, # 仅 Shepherd 有效本步骤的样式主题 alignmentNone, # 气泡锚定方向top / bottom / left / right durationNone, # 仅 Bootstrap 有效自动前进前的停留秒数 )4.1 各参数的行为细节message消息必填气泡内的主要说明文字。源码会在生成 JS 前对引号做转义处理__escape_quotes_if_needed。selectorCSS 选择器指定气泡要锚定的网页元素。不传时默认为html气泡会锚定到页面顶部对 DriverJS 会改为body、对 Hopscotch 会改为head并自动使用底部/居中定位。从源码看选择器会被自动处理[namexxx]形式的选择器会被规范化XPath 选择器会被 convert_to_css_selector 自动转换为 CSS 选择器。title标题可选显示在消息上方的加粗标题。theme主题仅 Shepherd可选值light/arrows、dark、default、square、square-dark不传时继承创建导览时设定的主题。alignment锚定方向可选top、bottom、left、right。默认值因库而异——从 add_tour_step 源码 可见Shepherd / Bootstrap / IntroJS 默认top而Hopscotch 与 DriverJS 默认bottom。duration停留时长仅 Bootstrap单位秒到达该步骤后自动前进。源码中会转换为毫秒写入 Bootstrap 的duration选项。name导览名仅在同时创建多段导览时需要用于区分不同导览。使用提示所有可选参数建议按关键字传参。虽然文档中常写作add_tour_step(message, css_selector, title, alignment, theme)的直观顺序但真实签名在selector与title之间还插入了name位置传参容易错位示例代码中全部采用关键字写法。4.2 未创建导览时的兜底行为源码 L13713-L13715 显示如果调用add_tour_step()时目标导览尚不存在会自动以themeintrojs创建一个 IntroJS 导览即默认库避免漏调用创建方法导致报错。五、播放与自动播放play_tour()self.play_tour(nameNone, interval0)interval为 0默认时导览为纯手动控制由用户点击气泡上的 Next / Skip 按钮前进传入大于 0 的秒数后导览会每隔该时长自动前进一个步骤自动播放。play_tour 源码 中的几个重要行为headless 跳过headless、headless2、xvfb模式下直接 return不播放。--interval命令行参数联动如果interval未传或为 0会自动读取 pytest 的--interval参数即self.interval这正是pytest maps_introjs_tour.py --interval1能自动播放的原因。最小间隔保护tour_helper 中 Shepherd / DriverJS / Hopscotch / IntroJS 的自动播放间隔若小于 0.5 秒会被强制设为 0.5 秒Bootstrap 小于 1 秒会被强制设为 1 秒。键盘导航播放期间支持快捷键控制——Shepherd 与 Hopscotch 支持PageUp/ArrowLeft后退、PageDown/ArrowRight前进DriverJS 与 IntroJS 支持PageUp/PageDown。首步元素校验播放前会对第一个步骤的选择器做存在性校验wait_for_element_present元素不存在会抛出 Tour Error: {selector} was not found! 异常避免导览在错误页面上空转。另外self.start_tour(nameNone, interval0)是play_tour()的完全等价别名源码位置。六、完整实战示例google_tour.py逐段拆解以下完整代码来自 google_tour.py与官方 ReadMe 一致演示了在一个测试方法内依次创建并播放 4 段不同库的导览from seleniumbase import BaseCase BaseCase.main(__name__, __file__, --uc) class MyTourClass(BaseCase): def test_google_tour(self): if not self.undetectable: self.get_new_driver(undetectableTrue) self.goto(https://google.com/ncr) self.click_if_visible(button:contains(Accept all)) self.wait_for_element([titleSearch]) self.hide_elements(iframe) # 用 ShepherdJS 库创建深色主题导览等价 self.create_shepherd_tour(themedark) self.create_tour(themedark) self.add_tour_step(Welcome to Google!, titleSeleniumBase Tours) self.add_tour_step(Type in your query here., [titleSearch]) self.play_tour() self.highlight_type([titleSearch], Google) self.wait_for_element([rolelistbox]) # 等待自动补全出现 # 用 ShepherdJS 库创建浅色主题导览等价 self.create_shepherd_tour(themelight) self.create_tour(themelight) self.add_tour_step(Then click to search., [valueGoogle Search]) self.add_tour_step(Or press [ENTER] after entry., [titleSearch]) self.play_tour() self.highlight_type([titleSearch], GitHub\n) self.ad_block() self.wait_for_element(#search) # 用 Bootstrap Tour 库创建导览3 秒自动播放 self.create_tour(themebootstrap) self.add_tour_step(3-second autoplay...) self.add_tour_step(Heres the next tour:) self.play_tour(interval3) # 每 3 秒自动前进 self.goto(https://www.google.com/maps/42.3591234,-71.0915634,15z) self.wait_for_element([nameq], timeout20) self.wait_for_element([aria-labelInteractive map], timeout20) self.wait_for_element([aria-labelZoom in], timeout20) self.wait_for_element([aria-labelZoom out]) self.wait_for_element([jsaction*minimap.main;]) self.sleep(0.5) # 用 IntroJS 库创建 Google Maps 导览 self.create_tour(themeintrojs) self.add_tour_step(Welcome to Google Maps, titleSeleniumBase Tour) self.add_tour_step( The location goes here., [nameq], titleSearch Box ) self.add_tour_step( Then click here to show it on the map., [aria-labelSearch], alignmentbottom, ) self.add_tour_step( Or click here to get driving directions., button[aria-labelDirections], alignmentbottom, ) self.add_tour_step( Use this button to switch to Satellite view., button[jsaction*minimap.main;], alignmentright, ) self.add_tour_step( Click here to zoom in., [aria-labelZoom in], alignmentleft, ) self.add_tour_step( Or click here to zoom out., [aria-labelZoom out], alignmentleft, ) if self.is_element_visible(button[jsaction*settings.open;]): self.add_tour_step( Use the Menu button to see more options., button[jsaction*settings.open;], alignmentright, ) elif self.is_element_visible(button[jsactionnavigationrail.more]): self.add_tour_step( Use the Menu button to see more options., button[jsactionnavigationrail.more], alignmentright, ) self.add_tour_step( Or click here to see more Google apps., [aria-labelGoogle apps], alignmentleft, ) self.add_tour_step( Thanks for using SeleniumBase Tours!, titleEnd of Guided Tour ) self.export_tour() # 默认导出文件名为 my_tour.js self.play_tour()这个示例值得注意的实战要点浏览器环境准备--uc参数 get_new_driver(undetectableTrue)启动隐身浏览器hide_elements(iframe)隐藏可能遮挡点击的 iframe。元素就绪保障每段导览前都用wait_for_element()等待锚定元素出现保证气泡能正确锚定。条件化步骤通过is_element_visible()判断页面实际渲染的控件Google Maps 的菜单按钮在不同版本/区域有不同选择器从而动态决定是否添加对应步骤——这是让导览跨环境稳定的关键技巧。先导出再播放最后一段导览先export_tour()导出 JS再play_tour()播放导出与播放互不干扰。七、导出导览为独立 JavaScript 文件export_tour()如果你想把导览从测试脚本中剥离出来独立用于任何网页可以调用导出方法源码位置self.export_tour() # 使用默认名 my_tour.js self.export_tour(nameNone, filenamemy_tour.js) self.export_tour(nameNone, filenamemy_tour.js, urlNone)参数说明name导览名仅在创建时使用了自定义名称时才需要filename导出 JS 文件名必须以.js结尾否则抛出异常见 tour_helper.py 的 export_toururl导览起始页 URL不传时默认使用当前页面地址self.get_current_url()导出文件开头会自动加入若当前地址不是该 URL 则跳转过去的逻辑。导出文件的行为特征来自 tour_helper.export_tour文件默认保存在仓库运行目录下的tours_exported/文件夹constants.Tours.EXPORTED_TOURS_FOLDER tours_exported见 constants.py保存成功会打印 [tours_exported/xxx.js] was saved!文件中会自动注入所需资源加载代码injectCSS/injectJS/injectStyle包括 jQuery 及各库的 CSS/JS并带资源加载轮询等待loadResources()/loadTour()因此导出的 JS 是自包含可运行的你可以在任意浏览器中打开目标网页把该 JS 文件内容粘贴到浏览器 Console 中执行即可脱离 SeleniumBase 单独播放这段导览——这也是官方文档明确推荐的使用方式。八、源码级原理Tours 是如何在页面上跑起来的8.1 三层调用链从源码结构看Tours 的运行时体系分为三层API 层seleniumbase/fixtures/base_case.pycreate_*_tour/add_tour_step/play_tour/export_tour/set_introjs_colors等全部公开方法负责把用户的 Python 调用转换成一段段 JS 代码字符串累积存放在self._tour_steps[name]列表中首元素为向导库的初始化模板后续元素为各步骤 JS。辅助层seleniumbase/core/tour_helper.pyactivate_*系列函数负责把对应库的 CSS/JS 通过add_css_link/add_js_link注入当前页面并轮询验证库是否加载成功加载验证脚本如var intro2 introJs();play_*系列函数把累积的 JS 拼接后driver.execute_script()执行并在 Python 侧用轮询循环驱动自动播放、监听键盘与处理步骤结束。资源层seleniumbase/fixtures/constants.py集中维护各库的 CDN 版本地址、jQuery 版本、IntroJS 主题色默认值等。8.2 步骤如何变成 JS以 IntroJS 为例create_introjs_tour()生成的是function startIntro(){ var intro introJs(); intro.setOptions({ steps: [随后每个add_tour_step()追加一段形如{element: 选择器, intro: 消息, position: top},的步骤对象最后由play_introjs_tour()拼上收尾代码并统一设置disableInteraction、overlayOpacity、keyboardNavigation等运行选项后一次性执行。其他 4 个库遵循完全相同的模板 步骤追加 拼接执行模式。8.3 IntroJS 主题色定制IntroJS 是默认库其按钮颜色可以通过以下方法定制源码位置self.set_introjs_colors(theme_color#367be5, hover_color#245ac0)两个参数都必须是#开头的十六进制颜色值3 位或 6 位均可不符合格式会抛出异常不传某参数时恢复默认值。默认颜色定义在 constants.py 的 TourColor 类主题色#367be5蓝色悬停色#245ac0深蓝并会在activate_introjs()注入页面时用于生成按钮样式。九、多导览并存与常见注意事项9.1name参数的使用时机所有 Tours 方法都接受可选的name参数默认值为default。当你同时创建多段导览如在同一个测试方法里交替构建 A、B 两段导览再分别播放时必须给不同导览起不同的名字否则后续步骤会追加到同一段导览上self.create_tour(themeintrojs, nametour_a) self.create_tour(themeshepherd, nametour_b) self.add_tour_step(A 的第一条提示, [titleSearch], nametour_a) self.add_tour_step(B 的第一条提示, button[aria-labelDirections], nametour_b) self.play_tour(nametour_a) self.play_tour(nametour_b)如果每段导览都是创建 → 加步骤 → 立即播放的顺序执行则可以完全省略name参数官方 ReadMe 的明确建议。9.2 实战注意事项汇总必须在有显示环境GUI下运行headless / xvfb 模式下play_tour()直接跳过元素必须先就绪锚定元素不存在时播放会抛出 Tour Error建议先wait_for_element()再添加步骤Shepherd 主题在步骤级可覆盖add_tour_step(..., themedark)可针对单个步骤覆盖导览全局主题Bootstrap 的步骤级自动前进用duration在add_tour_step(..., duration3)中指定秒数该步骤停留 3 秒后自动前进自动播放间隔存在下限Shepherd / DriverJS / Hopscotch / IntroJS 最小 0.5 秒Bootstrap 最小 1 秒小于下限的值会被自动抬升导览可用于演示与验收除了产品导览Tours 也适合在自动化测试中临时高亮正在操作的控件辅助调试与人工观摩。十、延伸阅读综合旗舰示例examples/tour_examples/google_tour.py自动播放示例examples/tour_examples/maps_introjs_tour.py各库独立示例examples/tour_examplesintrojs_google_tour.py、shepherd_google_tour.py、bootstrap_xkcd_tour.py、driverjs_maps_tour.py、hopscotch_google_tour.py、xkcd_tour.py、octocat_tour.pyTours API 源码seleniumbase/fixtures/base_case.pycreate_tour/add_tour_step/play_tour/export_tour/set_introjs_colors运行时辅助实现seleniumbase/core/tour_helper.pyactivate_*注入与play_*播放循环向导库资源与主题色常量seleniumbase/fixtures/constants.pyIntroJS/BootstrapTour/DriverJS/Hopscotch/Shepherd/TourColor掌握以上 API 与底层机制后你便可以在任意网站的自动化测试中自由组合 5 种交互式导览用于产品演示、新功能引导与测试过程可视化。【免费下载链接】SeleniumBaseAPIs for browser automation, testing, and bypassing bot-detection. Includes CDP Mode: A stealthy configuration for chromium that passes every bot detection test.项目地址: https://gitcode.com/GitHub_Trending/se/SeleniumBase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SeleniumBase 交互式产品导览（Tours）完全指南：基于 5 种 JavaScript 向导库的引导式网页演练
SeleniumBase 交互式产品导览Tours完全指南基于 5 种 JavaScript 向导库的引导式网页演练【免费下载链接】SeleniumBaseAPIs for browser automation, testing, and bypassing bot-detection. Includes CDP Mode: A stealthy configuration for chromium that passes every bot detection test.项目地址: https://gitcode.com/GitHub_Trending/se/SeleniumBaseSeleniumBase 的 Tours 功能允许测试脚本在任何网站上创建交互式产品导览walkthrough / guided tour通过高亮元素、气泡提示与逐步讲解引导用户熟悉页面功能。本指南以 examples/tour_examples/ReadMe.md 为核心完整覆盖五种向导库IntroJS、Bootstrap Tour、DriverJS、Shepherd、Hopscotch的创建、步骤添加、播放、自动播放与导出能力并深入 seleniumbase/fixtures/base_case.py 与 seleniumbase/core/tour_helper.py 的源码实现帮助读者快速上手编写自己的产品导览测试。一、什么是 SeleniumBase ToursSeleniumBase Tours 是一套内置在BaseCase类中的引导式导览能力它可以在任意网站上生成分步交互式讲解每一步都会在页面元素旁弹出一条带标题和说明文字的提示气泡并用高亮、遮罩等方式把用户注意力引导到指定控件上。整套体系封装了 5 个成熟的开源 JavaScript 向导库使用者无需接触任何前端代码只用几个 Python API 就能完成导览的构建与播放向导库用途特点IntroJS默认向导库轻量、易定制支持步骤编号、进度条与键盘导航Bootstrap Tour基于 Bootstrap 风格的导览支持步骤级自动前进duration参数DriverJS以高亮遮罩著称支持按钮文案与动画配置Shepherd主题最丰富提供 6 种内置主题样式HopscotchLinkedIn 出品的导览框架气泡样式简洁默认锚定在元素底部从源码看这 5 个库的 CSS/JS 资源地址统一在 seleniumbase/fixtures/constants.py 中维护IntroJS 5.1.0、Bootstrap Tour 0.12.0、DriverJS 0.9.8、Hopscotch 0.3.1、Shepherd 1.8.1、Tether 1.4.7、jQuery 3.7.1运行时由 seleniumbase/core/tour_helper.py 中的activate_*系列函数动态注入页面因此不需要修改被测网站的代码。二、快速开始运行内置示例仓库的 examples/tour_examples 目录下提供了 11 个可直接运行的示例脚本覆盖了全部 5 种向导库bootstrap_google_tour.py # Bootstrap Tour 版 Google 导览 bootstrap_xkcd_tour.py # Bootstrap Tour 版 xkcd 导览 driverjs_maps_tour.py # DriverJS 版 Google Maps 导览 google_tour.py # 综合演示 4 种库的旗舰示例 hopscotch_google_tour.py # Hopscotch 版 Google 导览 introjs_google_tour.py # IntroJS 版 Google 导览 maps_introjs_tour.py # IntroJS 版 Google Maps 导览可自动播放 octocat_tour.py # GitHub Octocat 导览 shepherd_google_tour.py # Shepherd 版 Google 导览 xkcd_tour.py # xkcd 导览示例一Google Maps 自动播放导览IntroJScd examples/tour_examples pytest maps_introjs_tour.py --interval1--interval1是 pytest 命令行参数含义是每 1 秒自动前进一个导览步骤。在 maps_introjs_tour.py 中脚本先用wait_for_element()等待地图页关键控件搜索框、缩放按钮、底图小组件就绪再创建 IntroJS 导览依次讲解搜索框、搜索按钮、路线、卫星视图、缩放与菜单等功能最后调用self.export_tour(filenamemaps_introjs_tour.js)导出导览并self.play_tour()播放。示例二综合导览同时演示 4 种向导库cd examples/tour_examples pytest google_tour.pygoogle_tour.py 是官方最完整的综合示例先使用--ucundetected 模式启动浏览器依次创建并播放 Shepherddark / light 两个主题、Bootstrap3 秒自动播放、IntroJSGoogle Maps 页共 4 段导览并在结束时调用self.export_tour()导出 JavaScript 文件。注意Tours 需要真实浏览器窗口才能演示效果。源码中 play_tour 会在 headless、headless2 或 xvfb 模式下直接跳过播放因此请使用带显示环境的浏览器运行。三、创建导览选择向导库与主题创建一段导览有两种等价写法使用create_tour(theme...)统一入口或使用各库专用的创建方法。3.1 统一入口create_tour()self.create_tour(nameNone, themeNone)是推荐入口。根据 base_case.py 中 create_tour 的实现theme的取值与内部路由规则如下theme取值实际创建的导览说明bootstrapBootstrap TourhopscotchHopscotchintro/introjsIntroJSdriver/driverjsDriverJSshepherd/light/arrowsShepherdlight/arrows 主题darkShepherddark 主题squareShepherdsquare 主题square-darkShepherdsquare-dark 主题defaultShepherddefault 主题不传 / 其他值IntroJS默认向导库3.2 各库专用创建方法每种库也提供了独立方法语义与统一入口完全等价self.create_shepherd_tour(nameNone, themeNone) # 等价 create_tour(themeshepherd) self.create_bootstrap_tour(nameNone) # 等价 create_tour(themebootstrap) self.create_introjs_tour(nameNone) # 等价 create_tour(themeintrojs) self.create_driverjs_tour(nameNone) # 等价 create_tour(themedriverjs) self.create_hopscotch_tour(nameNone) # 等价 create_tour(themehopscotch)3.3 Shepherd 主题详解Shepherd 是唯一支持主题定制的库。从 create_shepherd_tour 源码 可以看到主题会映射为 Shepherd 的 CSS class主题对应的 CSS class效果light默认shepherd-theme-arrows浅色 箭头样式arrowsshepherd-theme-arrows与light完全一致别名darkshepherd-theme-dark深色主题defaultshepherd-theme-default默认朴素样式squareshepherd-theme-square方形直角风格square-darkshepherd-theme-square-dark方形深色风格这些样式文件同样在 constants.py 的Shepherd类中定义播放前由activate_shepherd()一次性注入全部 6 套主题 CSS。四、添加导览步骤add_tour_step()参数详解创建导览对象后通过add_tour_step()逐个添加步骤。这是整个 Tours API 的核心方法其真实签名来自 base_case.pyself.add_tour_step( message, # 必填步骤要显示的文字内容 selectorNone, # 要锚定的元素 CSS 选择器不传则锚定到屏幕顶部 nameNone, # 多导览并存时的导览名 titleNone, # 消息上方的可选标题 themeNone, # 仅 Shepherd 有效本步骤的样式主题 alignmentNone, # 气泡锚定方向top / bottom / left / right durationNone, # 仅 Bootstrap 有效自动前进前的停留秒数 )4.1 各参数的行为细节message消息必填气泡内的主要说明文字。源码会在生成 JS 前对引号做转义处理__escape_quotes_if_needed。selectorCSS 选择器指定气泡要锚定的网页元素。不传时默认为html气泡会锚定到页面顶部对 DriverJS 会改为body、对 Hopscotch 会改为head并自动使用底部/居中定位。从源码看选择器会被自动处理[namexxx]形式的选择器会被规范化XPath 选择器会被 convert_to_css_selector 自动转换为 CSS 选择器。title标题可选显示在消息上方的加粗标题。theme主题仅 Shepherd可选值light/arrows、dark、default、square、square-dark不传时继承创建导览时设定的主题。alignment锚定方向可选top、bottom、left、right。默认值因库而异——从 add_tour_step 源码 可见Shepherd / Bootstrap / IntroJS 默认top而Hopscotch 与 DriverJS 默认bottom。duration停留时长仅 Bootstrap单位秒到达该步骤后自动前进。源码中会转换为毫秒写入 Bootstrap 的duration选项。name导览名仅在同时创建多段导览时需要用于区分不同导览。使用提示所有可选参数建议按关键字传参。虽然文档中常写作add_tour_step(message, css_selector, title, alignment, theme)的直观顺序但真实签名在selector与title之间还插入了name位置传参容易错位示例代码中全部采用关键字写法。4.2 未创建导览时的兜底行为源码 L13713-L13715 显示如果调用add_tour_step()时目标导览尚不存在会自动以themeintrojs创建一个 IntroJS 导览即默认库避免漏调用创建方法导致报错。五、播放与自动播放play_tour()self.play_tour(nameNone, interval0)interval为 0默认时导览为纯手动控制由用户点击气泡上的 Next / Skip 按钮前进传入大于 0 的秒数后导览会每隔该时长自动前进一个步骤自动播放。play_tour 源码 中的几个重要行为headless 跳过headless、headless2、xvfb模式下直接 return不播放。--interval命令行参数联动如果interval未传或为 0会自动读取 pytest 的--interval参数即self.interval这正是pytest maps_introjs_tour.py --interval1能自动播放的原因。最小间隔保护tour_helper 中 Shepherd / DriverJS / Hopscotch / IntroJS 的自动播放间隔若小于 0.5 秒会被强制设为 0.5 秒Bootstrap 小于 1 秒会被强制设为 1 秒。键盘导航播放期间支持快捷键控制——Shepherd 与 Hopscotch 支持PageUp/ArrowLeft后退、PageDown/ArrowRight前进DriverJS 与 IntroJS 支持PageUp/PageDown。首步元素校验播放前会对第一个步骤的选择器做存在性校验wait_for_element_present元素不存在会抛出 Tour Error: {selector} was not found! 异常避免导览在错误页面上空转。另外self.start_tour(nameNone, interval0)是play_tour()的完全等价别名源码位置。六、完整实战示例google_tour.py逐段拆解以下完整代码来自 google_tour.py与官方 ReadMe 一致演示了在一个测试方法内依次创建并播放 4 段不同库的导览from seleniumbase import BaseCase BaseCase.main(__name__, __file__, --uc) class MyTourClass(BaseCase): def test_google_tour(self): if not self.undetectable: self.get_new_driver(undetectableTrue) self.goto(https://google.com/ncr) self.click_if_visible(button:contains(Accept all)) self.wait_for_element([titleSearch]) self.hide_elements(iframe) # 用 ShepherdJS 库创建深色主题导览等价 self.create_shepherd_tour(themedark) self.create_tour(themedark) self.add_tour_step(Welcome to Google!, titleSeleniumBase Tours) self.add_tour_step(Type in your query here., [titleSearch]) self.play_tour() self.highlight_type([titleSearch], Google) self.wait_for_element([rolelistbox]) # 等待自动补全出现 # 用 ShepherdJS 库创建浅色主题导览等价 self.create_shepherd_tour(themelight) self.create_tour(themelight) self.add_tour_step(Then click to search., [valueGoogle Search]) self.add_tour_step(Or press [ENTER] after entry., [titleSearch]) self.play_tour() self.highlight_type([titleSearch], GitHub\n) self.ad_block() self.wait_for_element(#search) # 用 Bootstrap Tour 库创建导览3 秒自动播放 self.create_tour(themebootstrap) self.add_tour_step(3-second autoplay...) self.add_tour_step(Heres the next tour:) self.play_tour(interval3) # 每 3 秒自动前进 self.goto(https://www.google.com/maps/42.3591234,-71.0915634,15z) self.wait_for_element([nameq], timeout20) self.wait_for_element([aria-labelInteractive map], timeout20) self.wait_for_element([aria-labelZoom in], timeout20) self.wait_for_element([aria-labelZoom out]) self.wait_for_element([jsaction*minimap.main;]) self.sleep(0.5) # 用 IntroJS 库创建 Google Maps 导览 self.create_tour(themeintrojs) self.add_tour_step(Welcome to Google Maps, titleSeleniumBase Tour) self.add_tour_step( The location goes here., [nameq], titleSearch Box ) self.add_tour_step( Then click here to show it on the map., [aria-labelSearch], alignmentbottom, ) self.add_tour_step( Or click here to get driving directions., button[aria-labelDirections], alignmentbottom, ) self.add_tour_step( Use this button to switch to Satellite view., button[jsaction*minimap.main;], alignmentright, ) self.add_tour_step( Click here to zoom in., [aria-labelZoom in], alignmentleft, ) self.add_tour_step( Or click here to zoom out., [aria-labelZoom out], alignmentleft, ) if self.is_element_visible(button[jsaction*settings.open;]): self.add_tour_step( Use the Menu button to see more options., button[jsaction*settings.open;], alignmentright, ) elif self.is_element_visible(button[jsactionnavigationrail.more]): self.add_tour_step( Use the Menu button to see more options., button[jsactionnavigationrail.more], alignmentright, ) self.add_tour_step( Or click here to see more Google apps., [aria-labelGoogle apps], alignmentleft, ) self.add_tour_step( Thanks for using SeleniumBase Tours!, titleEnd of Guided Tour ) self.export_tour() # 默认导出文件名为 my_tour.js self.play_tour()这个示例值得注意的实战要点浏览器环境准备--uc参数 get_new_driver(undetectableTrue)启动隐身浏览器hide_elements(iframe)隐藏可能遮挡点击的 iframe。元素就绪保障每段导览前都用wait_for_element()等待锚定元素出现保证气泡能正确锚定。条件化步骤通过is_element_visible()判断页面实际渲染的控件Google Maps 的菜单按钮在不同版本/区域有不同选择器从而动态决定是否添加对应步骤——这是让导览跨环境稳定的关键技巧。先导出再播放最后一段导览先export_tour()导出 JS再play_tour()播放导出与播放互不干扰。七、导出导览为独立 JavaScript 文件export_tour()如果你想把导览从测试脚本中剥离出来独立用于任何网页可以调用导出方法源码位置self.export_tour() # 使用默认名 my_tour.js self.export_tour(nameNone, filenamemy_tour.js) self.export_tour(nameNone, filenamemy_tour.js, urlNone)参数说明name导览名仅在创建时使用了自定义名称时才需要filename导出 JS 文件名必须以.js结尾否则抛出异常见 tour_helper.py 的 export_toururl导览起始页 URL不传时默认使用当前页面地址self.get_current_url()导出文件开头会自动加入若当前地址不是该 URL 则跳转过去的逻辑。导出文件的行为特征来自 tour_helper.export_tour文件默认保存在仓库运行目录下的tours_exported/文件夹constants.Tours.EXPORTED_TOURS_FOLDER tours_exported见 constants.py保存成功会打印 [tours_exported/xxx.js] was saved!文件中会自动注入所需资源加载代码injectCSS/injectJS/injectStyle包括 jQuery 及各库的 CSS/JS并带资源加载轮询等待loadResources()/loadTour()因此导出的 JS 是自包含可运行的你可以在任意浏览器中打开目标网页把该 JS 文件内容粘贴到浏览器 Console 中执行即可脱离 SeleniumBase 单独播放这段导览——这也是官方文档明确推荐的使用方式。八、源码级原理Tours 是如何在页面上跑起来的8.1 三层调用链从源码结构看Tours 的运行时体系分为三层API 层seleniumbase/fixtures/base_case.pycreate_*_tour/add_tour_step/play_tour/export_tour/set_introjs_colors等全部公开方法负责把用户的 Python 调用转换成一段段 JS 代码字符串累积存放在self._tour_steps[name]列表中首元素为向导库的初始化模板后续元素为各步骤 JS。辅助层seleniumbase/core/tour_helper.pyactivate_*系列函数负责把对应库的 CSS/JS 通过add_css_link/add_js_link注入当前页面并轮询验证库是否加载成功加载验证脚本如var intro2 introJs();play_*系列函数把累积的 JS 拼接后driver.execute_script()执行并在 Python 侧用轮询循环驱动自动播放、监听键盘与处理步骤结束。资源层seleniumbase/fixtures/constants.py集中维护各库的 CDN 版本地址、jQuery 版本、IntroJS 主题色默认值等。8.2 步骤如何变成 JS以 IntroJS 为例create_introjs_tour()生成的是function startIntro(){ var intro introJs(); intro.setOptions({ steps: [随后每个add_tour_step()追加一段形如{element: 选择器, intro: 消息, position: top},的步骤对象最后由play_introjs_tour()拼上收尾代码并统一设置disableInteraction、overlayOpacity、keyboardNavigation等运行选项后一次性执行。其他 4 个库遵循完全相同的模板 步骤追加 拼接执行模式。8.3 IntroJS 主题色定制IntroJS 是默认库其按钮颜色可以通过以下方法定制源码位置self.set_introjs_colors(theme_color#367be5, hover_color#245ac0)两个参数都必须是#开头的十六进制颜色值3 位或 6 位均可不符合格式会抛出异常不传某参数时恢复默认值。默认颜色定义在 constants.py 的 TourColor 类主题色#367be5蓝色悬停色#245ac0深蓝并会在activate_introjs()注入页面时用于生成按钮样式。九、多导览并存与常见注意事项9.1name参数的使用时机所有 Tours 方法都接受可选的name参数默认值为default。当你同时创建多段导览如在同一个测试方法里交替构建 A、B 两段导览再分别播放时必须给不同导览起不同的名字否则后续步骤会追加到同一段导览上self.create_tour(themeintrojs, nametour_a) self.create_tour(themeshepherd, nametour_b) self.add_tour_step(A 的第一条提示, [titleSearch], nametour_a) self.add_tour_step(B 的第一条提示, button[aria-labelDirections], nametour_b) self.play_tour(nametour_a) self.play_tour(nametour_b)如果每段导览都是创建 → 加步骤 → 立即播放的顺序执行则可以完全省略name参数官方 ReadMe 的明确建议。9.2 实战注意事项汇总必须在有显示环境GUI下运行headless / xvfb 模式下play_tour()直接跳过元素必须先就绪锚定元素不存在时播放会抛出 Tour Error建议先wait_for_element()再添加步骤Shepherd 主题在步骤级可覆盖add_tour_step(..., themedark)可针对单个步骤覆盖导览全局主题Bootstrap 的步骤级自动前进用duration在add_tour_step(..., duration3)中指定秒数该步骤停留 3 秒后自动前进自动播放间隔存在下限Shepherd / DriverJS / Hopscotch / IntroJS 最小 0.5 秒Bootstrap 最小 1 秒小于下限的值会被自动抬升导览可用于演示与验收除了产品导览Tours 也适合在自动化测试中临时高亮正在操作的控件辅助调试与人工观摩。十、延伸阅读综合旗舰示例examples/tour_examples/google_tour.py自动播放示例examples/tour_examples/maps_introjs_tour.py各库独立示例examples/tour_examplesintrojs_google_tour.py、shepherd_google_tour.py、bootstrap_xkcd_tour.py、driverjs_maps_tour.py、hopscotch_google_tour.py、xkcd_tour.py、octocat_tour.pyTours API 源码seleniumbase/fixtures/base_case.pycreate_tour/add_tour_step/play_tour/export_tour/set_introjs_colors运行时辅助实现seleniumbase/core/tour_helper.pyactivate_*注入与play_*播放循环向导库资源与主题色常量seleniumbase/fixtures/constants.pyIntroJS/BootstrapTour/DriverJS/Hopscotch/Shepherd/TourColor掌握以上 API 与底层机制后你便可以在任意网站的自动化测试中自由组合 5 种交互式导览用于产品演示、新功能引导与测试过程可视化。【免费下载链接】SeleniumBaseAPIs for browser automation, testing, and bypassing bot-detection. Includes CDP Mode: A stealthy configuration for chromium that passes every bot detection test.项目地址: https://gitcode.com/GitHub_Trending/se/SeleniumBase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考