kkFileView E2E 自动化测试实战Playwright 驱动的预览冒烟、安全回归与性能门禁体系【免费下载链接】kkFileViewUniversal File Online Preview Project based on Spring-Boot项目地址: https://gitcode.com/GitHub_Trending/kk/kkFileView本文基于 kkFileView 仓库中tests/e2e目录的 E2E MVP 文档及配套实现展开完整讲解如何用 Playwright 对在线预览服务搭建一套端到端自动化测试涵盖 17 类文件的预览冒烟检查、Office/压缩包测试夹具fixture的自动生成、SSRF 信任主机安全回归验证以及可配置阈值的预览性能门禁。读完本文你可以完整复现“构建 jar → 生成夹具 → 启动双服务 → 跑通全部 E2E 用例”的本地与 CI 流程并理解每条用例背后的服务端实现证据。一、测试体系总览这套 E2E 覆盖了什么tests/e2e目录是 kkFileView 首个 MVP 级的端到端自动化测试套件见 README。按照文档声明它的覆盖面包括基础预览冒烟检查针对常见文件类型 txt/md/json/xml/csv/html/pngOffice Phase-2 冒烟检查docx/xlsx/pptx压缩包冒烟检查zip/tar/tgz/7z/rar基础端点可达性检查首页/安全回归检查针对被屏蔽的内网地址段10.*的主机访问拦截分别验证/onlinePreview与/getCorsFile两个入口基础性能冒烟检查txt/docx/xlsx 预览响应时间阈值可配置CI 一体化命令通过npm run test:ci单命令完成“一次夹具生成 全部用例执行”。从源码结构看整个目录组织为三层路径职责specs/preview-smoke.spec.ts预览冒烟 安全回归用例21 个 testspecs/perf-smoke.spec.ts性能冒烟用例3 个 testscripts/generate-fixtures.mjs生成文本/图片/PDF/压缩包等夹具scripts/generate-office-fixtures.py生成 docx/xlsx/pptx 夹具fixtures/夹具文件目录由本地 HTTP 服务对外提供playwright.config.ts、package.jsonPlaywright 配置与 npm 脚本入口这套体系的核心设计是双服务架构kkFileView 本身负责预览默认http://127.0.0.1:8012另起一个 Python HTTP 文件服务器http://127.0.0.1:18080承载所有测试夹具用例通过“夹具 URL 做 Base64 编码”后请求/onlinePreview接口完成端到端验证。二、环境准备与本地运行流程五步以下内容完整继承自 tests/e2e/README.md并补充了每一步的作用说明。2.1 第一步构建服务端 jarmvn -q -pl server -DskipTests package在仓库根目录执行-pl server表示只构建 server 子模块并跳过单元测试。产物是server/target/kkFileView-*.jar后续第 4 步会用到。2.2 第二步安装依赖与浏览器cd tests/e2e npm install npx playwright install --with-deps chromium pip3 install -r requirements.txtnpm install安装 Playwright 测试框架。从 package.json 看唯一的开发依赖是playwright/test^1.55.0说明该套件刻意保持轻量。npx playwright install --with-deps chromium下载 Chromium 及系统依赖。pip3 install -r requirements.txt安装 Office 夹具生成所需的 Python 库。requirements.txt 中版本被精确锁定python-docx1.1.2 openpyxl3.1.5 python-pptx1.0.2版本锁定保证了夹具生成脚本在不同机器上的行为可复现。前置条件文档明确提示压缩包夹具的生成要求python3、zip、7z或回退方案bsdtar在 PATH 中可用。2.3 第三步生成夹具并启动夹具服务器cd /path/to/kkFileView npm run gen:all cd tests/e2e/fixtures python3 -m http.server 18080npm run gen:all实际等价于npm run gen:fixtures npm run gen:office即依次执行 Node 脚本与 Python 脚本生成全部测试文件随后用 Python 标准库把tests/e2e/fixtures目录暴露为 18080 端口的静态 HTTP 服务。2.4 第四步启动 kkFileView另一个终端JAR_PATH$(ls server/target/kkFileView-*.jar | head -n 1) KK_TRUST_HOST* KK_NOT_TRUST_HOST10.*,172.16.*,192.168.* java -jar $JAR_PATH这里的环境变量设置是理解整条测试链路的关键后文第五节会结合服务端源码解释其必要性白名单*放行 127.0.0.1 的夹具地址同时黑名单显式拦截10.*等内网网段从而让两条 SSRF 安全回归用例能够稳定复现“拦截”行为。2.5 第五步运行测试cd tests/e2e KK_BASE_URLhttp://127.0.0.1:8012 FIXTURE_BASE_URLhttp://127.0.0.1:18080 npm test两个环境变量分别指向 kkFileView 服务与夹具服务器对应 playwright.config.ts 中的baseURL: process.env.KK_BASE_URL || http://127.0.0.1:8012以及各 spec 文件顶部的FIXTURE_BASE_URL || http://127.0.0.1:18080兜底默认值。2.6 可选的三类运行模式文档还给出了三条快捷命令# smoke only自包含自动先生成夹具 npm run test:smoke # perf smoke自包含默认阈值 15000ms E2E_MAX_PREVIEW_MS15000 npm run test:perf # CI 风格合并运行单次夹具生成 E2E_MAX_PREVIEW_MS20000 npm run test:ci对照 package.json 的 scripts 定义可以看出其“自包含”的实现方式pretest: npm run gen:all, test:smoke: playwright test specs/preview-smoke.spec.ts, pretest:smoke: npm run gen:all, test:perf: playwright test specs/perf-smoke.spec.ts, pretest:perf: npm run gen:all, test:ci: npm run gen:all playwright test specs/preview-smoke.spec.ts specs/perf-smoke.spec.tsnpm 会在test:smoke/test:perf执行前自动触发对应的pre*钩子先生成夹具而test:ci则是只生成一次夹具、连续跑两个 spec避免了重复生成开销——这正是文档所说“CI 合并运行命令”的落地。三、测试夹具的生成策略夹具fixture是 E2E 测试可复现的基石。本套件的策略是“能程序化生成的全部程序化生成二进制文件随仓库提交”。3.1 Node 脚本文本、图片、PDF 与压缩包generate-fixtures.mjs 一次性产出纯文本类sample.txt、sample.md、sample.json、sample.xml、sample.csv、sample.html内容都是几行的固定模板例如sample.csv为name,value\nkkFileView,1\ne2e,1\n保证断言文案稳定图片sample.png是一个 1×1 像素的 PNG由脚本内置的 Base64 常量直接解码写入最小合法 PDFsample.pdf由脚本内联的 PDF 1.1 文本Catalog/Pages/Page 三个对象 一段绘制 “kkFileView e2e pdf” 文本的内容流直接写入无需 PDF 工具链压缩包五件套统一封装一个名为inner.txt的内部文件内容kkFileView archive inner file供用例断言“压缩包内文件可见”夹具生成方式sample.zipzip -X -q -r-X去除扩展属性增强可复现性sample.tar/sample.tgz内嵌 Python 片段用tarfile以 USTAR 格式生成mtime9466848002000-01-01、uid/gid 固定为 0tgz 再套一层mtime0的 gzip——刻意做成确定性归档sample.7z优先7z a -bd -y -mtcoff -mtaoff -mtmoff关闭注释/属性/时间戳7z不存在ENOENT时回退bsdtar -a -cfsample.rar不生成脚本检测到缺失时直接抛错提示从 git 恢复git checkout -- tests/e2e/fixtures/sample.rar最后一条值得注意Rar 格式没有可靠的开源命令行写入工具因此 fixtures/sample.rar 作为二进制文件直接提交在仓库中脚本只校验其存在性。同理视频夹具 sample.mp4 也是随仓库提供的。3.2 Python 脚本Office 三件套generate-office-fixtures.py 用三个第三方库生成 Office 夹具与 requirements.txt 中的锁定版本一一对应python-docx→sample.docx一级标题 “kkFileView E2E” 一段正文openpyxl→sample.xlsxSheet1 两行两列name/value 表头与一条数据python-pptx→sample.pptx使用 layout 1 添加一页幻灯片写入标题与正文占位符。内容都很小这符合冒烟测试的定位——验证“转换管线跑得通”而不是渲染保真度。四、预览冒烟与安全回归用例preview-smoke.spec.tspreview-smoke.spec.ts 共 21 个 test是整个套件的核心。4.1 前置校验beforeAll 探测 17 个夹具用例执行前beforeAll会用独立的playwrightRequest上下文逐个 GET${fixtureBase}/name覆盖 17 个必需夹具txt/md/json/xml/csv/html/png/pdf/docx/xlsx/pptx/zip/tar/tgz/7z/rar/mp4/dxf任何一个 404 都会以fixture missing or unavailable明确报失败——把“夹具缺失”与“预览失败”两类问题区分开。4.2 请求构造Base64 编码的 URL 参数function b64(v: string): string { return Buffer.from(v).toString(base64); } async function openPreview(request: any, fileUrl: string) { const encoded encodeURIComponent(b64(fileUrl)); return request.get(/onlinePreview?url${encoded}); }预览请求的形态是/onlinePreview?urlURL编码的Base64(文件地址)这与 kkFileView 服务端的 URL 参数约定一致安全用例中的/getCorsFile?urlPath...同理服务端实现见 OnlinePreviewController 的getCorsFile方法。4.3 关键机制异步转换轮询waitForFinalOffice/PDF 类文件的预览是异步转换流程首次请求可能返回“转换中”占位页。为此定义了openPreviewBody(request, fileUrl, waitForFinal)普通文件txt/png/zip 等只请求一次需要转换的文件pdf/docx/xlsx/pptx/dxf传waitForFinal true若响应体包含“文件转换中”则以 1500ms 间隔最多轮询 10 次约 15 秒窗口直到拿到最终预览页。这是一个非常实用的细节——它把“转换耗时”与“转换失败”解耦转换慢只会拉长等待不会导致断言误报。4.4 断言策略候选文案 OR 匹配function expectAnyContains(body: string, candidates: string[], label: string) { const hit candidates.some(candidate body.includes(candidate)); expect(hit, ${label} should contain one of: ${candidates.join(, )}).toBeTruthy(); }每类文件给出一组候选关键词命中其一即通过。全部 21 条用例及其断言要点如下#用例夹具断言候选任一命中轮询01首页可达/状态码 500否02txt 预览sample.txt普通文本预览 / sample.txt否03markdown 预览sample.mdMarkdown / sample.md / markdown否04json 预览sample.jsonJSON / sample.json / json否05xml 预览sample.xmlXML / sample.xml / xml否06csv 预览sample.csvCSV / sample.csv / csv否07html 预览sample.htmlHTML / sample.html / html否08png 预览sample.png图片预览 / sample.png /img否09pdf 预览sample.pdf图片预览 / sample.pdf / pdf是10docx 预览sample.docx图片预览 / sample.docx / office是11xlsx 预览sample.xlsxsample.xlsx预览 / xlsx / office是12pptx 预览sample.pptxppt / sample.pptx / office是13zip 预览sample.zip压缩包预览 / sample.zip / inner.txt否14tar 预览sample.tar压缩包预览 / sample.tar / inner.txt否15tgz 预览sample.tgz压缩包预览 / sample.tgz / inner.txt /系统暂不支持在线预览否167z 预览sample.7z压缩包预览 / sample.7z / inner.txt否17rar 预览sample.rar压缩包预览 / sample.rar / inner.txt否18mp4 预览sample.mp4播放器 /video/ sample.mp4否19CAD dxf 预览text.dxftext.dxf /svg/ svg是20安全onlinePreview 拦截 10.xhttp://10.1.2.3/a.pdf响应体包含“不受信任”—21安全getCorsFile 拦截 10.xhttp://10.1.2.3/a.pdf响应体包含“不受信任”—两处体现工程审慎的设计tgz 用例的宽容断言——候选中特意加入“系统暂不支持在线预览”即 tgz 无论走通预览还是走“不支持”的兜底提示都算通过。这符合文档将其定位为 smoke check 的性质防止环境差异如解压库能力导致用例误红安全用例直接打真实内网地址http://10.1.2.3/a.pdf——由于黑名单匹配发生在请求发起前见第五节根本不会真的发起对外请求断言只检查拦截提示页文案。五、安全回归的服务端实现证据用例 20/21 为什么断言“不受信任”这背后是 kkFileView 的 SSRF 防护机制可以在源码中找到完整对应关系。过滤器注册WebConfig.java 将TrustHostFilter注册到四个入口/onlinePreview、/picturesPreview、/getCorsFile、/addTask——E2E 恰好覆盖了其中用户最可能直接触达的两个。配置来源application.properties 中trust.host ${KK_TRUST_HOST:default} not.trust.host ${KK_NOT_TRUST_HOST:default}配置注释明确提示为防止 SSRF 强烈建议配置信任白名单不配置则默认拒绝所有外部文件预览请求。这也解释了 README 第四步启动命令必须显式传KK_TRUST_HOST*否则默认值default不在任何白名单内127.0.0.1 的夹具会被全部拦截冒烟用例集体失败。拦截逻辑TrustHostFilter.java 的判定顺序为主机名为空 → 拒绝黑名单not trust优先命中10.*等模式即拒绝——这正是用例 20/21 中10.1.2.3被拦截的原因白名单检查含*则全放行README 中KK_TRUST_HOST*的语义否则按模式匹配两者都未配置时默认拒绝所有主机防 SSRF 的兜底。其模式匹配matchHostPattern支持精确匹配、通配符192.168.*、IPv4 CIDR192.168.0.0/16三种方式其中 IP 匹配走 parseLiteralIpv4源码注释写明“仅解析字面量 IPv4 地址不做 DNS 解析防止 DNS rebinding/TOCTOU 风险”。被拦截请求会收到 403 及含${current_host}占位替换后的 notTrustHost.html 页面文案含“不受信任的站点”与用例断言的“不受信任”字符串精确对应。六、性能冒烟可配置阈值的响应时间门禁perf-smoke.spec.ts 对 txt/docx/xlsx 各做一次计时请求const DEFAULT_MAX_MS 15000; const envMaxMs Number(process.env.E2E_MAX_PREVIEW_MS); const maxMs Number.isFinite(envMaxMs) envMaxMs 1 ? Math.floor(envMaxMs) : DEFAULT_MAX_MS;阈值默认15000ms可用环境变量E2E_MAX_PREVIEW_MS覆盖非法值或小于 1 时回退默认值每个用例断言status 200且elapsed maxMsbeforeAll同样先探测sample.txt/docx/xlsx三个夹具可达。阈值可配是性能门禁类用例的标准做法本地快速验证用默认 15sCI 机器资源紧张时按 README 示例放宽到E2E_MAX_PREVIEW_MS20000。注意它度量的是“首响应时间”而非转换完成时间因此对 docx/xlsx 这类异步转换文件它验证的是管线入口的响应延迟而非完整转换耗时——这与文档中“basic performance smoke checks”的定位一致。七、Playwright 配置要点playwright.config.ts 全文如下每行配置都有明确的运维含义import { defineConfig } from playwright/test; export default defineConfig({ testDir: ./specs, timeout: 30_000, // 单用例 30s 超时 expect: { timeout: 10_000 }, // 断言等待 10s retries: process.env.CI ? 1 : 0, // 仅 CI 失败重试 1 次 reporter: [[list], [html, { outputFolder: playwright-report, open: never }]], use: { baseURL: process.env.KK_BASE_URL || http://127.0.0.1:8012, trace: on-first-retry, // 首次重试时采集 trace }, });baseURL由KK_BASE_URL注入使同一套 spec 可指向任意环境retries: CI ? 1 : 0与trace: on-first-retry组合保证 CI 上的偶发抖动可复现且留有 trace 证据本地开发则快速失败双 reporter 输出终端列表与playwright-report静态 HTML 报告open: never适合无头 CI 环境。结合第四、六节可知整套 E2E 在 CI 上的最小落地命令就是 README 给出的E2E_MAX_PREVIEW_MS20000 npm run test:ci它完成一次夹具生成并串联执行两个 spec配合CItrue时自动生效的重试策略即文档所述“CI combined run command”。八、小结与扩展方向tests/e2e这套 MVP 展示了 kkFileView 质量保障体系中非常实用的一层用程序化生成的确定性夹具消除环境噪声用双服务 环境变量注入实现本地/CI 双形态运行用OR 候选断言与转换轮询保证冒烟用例的稳定性再用两条 SSRF 拦截用例把安全边界TrustHostFilter 的黑名单优先、默认拒绝、字面量 IP 匹配纳入回归验证最后以E2E_MAX_PREVIEW_MS提供可调的性能门禁。对于仓库贡献者这条链路也给出了一个可复制的模板新增文件类型预览能力时只需在 generate-fixtures.mjs或 Office 脚本中补充夹具、在 preview-smoke.spec.ts 中加一条带候选文案的断言用例即可获得端到端的持续验证。【免费下载链接】kkFileViewUniversal File Online Preview Project based on Spring-Boot项目地址: https://gitcode.com/GitHub_Trending/kk/kkFileView创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考