震惊！！！Excel版用例转Word版用例工具诞生！！！

一、工具地址

gitee地址：https://gitee.com/HLiucyH/excel-to-word

注意：源码文件夹中有可直接运行的exe工具程序！！！

二、用户手册

1、功能介绍

本工具旨在解决编写Word版用例比较繁琐的问题，使用该工具后可以轻松将Excel的用例转为Word用例。

同时，该工具设计趋向于更大的通用性。使用者可以自定义模板、替换的内容、位置等，在较大程度上可以实现不修改业务源代码的情况下自定义生成模板，按需转换成想要的word文档。

工具主要原理：

1. 将（源文件）Excel表格的数据读入到程序中，形成一行行的数据（如：用例）信息。
2. 根据该行Excel表格中定义的功能级别（如：一级功能、二级功能等），生成对应的标题级别。
3. 然后再根据word版本的表格模板（如：用例表格模板），拼接到想要拼接的word文档中。
4. 重复步骤2和3，直到所有数据行都生成、替换完。

最后生成、拼接的内容格式大致如下：

一级功能（标题内容）
    |
    `————————二级功能（标题内容）
    |        表格（如：用例）
    |
    `————————二级功能（标题内容）
    |        表格（如：用例）
    |
    `————————二级功能（标题内容）
                  |
                  `————————三级功能（标题内容）
                  |         表格（如：用例）
                  |
                  `————————三级功能（标题内容）
                           表格（如：用例）

2、使用步骤

以下我们以默认的用例生成来讲解如何使用，使用时主要涉及到“测试用例.xlsx”、“用例表格模板.docx”、“输出模板.docx”三个文件，文件均需放在与“ExcelToWordUtils.py”源代码文件放在同一目录下。

程序就是将“测试用例.xlsx”里面的每行数据、“用例表格模板.docx”拼接至“输出模板.docx”文件中，最后生成“用例结果-xxx。xlsx”。

如下是文件与程序对应的配置关系图，可以帮助理解对应关系。

具体使用步骤如下：

• 步骤一：填写“测试用例.xlsx”
  • 蓝框（功能级别）：
    • 功能级别分别为“一级功能”、“二级功能”、…、“八级功能”，其中默认对应的标题级别分别为2、3、…、9级标题。
    • 下图测试用例填写示例中，只到了三级功能，如果实际项目中功能级别到四、五级功能等，插入列并按要求命名成“四级功能”、“五级功能”等。
    • 功能级别的内容填写方面，需要进行合并；同时如果当前用例没有三级标题（如示例图的第一、二行），则填写“/”即可。
  • 红框（用例相关标题）：红框的标题，需要与“用例表格模板.docx”的“${xxx}”一一对应上，在内容填写上按自己需要填写即可。
  • 绿框（存在截图）：
    • 如果用例相关信息中存在截图时，如实际结果中需要加入截图，则需以“#截图-xxx图片名称#”的格式为图片做占位标记。
    • 同时在源代码同一目录下的“Images”下存放对用的图片，如默认示例的“截图-功能-xxx-001.jpg”

• 步骤二：“用例表格模板.docx”示例，需要确保“${xxx}”与“测试用例.xlsx”的标题行对应上（默认的示例已对应上）。具体图示如下：

• 步骤三：填写完“测试用例.xlsx”文件后，并确保用例表格模板正确。即可执行程序“ExcelToWordUtils.py”的main方法。
• 步骤四：程序执行完成后，即会生成以“测试结果”为前缀的用例结果文件。

注意：

• 如果是用打包后的exe程序来执行，需要在与exe程序同一目录下填充好“测试用例.xlsx”、“用例表格模板.docx”、“输出模板.docx”、“Images文件夹”，然后双击程序运行即可。
• 打包exe程序的方法，请参考“二、开发指引”的“3、打包指引”。

3、模板示例

该项目已准备两个已打包好的示例，分别在“示例/CNAS示例”、“示例/默认模板示例”路径下。这两个示例的文件中，只有“测试用例.xlsx”和“用例表格模板.docx”两个文件是根据特定表格设计的，不用修改源码等其他内容。

运行时推荐双击“【运行推荐】执行程序.bat”，此方式运行时如果程序报错的话，可以查看到错误日志。如果双击ExcelToWordUtils.exe运行方式，程序执行完后会直接自动关闭窗口，看不到执行结果。

三、开发指引

1、开发环境&版本

建议版本与下述保持一致，以避免出现不必要的错误：

• python版本：python-3.8.6-amd64
• 第三方依赖：
  • word文档读写：python-docx/0.8.11
  • excel读：xlrd/1.2.0
  • python-docx可能用到的依赖：lxml/4.8.0

2、整体代码逻辑介绍

注：为方便将程序打包成exe可执行文件，本项目将所有代码放置一个文件中。

本项目共设计三个类以及一个程序运行入口：

• Const类：该类主要用作全局配置。具体配置作用如下：
  • functionPointLevel配置：对应“测试用例.xlsx”的功能级别的标题。此处可修改，但需要与“测试用例.xlsx”的功能级别的标题对应上。
  • titleLevel配置：对应“测试用例.xlsx”的功能级别的标题等级。如“一级功能”对应的文档标题等级是“2级标题”，以此类推。
  • excelFileName配置：对应“测试用例.xlsx”文件名称。此处配置修改时，对应的原数据文件名称也要修改成一致。
  • sheetName配置：对应“测试用例.xlsx”文件中的sheet页名称。此处配置修改时，也需对应修改成一致。
  • wordTableTemplateFileName配置：与“用例表格模板.docx”表格模板对对应上。此处配置修改时，也需对应修改成一致。
  • exportTemplateFileName配置：与“输出模板.docx”对应上。此处配置修改时，也需对应修改成一致。
  • exportNamePrefix配置：输出结果文件的前缀名称。
  • imagesPath配置：如果数据源excel文件中有截图，则需将截图放在该文件夹下。此处配置修改时，“Images”文件夹名称也要对应修改成一致。
  • picWidth配置：如果数据源excel文件中有截图，此处修改控制图片宽度，以免图片太大而溢出。
• Transfer类：该类主要用于将Excel数据转换成Word，会生成文章结构及对应的用例表格。具体方面介绍如下：
  • doTransfer方法：遍历Excel数据行，按数据行信息，分别调用addTitle方法、addTable方法、replaceTableContent方法等，逐行生成标题、拼接表格、替换表格内容。
  • addTitle方法：在文档中添加一个文档标题。
  • addTable方法：从表格模板中复制一份到待输出的文档中。
  • replaceTableContent方法：替换表格的“${xxx}”内容。
  • addPicture方法：为段落、表格添加图片。
• ExcelHelper类：
  • read_by_list方法：读取用例表格，保存至list中，其中每个list的元素是list列表。
  • read_by_dict方法：读取用例表格，保存到list中，其中每个list的元素为dict字典。
• main程序入口，执行流程大致如下：
  • 步骤一：读取Excel表格数据、Excel表格的表头
  • 步骤二：读取待拼接的输出模板文档
  • 步骤三：读取表格模板
  • 步骤四：执行转换操作
  • 步骤五：将转换结果输出

Const配置类与相关文件的对应关系图：

3、打包指引

如果需要将该程序打包成exe程序。则需安装“pyinstaller”打包工具。

PyInstaller可以将Python代码和依赖项打包成一个独立的可执行文件，无需安装Python解释器或其他依赖项。

以下是在PyCharm中使用PyInstaller打包Python项目成exe文件的一般步骤：

1. 在PyCharm中打开你的Python项目。

2. 确保你已经安装了PyInstaller。你可以通过在终端中运行以下命令来安装PyInstaller：

   pip install pyinstaller
   

3. 打开PyCharm的终端。在底部工具栏上，你可以找到终端按钮。

4. 在终端中，导航到你的项目目录。可以使用cd命令来切换目录。

5. 运行以下命令来使用PyInstaller打包你的项目：

   pyinstaller --onefile ExcelToWordUtils.py
   

   这个命令将在项目目录中创建一个dist文件夹，并在其中生成可执行的exe文件。

6. 打包完成后，你可以在dist文件夹中找到生成的exe文件。这个exe文件可以在没有Python解释器的环境中运行。

请注意，PyInstaller会将你的Python代码和依赖项打包成一个独立的exe文件，但在某些情况下可能会遇到一些问题。例如，如果你的项目依赖于一些动态加载的资源文件或第三方库，可能需要进行额外的配置。你可以查阅PyInstaller的文档以获取更多详细信息和解决方案。

另外，打包成exe文件可能会因操作系统的不同而有所差异。如果你希望在不同的操作系统上打包exe文件，可以考虑使用PyInstaller的--platform选项来指定目标平台。例如，如果你希望在Windows上打包exe文件，可以使用以下命令：

pyinstaller --onefile --platform=win32 ExcelToWordUtils.py

这将生成一个适用于Windows平台的exe文件。

4、待完善内容

目前为初始版本，实现了基本功能，未对配置、内容等填写进行填写错误提示、检查等。同时，在自定义模板内容时，容易出错。

四、常见问题

1、表格模板单元格样式问题

表格模板的单元格需保持“正文”的样式，有些表格的单元格可能是“列表”等样式，这样在生成时，可能会影响到标题序号的自动生成。

2、生成后标题无自动序号

本程序的默认示例中的“输出模板.docx”的标题样式，已经是预设好了样式，程序生成标题时就会自动生成序号。

如果你自定义的输出模板没有给标题预设样式，需要先给输出模板的标题预设自动标题的样式。