Files
paper-doc/backend/scripts/smoke_papers.py
T
govin e8e129221c frontend: centre the display formula, and let one be set left or right
Display formulas were sitting against the left margin with only their number at
the right, and the cause was a rule I had written myself: the paragraph's
stylesheet set `text-align: left` on `.katex`, which is the very element KaTeX
centres a display formula in. A well-meant attempt to keep a formula from being
justified apart had quietly overridden the centring, and it applied to every
formula in every paper — measured on a paragraph of known width, the formula's
midpoint sat 607px left of centre.

The override is gone; the rule carries only a font size now, and a comment says
why nothing about alignment belongs there.

`paper_sentence.formula_align` then adds the choice the writer asked for: a
display formula can be `center` (the default, and what a paper wants almost
always), `left` or `right`. It is per sentence rather than a template-field
setting — one paragraph legitimately mixes a centred equation with a
right-aligned continuation, and a field describes a heading, not a formula — and
the paragraph editor offers it only on rows that contain display maths, since
only those have a line of their own. The equation number is untouched: `\tag{1}`
prints against the right margin in all three cases, as every numbered style
does.

Measured in the browser on a 1276px paragraph: centred puts the formula 596px
from each edge, left puts it at 0, right puts it at 1225, and the tag is at the
right in every case. 56 paper checks (2 new: the round trip and the refusal of
an alignment the renderer does not know), 61 reference checks, 99 MCP checks,
`vue-tsc` and the build all pass.
2026-09-23 13:14:52 +08:00

509 lines
21 KiB
Python

"""End-to-end smoke test for the paper feature, against a running API.
Run it while the backend is up::
.venv/bin/python scripts/smoke_papers.py
It walks the whole writing loop — create a paper on a template, verify the
empty structure, fill a paragraph with sentences and citations, read the
document back, switch the template, and check that unmatched positions survive
under an unset heading — then deletes everything it created. Exits non-zero on
the first failed expectation, so it is usable as a gate.
"""
from __future__ import annotations
import json
import sys
import urllib.error
import urllib.parse
import urllib.request
from typing import Any
BASE = "http://127.0.0.1:8000/api"
_checks = 0
def call(method: str, path: str, body: Any = None, expect: int = 200) -> Any:
"""Perform one API call and assert its status code.
The path is quoted so a Chinese search keyword travels as UTF-8 percent
escapes instead of blowing up the ASCII request line.
"""
data = json.dumps(body).encode() if body is not None else None
url = BASE + urllib.parse.quote(path, safe="/?&=%")
request = urllib.request.Request(
url,
data=data,
method=method,
headers={"Content-Type": "application/json"},
)
try:
with urllib.request.urlopen(request, timeout=20) as response:
status = response.status
payload = response.read().decode()
except urllib.error.HTTPError as error:
status = error.code
payload = error.read().decode()
if status != expect:
raise AssertionError(f"{method} {path} -> {status}, expected {expect}: {payload}")
return json.loads(payload) if payload else None
def check(label: str, condition: bool, detail: str = "") -> None:
"""Assert one expectation and report it."""
global _checks
_checks += 1
if not condition:
raise AssertionError(f"{label}: {detail}")
print(f" ok {label}")
def main() -> int:
created_papers: list[int] = []
created_references: list[int] = []
try:
# The database may already hold real papers, so "nothing of ours is
# left" is measured against a baseline rather than against zero.
baseline = call("GET", "/papers")["total"]
print(f"0. baseline: {baseline} paper(s) already in the database")
print("1. pick two templates with different paragraph positions")
templates = call("GET", "/templates?page_size=50")["items"]
check("templates exist", len(templates) >= 2, f"got {len(templates)}")
wide = max(templates, key=lambda item: item["placement_count"])
narrow = min(templates, key=lambda item: item["placement_count"])
wide_full = call("GET", f"/templates/{wide['id']}")
narrow_full = call("GET", f"/templates/{narrow['id']}")
print(f" wide={wide['name']} ({wide['placement_count']}), narrow={narrow['name']}")
print("2. create a paper")
paper = call(
"POST",
"/papers",
{
"title": "冒烟测试论文",
"template_id": wide["id"],
"author": "测试作者",
"status": "writing",
"keywords": "关键词A,关键词B;关键词A",
"target_journal": "测试期刊",
},
expect=201,
)
created_papers.append(paper["id"])
check("keywords normalised", paper["keywords"] == "关键词A, 关键词B", paper["keywords"])
check(
"paragraph denominator counts the template",
paper["template_paragraph_count"]
== len({p["sort"] for p in wide_full["placements"]}),
str(paper["template_paragraph_count"]),
)
check("no sentences yet", paper["sentence_count"] == 0)
print("3. the empty paper already has its structure")
document = call("GET", f"/papers/{paper['id']}/document")
check(
"every template position is a paragraph",
len(document["paragraphs"]) == len({p["sort"] for p in wide_full["placements"]}),
str(len(document["paragraphs"])),
)
check("all paragraphs empty", all(not p["sentences"] for p in document["paragraphs"]))
check("all paragraphs matched", all(p["matched"] for p in document["paragraphs"]))
check("no citations", document["citations"] == [])
first_sort = document["paragraphs"][0]["paper_template_filed_sort"]
print("4. write a paragraph: two sentences, citations on both")
# A citation names real literature now, so the library needs an entry
# first — and a citation with no id at all stays legal.
reference = call(
"POST",
"/references",
{
"type": "journal-article",
"title": "用于验证引用链路的文献",
"container_title": "测试期刊",
"publication_year": 2024,
"authors": [{"name": "测试作者"}],
},
expect=201,
)
created_references.append(reference["id"])
document = call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{first_sort}",
{
"sentences": [
{
"content": " 第一句话,用于验证空白折叠。 ",
"citations": [
{"reference_id": reference["id"], "quote": "被引用的第一段内容"}
],
},
{
"content": "第二句话。",
"citations": [
{"reference_id": reference["id"], "quote": "引文甲"},
{"quote": "只有引用内容、暂时没有引用 id"},
],
},
]
},
)
paragraph = document["paragraphs"][0]
check("two sentences", len(paragraph["sentences"]) == 2, str(len(paragraph["sentences"])))
check("content trimmed", paragraph["sentences"][0]["content"] == "第一句话,用于验证空白折叠。")
check(
"sorts numbered from 1",
[s["sort"] for s in paragraph["sentences"]] == [1, 2],
str([s["sort"] for s in paragraph["sentences"]]),
)
check("citations numbered", [c["sort"] for c in paragraph["sentences"][1]["citations"]] == [1, 2])
check("three citations in the paper", len(document["citations"]) == 3)
check(
"a citation carries the number of its work, not of itself",
[c["index"] for c in document["citations"]] == [1, 1, 2],
str([c["index"] for c in document["citations"]]),
)
print("5. the 参考文献 list: one entry per work, in Springer's basic style")
check(
"two works — the article cited twice, and the unlinked quote",
len(document["references"]) == 2,
str(len(document["references"])),
)
first, second = document["references"]
check("both places that cite the article share its entry", len(first["citations"]) == 2)
check(
"the entry is a bibliography line, not the quote",
first["text"]
== "测试作者: 用于验证引用链路的文献. 测试期刊 (2024)",
first["text"],
)
check(
"what a complete entry still lacks is named",
first["missing"] == ["卷期页码"],
str(first["missing"]),
)
check("the unlinked quote is its own entry", second["reference_id"] is None)
check("and prints no fabricated entry", second["text"] == "", second["text"])
check("the style is reported", document["reference_style"] == "springer", document["reference_style"])
check("sentence template stamped", paragraph["sentences"][0]["template_id"] == wide["id"])
print("6. explicit sorts decide the order, not the order they were sent")
second_sort = document["paragraphs"][1]["paper_template_filed_sort"]
reordered = call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{second_sort}",
{
"sentences": [
{"sort": 20, "content": "排序在后的句子。"},
{"sort": 10, "content": "排序在前的句子。"},
]
},
)
second = next(
p
for p in reordered["paragraphs"]
if p["paper_template_filed_sort"] == second_sort
)
check(
"ascending sort wins over arrival order",
[s["content"] for s in second["sentences"]]
== ["排序在前的句子。", "排序在后的句子。"],
str([s["content"] for s in second["sentences"]]),
)
check("explicit sorts are stored as sent", [s["sort"] for s in second["sentences"]] == [10, 20])
# Clear it again so the counts asserted below stay meaningful.
call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{second_sort}",
{"sentences": []},
)
print("7. the seam between sentences depends on the language")
# Chinese needs nothing after 。; English needs a space, or two
# sentences print as `First.Second.`
mixed = call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{second_sort}",
{
"sentences": [
{"content": "第一句。"},
{"content": "第二句。"},
{"content": "This is English."},
{"content": "So is this."},
]
},
)
paragraph_mixed = next(
p
for p in mixed["paragraphs"]
if p["paper_template_filed_sort"] == second_sort
)
separators = [s["separator_before"] for s in paragraph_mixed["sentences"]]
check("no space between Chinese sentences", separators[:2] == ["", ""], str(separators))
check("a space before an English sentence", separators[2] == " ", str(separators))
check("a space between English sentences", separators[3] == " ", str(separators))
assembled = "".join(
s["separator_before"] + s["content"] for s in paragraph_mixed["sentences"]
)
check(
"the assembled paragraph reads correctly",
assembled == "第一句。第二句。 This is English. So is this.",
assembled,
)
check(
"the separator is not part of the stored text",
all(
not s["content"].startswith(" ") and not s["content"].endswith(" ")
for s in paragraph_mixed["sentences"]
),
)
# Clear it again so the counts asserted below stay meaningful.
call("PUT", f"/papers/{paper['id']}/paragraphs/{second_sort}", {"sentences": []})
print("8. a sentence can ask for a line break")
# The flag replaces the separator rather than adding to it: a break
# already separates the two, and a space as well would indent the new
# line by one blank.
broken = call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{second_sort}",
{
"sentences": [
{"content": "连排的第一句。"},
{"content": "另起一行的一句。", "line_break_before": True},
{"content": "English runs on.", "line_break_before": True},
]
},
)
paragraph_breaks = next(
p
for p in broken["paragraphs"]
if p["paper_template_filed_sort"] == second_sort
)
check(
"the flag is stored per sentence",
[s["line_break_before"] for s in paragraph_breaks["sentences"]]
== [False, True, True],
str([s["line_break_before"] for s in paragraph_breaks["sentences"]]),
)
check(
"it also survives a read back",
all(
s["line_break_before"] is False or s["separator_before"] == ""
for s in paragraph_breaks["sentences"]
),
)
call("PUT", f"/papers/{paper['id']}/paragraphs/{second_sort}", {"sentences": []})
print("9. a formula says how it is set on its line")
aligned = call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{second_sort}",
{
"sentences": [
{"content": "$$ E = mc^2 $$", "formula_align": "right"},
{"content": "$$ F = ma $$", "formula_align": "left"},
{"content": "$$ p = mv $$"},
]
},
)
paragraph_aligned = next(
p
for p in aligned["paragraphs"]
if p["paper_template_filed_sort"] == second_sort
)
check(
"alignment is stored per sentence, defaulting to centre",
[s["formula_align"] for s in paragraph_aligned["sentences"]]
== ["right", "left", "center"],
str([s["formula_align"] for s in paragraph_aligned["sentences"]]),
)
call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{second_sort}",
{"sentences": [{"content": "$$ x $$", "formula_align": "middle"}]},
expect=422,
)
check("an alignment the renderer does not know is refused", True)
call("PUT", f"/papers/{paper['id']}/paragraphs/{second_sort}", {"sentences": []})
print("10. reject a citation with no quote")
bad = call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{first_sort}",
{
"sentences": [
{
"content": "x",
"citations": [
{"reference_id": reference["id"], "quote": " "}
],
}
]
},
expect=422,
)
check("citation without content refused", "detail" in bad)
print("11. a sentence with no paragraph in the template survives a switch")
# A position neither template defines, so the check means the same
# thing before and after the switch below.
orphan_sort = (
max(
p["sort"]
for p in wide_full["placements"] + narrow_full["placements"]
)
+ 5
)
call(
"POST",
f"/papers/{paper['id']}/sentences",
{"paper_template_filed_sort": orphan_sort, "content": "新模板里没有这个位置的句子。"},
expect=201,
)
document = call("GET", f"/papers/{paper['id']}/document")
check(
"orphan position is rendered",
any(
p["paper_template_filed_sort"] == orphan_sort and not p["matched"]
for p in document["paragraphs"]
),
)
check("orphan heading has no name", next(
p for p in document["paragraphs"] if p["paper_template_filed_sort"] == orphan_sort
)["name"] is None)
print("12. switch the template")
switched = call("PATCH", f"/papers/{paper['id']}", {"template_id": narrow["id"]})
check("template changed", switched["template_id"] == narrow["id"])
document = call("GET", f"/papers/{paper['id']}/document")
matched = [p for p in document["paragraphs"] if p["matched"]]
unmatched = [p for p in document["paragraphs"] if not p["matched"]]
check(
"structure follows the new template",
len(matched) == len({p["sort"] for p in narrow_full["placements"]}),
str(len(matched)),
)
check("unmatched positions kept", len(unmatched) >= 1, str(len(unmatched)))
check(
"all sentences still present",
sum(len(p["sentences"]) for p in document["paragraphs"]) == 3,
)
check(
"positions ascend",
[p["paper_template_filed_sort"] for p in document["paragraphs"]]
== sorted(p["paper_template_filed_sort"] for p in document["paragraphs"]),
)
check(
"sentences re-stamped with the new template",
all(
s["template_id"] == narrow["id"]
for p in document["paragraphs"]
for s in p["sentences"]
),
)
print("13. move one paragraph onto another position")
document = call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{orphan_sort}",
{"sentences": [{"content": "搬到别处的一句。"}], "target_sort": first_sort},
)
target = next(
p for p in document["paragraphs"] if p["paper_template_filed_sort"] == first_sort
)
check("moved sentence appended after the existing ones", len(target["sentences"]) == 3)
check(
"source position gone",
all(p["paper_template_filed_sort"] != orphan_sort for p in document["paragraphs"]),
)
print("14. paper list reports progress")
listing = call("GET", f"/papers?keyword=冒烟&status=writing")
check("found by keyword and status", listing["total"] == 1, str(listing["total"]))
row = listing["items"][0]
check("paragraph count", row["paragraph_count"] == 1, str(row["paragraph_count"]))
check("sentence count", row["sentence_count"] == 3, str(row["sentence_count"]))
print("15. a template in use cannot be deleted")
conflict = call("DELETE", f"/templates/{narrow['id']}", expect=409)
check("template delete refused", "正被论文使用" in conflict["detail"], conflict["detail"])
print("16. single sentence edit and delete")
sentence_id = target["sentences"][0]["id"]
updated = call(
"PATCH",
f"/papers/{paper['id']}/sentences/{sentence_id}",
{"content": "改写后的一句话。", "sort": 5},
)
check("sentence updated", updated["content"] == "改写后的一句话。")
check("sentence sort updated", updated["sort"] == 5)
call("DELETE", f"/papers/{paper['id']}/sentences/{sentence_id}", expect=204)
document = call("GET", f"/papers/{paper['id']}/document")
check(
"sentence deleted",
sum(len(p["sentences"]) for p in document["paragraphs"]) == 2,
)
print("17. a paper with no template still works")
bare = call(
"POST",
"/papers",
{"title": "冒烟测试-无模板论文", "template_id": None, "status": "draft"},
expect=201,
)
created_papers.append(bare["id"])
empty_doc = call("GET", f"/papers/{bare['id']}/document")
check("no template means no structure", empty_doc["paragraphs"] == [])
call(
"POST",
f"/papers/{bare['id']}/sentences",
{"paper_template_filed_sort": 1, "content": "没有模板时写下的第一句。"},
expect=201,
)
bare_doc = call("GET", f"/papers/{bare['id']}/document")
check("content creates its own paragraph", len(bare_doc["paragraphs"]) == 1)
check("that paragraph has no heading", bare_doc["paragraphs"][0]["matched"] is False)
check("and the reader is warned", len(bare_doc["warnings"]) >= 1)
call("DELETE", f"/papers/{bare['id']}", expect=204)
created_papers.remove(bare["id"])
print("18. delete the paper")
call("DELETE", f"/papers/{paper['id']}", expect=204)
created_papers.clear()
for reference_id in created_references:
call("DELETE", f"/references/{reference_id}", expect=204)
created_references.clear()
check(
"gone from the list",
call("GET", "/papers")["total"] == baseline,
f"expected {baseline} paper(s) to remain",
)
print(f"\nall {_checks} checks passed")
return 0
finally:
# Never leave test rows behind, even on a failed expectation.
for reference_id in created_references:
try:
call("DELETE", f"/references/{reference_id}", expect=204)
except Exception as error: # noqa: BLE001 - cleanup must not mask the failure
print(f"cleanup of reference {reference_id} failed: {error}", file=sys.stderr)
for paper_id in created_papers:
try:
call("DELETE", f"/papers/{paper_id}", expect=204)
print(f"cleaned up paper {paper_id}")
except Exception as error: # noqa: BLE001 - cleanup must not mask the failure
print(f"cleanup of paper {paper_id} failed: {error}", file=sys.stderr)
if __name__ == "__main__":
sys.exit(main())