troynguyen/cypress-included-pdf-package

Docker镜像文档：cypress-ocr-pdf-tools

概述

本镜像基于cypress/included构建，扩展集成了多种PDF处理工具（pdftk、poppler-utils、ghostscript）和OCR识别工具（tesseract-ocr），旨在提供一站式的端到端测试环境，支持在测试流程中直接处理PDF文件或执行OCR文字识别任务。

核心功能与特性

1. Cypress测试环境

• 内置完整的cypress/included环境，支持直接运行Cypress测试脚本，无需额外安装Cypress依赖。

2. PDF处理工具集

• pdftk：支持PDF文件合并、拆分、旋转、加密/解密等基础操作。
• poppler-utils：提供pdftotext（PDF转文本）、pdfinfo（PDF元信息提取）、pdfimages（PDF图像提取）等工具。
• ghostscript：支持PDF压缩、格式转换（如PDF转PostScript）及高级渲染处理。

3. OCR文字识别

• tesseract-ocr：开源OCR引擎，支持从图像或PDF中提取文字，默认包含英文语言包，可通过配置扩展其他语言支持。

使用场景

• 电商/***系统：测试订单、发票等PDF文件的生成正确性（内容验证、格式检查）。
• 文档管理系统：验证导出PDF的文本内容、图像提取及元数据准确性。
• 表单系统：对包含扫描件的PDF进行OCR识别，测试文字提取结果与预期值匹配。
• 自动化测试：在端到端测试流程中，直接调用工具处理PDF/OCR，无需依赖外部服务。

使用方法

1. 拉取镜像

bash
docker pull docker.xuanyuan.run/[镜像名称]  # 请替换为实际镜像地址

2. 基本运行命令

bash
docker run -it --rm \
  -v $(pwd)/cypress:/e2e/cypress \
  -v $(pwd)/cypress.config.js:/e2e/cypress.config.js \
  [镜像名称] \
  npx cypress run

• -v $(pwd)/cypress:/e2e/cypress：挂载本地Cypress测试用例目录到容器内。
• -v $(pwd)/cypress.config.js:/e2e/cypress.config.js：挂载Cypress配置文件。
• 命令末尾可添加Cypress参数（如--spec cypress/e2e/pdf-test.cy.js指定测试文件）。

3. 测试中调用工具示例

在Cypress测试脚本中，可通过cy.exec()调用镜像内置工具：

示例1：提取PDF文本并验证内容

javascript
// cypress/e2e/pdf-validation.cy.js
it('验证PDF导出内容', () => {
  // 假设测试流程中生成了目标PDF并保存到/tmp/test.pdf
  cy.exec('pdftotext /tmp/test.pdf -', { log: true }).then(result => {
    expect(result.stdout).to.include('订单编号: 20240101001');  // 验证文本内容
  });
});

示例2：OCR识别图像中的文字

javascript
// cypress/e2e/ocr-test.cy.js
it('OCR识别验证', () => {
  // 假设测试流程中下载了包含文字的图像/tmp/sample.png
  cy.exec('tesseract /tmp/sample.png stdout', { log: true }).then(result => {
    expect(result.stdout.trim()).to.equal('测试OCR识别内容');  // 验证OCR结果
  });
});

4. Docker Compose配置示例

yaml
# docker-compose.yml
version: '3.8'
services:
  cypress-test:
    image: docker.xuanyuan.run/[镜像名称]
    volumes:
      - ./cypress:/e2e/cypress
      - ./cypress.config.js:/e2e/cypress.config.js
      - ./test-assets:/e2e/test-assets  # 挂载测试所需的PDF/图像资源
    command: npx cypress run --spec cypress/e2e/pdf-ocr-test.cy.js

配置说明

环境变量

• **CYPRESS_*：支持所有Cypress原生环境变量（如CYPRESS_BASE_URL`指定测试基础URL）。
• TESSDATA_PREFIX：指定tesseract语言包路径（默认/usr/share/tesseract-ocr/5/tessdata/）。

扩展配置

• 安装额外tesseract语言包：通过apt-get安装（需以root用户运行），例如安装中文语言包： CODE_TOKEN_5
• 自定义工具路径：如需修改工具默认配置，可通过挂载配置文件（如/etc/ghostscript/下的配置）实现。

注意事项

• 容器默认工作目录为/e2e，建议将测试脚本及资源挂载到此目录。
• 处理大型PDF或高分辨率图像时，建议为容器分配足够内存（通过--memory参数）。
• OCR识别 accuracy 受图像质量影响，测试中建议使用标准化的图像/PDF样本。