代码分析摘要
- 函数 chunk_text(text, max_len, overlap=0) 将字符串按最大长度 max_len 切分为若干块，并在相邻块之间保留 overlap 个字符的重叠。
- 输入约束：
- text 必须为 str，否则抛 TypeError('text must be str')
- 参数窗口合法性：max_len >= 1，overlap >= 0 且 overlap < max_len，否则抛 ValueError('invalid window params')
- 行为：
- 空字符串在参数合法时返回 []
- 每个分块通过 strip 去除首尾空白
- 最后一个块必定覆盖到原串末尾（end == n）
- 步进为 i = end - overlap
- 关键边界点：
- 参数边界：max_len=1，overlap=0，overlap=max_len-1
- 文本边界：空串、长度小于/等于/刚超过 max_len
- 重叠正确性：相邻块的重叠段一致
- 去空白影响：块可能为空字符串；内部空白需保留
断言设计思路
- 参数校验断言：确保异常类型和消息正确；覆盖非法和合法边界值。
- 返回值断言：空文本返回 []；短文本返回单块；各块长度不超过 max_len。
- 重叠一致性断言：对于无空白干扰的文本，验证相邻块的重叠段相等。
- 极限重叠断言：overlap=max_len-1 应产生滑动窗口步长为 1 的预期块序列。
- 去空白断言：验证 strip 行为仅移除首尾空白，不改变内部空白；允许出现空块。
- 计数公式断言：在无首尾空白干扰时，验证块数量与理论值一致，防止循环或步进错误。
- 类型与长度性质断言：所有块为 str，长度均 <= max_len，作为回归的基本不变量。
生成的断言代码
import math
import pytest
def chunk_text(text, max_len, overlap=0):
'''
Split text into chunks of length <= max_len with character overlap.
- Return list of strings
- Empty text -> []
- Raise ValueError if max_len < 1 or overlap < 0 or overlap >= max_len
- Preserve all characters; trim whitespace around each chunk
'''
if not isinstance(text, str):
raise TypeError('text must be str')
if max_len < 1 or overlap < 0 or overlap >= max_len:
raise ValueError('invalid window params')
if not text:
return []
chunks = []
i = 0
n = len(text)
while i < n:
end = min(i + max_len, n)
chunk = text[i:end].strip()
chunks.append(chunk)
if end == n:
break
i = end - overlap
return chunks
def expected_chunk_count(n, max_len, overlap):
"""用于断言块数量的理论值（不考虑 strip 带来的空块/空白变化）。"""
if n == 0:
return 0
if n <= max_len:
return 1
step = max_len - overlap
return math.ceil((n - max_len) / step) + 1
def test_param_validation():
# 类型错误
with pytest.raises(TypeError, match='text must be str'):
chunk_text(123, 5)
with pytest.raises(TypeError, match='text must be str'):
chunk_text(None, 5)
# 窗口参数非法
with pytest.raises(ValueError, match='invalid window params'):
chunk_text("abc", 0) # max_len < 1
with pytest.raises(ValueError, match='invalid window params'):
chunk_text("abc", 5, -1) # overlap < 0
with pytest.raises(ValueError, match='invalid window params'):
chunk_text("abc", 5, 5) # overlap >= max_len
# 合法边界值
assert chunk_text("a", 1, 0) == ["a"], "max_len=1, overlap=0 应产生单块"
assert chunk_text("", 1, 0) == [], "空文本且参数合法应返回空列表"
def test_empty_text_returns_empty():
assert chunk_text("", 5) == [], "空文本返回空列表（参数合法）"
def test_short_and_exact_length_text():
# 短于 max_len -> 单块
assert chunk_text("abc", 5, 0) == ["abc"], "短文本应返回单块，且内容被 strip"
# 等于 max_len -> 单块
assert chunk_text("abcde", 5, 0) == ["abcde"], "文本长度等于 max_len 应返回单块"
# 带首尾空白的短文本 -> strip 生效
assert chunk_text(" abc ", 10, 0) == ["abc"], "块应移除首尾空白"
def test_basic_chunking_no_overlap():
text = "abcdefgh"
max_len = 3
overlap = 0
chunks = chunk_text(text, max_len, overlap)
assert chunks == ["abc", "def", "gh"], "无重叠时分块应按固定步长推进"
assert all(isinstance(c, str) for c in chunks), "所有块类型应为 str"
assert all(len(c) <= max_len for c in chunks), "所有块长度应 <= max_len"
# 最后一块应包含文本的最后一个非空白字符
assert chunks[-1][-1] == text[-1], "最后一块应包含原文本末尾字符"
def test_chunking_with_overlap():
text = "abcdefgh"
max_len = 4
overlap = 2
chunks = chunk_text(text, max_len, overlap)
assert chunks == ["abcd", "cdef", "efgh"], "重叠窗口应产生预期序列"
# 重叠一致性：相邻块交叠部分相等
for i in range(len(chunks) - 1):
tail = chunks[i][-overlap:]
head = chunks[i + 1][:overlap]
assert tail == head, f"第{i}块尾部与第{i+1}块头部的重叠应一致"
assert all(len(c) <= max_len for c in chunks), "所有块长度应 <= max_len"
def test_maximal_overlap_step_one():
text = "abcdef"
max_len = 3
overlap = 2 # 极限重叠：步长为 1
chunks = chunk_text(text, max_len, overlap)
assert chunks == ["abc", "bcd", "cde", "def"], "极限重叠应产生滑动窗口步长为 1 的序列"
# 重叠一致性
for i in range(len(chunks) - 1):
assert chunks[i][-2:] == chunks[i + 1][:2], "相邻块的两个字符重叠应一致"
def test_trim_behavior_and_possible_empty_chunks():
text = " a b c "
max_len = 3
overlap = 1
chunks = chunk_text(text, max_len, overlap)
# 预期分块（分析 strip 后的结果）
assert chunks == ["a", "a b", "b", "c", ""], "strip 应移除首尾空白但保留内部空白，尾部可能产生空块"
# 所有块应已 strip（无首尾空白）
for c in chunks:
assert c == c.strip(), "每个块应无首尾空白"
# 内部空白保留（中间块应包含空格）
assert "a b" in chunks, "内部空白应被保留"
# 长度约束
assert all(len(c) <= max_len for c in chunks), "所有块长度应 <= max_len"
def test_expected_chunk_count_formula():
text = "abcdefghij" # 长度 10，末尾非空白，便于计数断言
max_len = 4
overlap = 1
chunks = chunk_text(text, max_len, overlap)
expected = expected_chunk_count(len(text), max_len, overlap)
assert len(chunks) == expected, "块数量应符合理论计数公式（无首尾空白干扰场景）"
def test_type_and_length_properties_regression():
# 多样文本场景下的基本性质断言（回归用）
samples = [
(" hello world ", 5, 2),
("xyz", 2, 1),
(" " * 8, 3, 1), # 全空白文本，strip 后可能出现空块
("123456789", 9, 8), # overlap = max_len-1
]
for text, max_len, overlap in samples:
chunks = chunk_text(text, max_len, overlap)
assert all(isinstance(c, str) for c in chunks), "所有块类型应为 str"
assert all(len(c) <= max_len for c in chunks), "所有块长度应 <= max_len"
# 空文本的特殊回归
if text == "":
assert chunks == [], "空文本应返回空列表"
断言说明
- test_param_validation
- 验证 TypeError/ValueError 的触发条件与错误消息，覆盖非法边界：max_len<1、overlap<0、overlap>=max_len。
- 验证合法边界：max_len=1、overlap=0。
- test_empty_text_returns_empty
- test_short_and_exact_length_text
- 文本长度短于/等于 max_len 时应返回单块；且块内容被 strip（去首尾空白）。
- test_basic_chunking_no_overlap
- 无重叠情况下的分块序列正确；类型与长度不变量；最后一块包含原文本末尾字符。
- test_chunking_with_overlap
- 有重叠的基本序列正确；相邻块的重叠段一致，确保步进 i = end - overlap 正确。
- test_maximal_overlap_step_one
- 覆盖极限重叠 overlap=max_len-1，验证产生步长为 1 的滑动窗口序列以及重叠一致性。
- test_trim_behavior_and_possible_empty_chunks
- 验证 strip 行为：仅移除首尾空白，内部空白保留；可能产生空字符串块；所有块长度满足约束。
- test_expected_chunk_count_formula
- 在无首尾空白干扰的文本上，块数量符合理论公式，防止循环或步进错误的回归。
- test_type_and_length_properties_regression
- 多样样本的基本不变量断言（类型、长度），提升回归覆盖度；覆盖特殊参数组合如 overlap=max_len-1 和全空白文本。
使用建议
- 测试框架建议使用 pytest，将上述代码保存为 tests/test_chunk_text.py；运行 pytest 即可。
- 若函数定义已存在于项目模块中，建议在测试文件中从目标模块导入 chunk_text，避免重复定义。
- 在增加回归样例时：
- 优先选择能体现边界的输入（空串、极限重叠、长度恰好等于/略大于 max_len）。
- 若需验证重叠内容一致性，选择不含首尾空白的文本以避免 strip 干扰。
- 断言信息尽量明确，出现失败时能快速定位是参数校验、分块逻辑、重叠、或 strip 行为的问题。
- 禁止在断言中包含副作用代码（如修改全局状态）；如需计算期望值，可使用纯函数（如 expected_chunk_count）。
