本文介绍如何在 Spring Boot 集成测试中正确获取控制器返回的 Excel 文件响应体（byte[]），使用 mvc-requester 库完成断言与文件内容比对。
本文介绍如何在 spring boot 集成测试中正确获取控制器返回的 excel 文件响应体（`byte[]`），使用 `mvc-requester` 库完成断言与文件内容比对。
在基于 Spring MVC 的 Web 应用中，导出 Excel 报表（如 .xlsx）通常采用流式响应（HttpServletResponse）方式，而非返回 ResponseEntity<resource></resource> 或 MultipartFile —— 这意味着 测试时无法直接通过 .returnAs(MultipartFile.class) 解析响应，因为服务端并未以 multipart/form-data 格式返回文件，而是以原始二进制流（application/vnd.openxmlformats-officedocument.spreadsheetml.sheet）写入响应体。
正确的测试路径是：跳过反序列化尝试，直接提取原始响应字节流。mvc-requester（v0.4+）提供了 .returnResponse() 方法，可获取 MockHttpServletResponse 实例，进而调用 .getContentAsByteArray() 安全提取完整 Excel 文件内容：
@Test
void shouldDownloadComplaintsFullReportAsExcel() throws Exception {
byte[] excelBytes = MvcRequester.on(mockMvc)
.to("/api/reports/complaints/full")
.get()
.doExpect(status().isOk())
.doExpect(header().contentType(MediaType.parseMediaType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")))
.returnResponse()
.getContentAsByteArray();
// ✅ 验证非空 & 基础格式（如 ZIP 签名，因 .xlsx 是 ZIP 容器）
assertThat(excelBytes).isNotEmpty();
assertThat(excelBytes).startsWith(0x50, 0x4B, 0x03, 0x04); // ZIP magic bytes
// ✅ 可选：与预生成基准文件进行二进制比对（需确保时间无关字段已标准化）
byte[] expectedBytes = Files.readAllBytes(Paths.get("src/test/resources/expected-report.xlsx"));
assertThat(excelBytes).isEqualTo(expectedBytes);
// ✅ 可选：用 Apache POI 解析校验内容逻辑（需添加 poi-ooxml 依赖）
try (Workbook wb = new XSSFWorkbook(new ByteArrayInputStream(excelBytes))) {
Sheet sheet = wb.getSheetAt(0);
assertThat(sheet.getPhysicalNumberOfRows()).isGreaterThan(0);
assertThat(sheet.getRow(0).getCell(0).getStringCellValue()).isEqualTo("Complaint ID");
}
}
⚠️ 注意事项：
-
勿误用
.returnAs(...)：MultipartFile、File、InputStream等类型仅适用于 请求上传 场景，不适用于 响应下载；强行调用会导致ClassCastException或NullPointerException（如截图所示）。 -
依赖版本关键：必须使用
com.jupiter-tools:mvc-requester:0.4（或更高稳定版），旧版或自定义封装可能缺少.returnResponse()方法。 -
响应头断言不可少：务必通过
.doExpect(header().contentType(...))验证 MIME 类型，确保后端正确设置了Content-Type和Content-Disposition（如需）。 -
时间敏感文件名处理：示例中文件名含
LocalDateTime.now()，测试时建议在控制器中注入Clock或使用@MockBean替换时间源，避免每次生成不同文件名影响断言稳定性。
通过上述方式，你即可在测试中完整捕获 Excel 响应、执行二进制一致性校验、结构化解析与业务字段验证，构建健壮可靠的文件导出测试链。
