"""End-to-end check of the reference library, against a running API. Run it while the backend is up:: .venv/bin/python scripts/smoke_references.py It walks the whole loop the library exists for — make the labels, add literature and tag it, find it again by author, by type and by tag, link a sentence to it, look the citation up from the reference side, be refused when deleting something in use, then clean up — and exits non-zero on the first failed expectation. Everything it creates is deleted, including the throwaway paper it cites from. The order of the first two steps is the point of the tag library rather than an accident of the script: **tags are made first and applied second**. A reference is created *with* tag ids, never with tag names, so a typo cannot invent a label — which is what step 4 checks. """ 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.""" 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_references: list[int] = [] created_papers: list[int] = [] created_tags: list[int] = [] try: print("1. the labels come first: create two tags") survey = call( "POST", "/reference-tags", {"name": " 综述 ", "color": "rgb(64, 158, 255)", "note": "综述性文献"}, expect=201, ) created_tags.append(survey["id"]) check("a name is trimmed to one spelling", survey["name"] == "综述", survey["name"]) check( "a colour is canonicalised", survey["color"] == "#409EFF", survey["color"], ) check("nothing carries it yet", survey["reference_count"] == 0) must_read = call( "POST", "/reference-tags", {"name": "必读", "color": "#f56c6c"}, expect=201, ) created_tags.append(must_read["id"]) check("the second tag is stored", must_read["name"] == "必读") print("2. a tag name is unique, and only a real colour is accepted") duplicate = call( "POST", "/reference-tags", {"name": "综述"}, expect=409 ) check("the refusal names the label", "综述" in duplicate["detail"], duplicate["detail"]) call("POST", "/reference-tags", {"name": "怪颜色", "color": "blue"}, expect=422) call("POST", "/reference-tags", {"name": " "}, expect=422) check("a blank name and a non-colour are refused", True) print("3. add an article with four authors and both tags") article = call( "POST", "/references", { "type": "journal-article", "title": "技术惯性与冲量的耦合机制", "subtitle": "基于科学与技术融合网络的实证分析", "title_translated": "Coupling inertia and impulse in technology evolution", "container_title": "Technological Forecasting and Social Change", "container_title_short": "Technol. Forecast. Soc. Change", "volume": "198", "issue": "3", "pages": "122-141", "publication_year": 2024, "publication_month": 5, "doi": "https://doi.org/10.1016/j.techfore.2024.123456", "language": "zh", "keywords": "技术演化, 惯性, 冲量", "tag_ids": [survey["id"], must_read["id"]], "authors": [ {"name": "张三", "family_name": "张", "given_name": "三"}, {"name": "李四"}, {"name": "Wang Wu", "family_name": "Wang", "given_name": "Wu"}, {"name": "世界卫生组织", "role": "compiler"}, ], }, expect=201, ) created_references.append(article["id"]) check("the DOI lost its URL prefix", article["doi"] == "10.1016/j.techfore.2024.123456", article["doi"]) check("four contributors stored", len(article["authors"]) == 4) check( "they keep the order they were sent in", [a["name"] for a in article["authors"]] == ["张三", "李四", "Wang Wu", "世界卫生组织"], str([a["name"] for a in article["authors"]]), ) check( "sort is numbered from 1", [a["sort"] for a in article["authors"]] == [1, 2, 3, 4], str([a["sort"] for a in article["authors"]]), ) check("roles survive", article["authors"][3]["role"] == "compiler") check("partial date kept as sent", article["publication_year"] == 2024 and article["publication_month"] == 5) check("no day invented", article["publication_day"] is None) check("not cited yet", article["citation_count"] == 0) check( "both tags are on the row", sorted(tag["name"] for tag in article["tags"]) == ["必读", "综述"], str(article["tags"]), ) print("4. a tag that does not exist is refused by name, not invented") missing_tag = call( "POST", "/references", {"title": "引用了不存在的标签", "type": "book", "tag_ids": [999999]}, expect=400, ) check("the refusal names the id", "999999" in missing_tag["detail"], missing_tag["detail"]) orphan = call("GET", "/references?keyword=引用了不存在的标签") check("nothing was stored half-labelled", orphan["total"] == 0, str(orphan["total"])) print("5. add a patent, which needs a country and a number") patent = call( "POST", "/references", { "type": "patent", "title": "一种基于多层聚类的人工智能技术识别方法", "patent_country": "中国", "patent_number": "CN114000000A", "publication_year": 2023, "tag_ids": [must_read["id"]], "authors": [{"name": "张三"}], }, expect=201, ) created_references.append(patent["id"]) check("patent stored", patent["type"] == "patent" and patent["patent_number"] == "CN114000000A") check( "tagging works on create for more than one entry", [tag["name"] for tag in patent["tags"]] == ["必读"], str(patent["tags"]), ) print("6. a webpage without a URL is refused") call( "POST", "/references", {"type": "web-page", "title": "某网页"}, expect=422, ) check("web page without URL refused", True) print("7. a bad type and a missing title are refused") call("POST", "/references", {"type": "blog-post", "title": "x"}, expect=422) call("POST", "/references", {"title": " "}, expect=422) call( "POST", "/references", {"title": "没有标签的书", "authors": [{"name": "甲"}], "type": "book"}, expect=201, ) probe = call("GET", "/references?keyword=没有标签的书") created_references.append(probe["items"][0]["id"]) check("a book needs nothing else", probe["total"] == 1) check("and may carry no tags at all", probe["items"][0]["tags"] == []) print("8. find it again: by author, by type, by year, by tag") by_author = call("GET", "/references?keyword=Wang") check("search matches an author name", by_author["total"] == 1, str(by_author["total"])) check( "the row prints an author line", by_author["items"][0]["authors_line"].startswith("张三, 李四, Wang Wu"), by_author["items"][0]["authors_line"], ) by_type = call("GET", "/references?type=patent") check("filter by type", by_type["total"] == 1, str(by_type["total"])) by_year = call("GET", "/references?year=2024") check("filter by year", by_year["total"] == 1, str(by_year["total"])) uncited = call("GET", "/references?cited=false") check("filter by not-yet-cited", uncited["total"] == len(created_references)) by_tag = call("GET", f"/references?tag={must_read['id']}") check("filter by tag", by_tag["total"] == 2, str(by_tag["total"])) both = call( "GET", f"/references?tag={survey['id']}&tag={must_read['id']}", ) check( "two tags narrow to the rows carrying both", both["total"] == 1 and both["items"][0]["id"] == article["id"], str(both["total"]), ) print("9. the tag table counts what carries each label") tags = call("GET", "/reference-tags") counts = {tag["name"]: tag["reference_count"] for tag in tags["items"]} check("two labels in the library", tags["total"] == 2, str(tags["total"])) check("the shared label counts two rows", counts["必读"] == 2, str(counts)) check("the other counts one", counts["综述"] == 1, str(counts)) found = call("GET", "/reference-tags?keyword=综述") check("tags are searchable by name", found["total"] == 1, str(found["total"])) print("10. renaming a label follows it everywhere it is used") renamed = call( "PATCH", f"/reference-tags/{survey['id']}", {"name": "综述文章", "note": "综述与述评"}, ) check("the label is renamed", renamed["name"] == "综述文章") after = call("GET", f"/references/{article['id']}") check( "the reference prints the new name", sorted(tag["name"] for tag in after["tags"]) == ["必读", "综述文章"], str(after["tags"]), ) taken = call( "PATCH", f"/reference-tags/{survey['id']}", {"name": "必读"}, expect=409 ) check("renaming onto a taken name is refused", "必读" in taken["detail"], taken["detail"]) print("11. edit it: replace the contributor list, a field and its tags") updated = call( "PATCH", f"/references/{article['id']}", { "pages": "122-145", "tag_ids": [must_read["id"]], "authors": [ {"name": "张三", "family_name": "张", "given_name": "三"}, {"name": "李四"}, ], }, ) check("pages updated", updated["pages"] == "122-145") check("author list replaced wholesale", len(updated["authors"]) == 2) check( "tag list replaced wholesale too", [tag["name"] for tag in updated["tags"]] == ["必读"], str(updated["tags"]), ) check("untouched fields kept", updated["container_title"] == "Technological Forecasting and Social Change") cleared = call("PATCH", f"/references/{patent['id']}", {"tag_ids": None}) check( "omitting tags leaves them alone", [tag["name"] for tag in cleared["tags"]] == ["必读"], str(cleared["tags"]), ) print("12. cite it from a sentence") templates = call("GET", "/templates?page_size=1")["items"] paper = call( "POST", "/papers", {"title": "参考文献冒烟测试论文", "template_id": templates[0]["id"]}, expect=201, ) created_papers.append(paper["id"]) outline = call("GET", f"/templates/{templates[0]['id']}") position = outline["placements"][0]["sort"] call( "PUT", f"/papers/{paper['id']}/paragraphs/{position}", { "sentences": [ { "content": "技术惯性约束了同时具有高冲量的可能。", "citations": [ {"reference_id": article["id"], "quote": "高惯性技术几乎不可能同时具有高冲量。"} ], } ] }, ) check("a citation to a real reference is accepted", True) missing = call( "PUT", f"/papers/{paper['id']}/paragraphs/{position}", {"sentences": [{"content": "x", "citations": [{"reference_id": 999999, "quote": "y"}]}]}, expect=400, ) check("a citation to nothing is refused by name", "999999" in missing["detail"], missing["detail"]) print("13. the reverse lookup: which sentences use this article?") citations = call("GET", f"/references/{article['id']}/citations") check("one citation found", len(citations) == 1, str(len(citations))) check("it names the sentence", "技术惯性约束" in citations[0]["sentence_content"]) check("and the paper", citations[0]["paper_id"] == paper["id"]) check("and the paragraph heading", citations[0]["paragraph_name"] is not None, str(citations[0])) cited = call("GET", "/references?cited=true") check("the cited filter now finds it", cited["total"] == 1, str(cited["total"])) print("14. a cited reference cannot be deleted; an uncited one can") conflict = call("DELETE", f"/references/{article['id']}", expect=409) check("refusal explains itself", "正被论文引用" in conflict["detail"], conflict["detail"]) call("DELETE", f"/references/{patent['id']}", expect=204) created_references.remove(patent["id"]) check("an uncited reference deletes cleanly", True) print("15. deleting a tag unlabels the literature instead of deleting it") call("DELETE", f"/reference-tags/{must_read['id']}", expect=204) created_tags.remove(must_read["id"]) survivor = call("GET", f"/references/{article['id']}") check("the reference is still there", survivor["title"] == article["title"]) check("and has lost that label", survivor["tags"] == [], str(survivor["tags"])) left = call("GET", f"/references?tag={survey['id']}") check( "the other label no longer matches anything", left["total"] == 0, str(left["total"]), ) print("16. clean up") 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() for tag_id in created_tags: call("DELETE", f"/reference-tags/{tag_id}", expect=204) created_tags.clear() remaining = call("GET", "/references") check("nothing of ours is left", remaining["total"] == 0, str(remaining["total"])) check( "and no labels either", call("GET", "/reference-tags")["total"] == 0, str(call("GET", "/reference-tags")["total"]), ) print(f"\nall {_checks} checks passed") return 0 finally: for paper_id in created_papers: try: call("DELETE", f"/papers/{paper_id}", expect=204) except Exception as error: # noqa: BLE001 - cleanup must not mask the failure print(f"cleanup of paper {paper_id} failed: {error}", file=sys.stderr) for reference_id in created_references: try: call("DELETE", f"/references/{reference_id}", expect=204) print(f"cleaned up reference {reference_id}") except Exception as error: # noqa: BLE001 print(f"cleanup of reference {reference_id} failed: {error}", file=sys.stderr) for tag_id in created_tags: try: call("DELETE", f"/reference-tags/{tag_id}", expect=204) print(f"cleaned up tag {tag_id}") except Exception as error: # noqa: BLE001 print(f"cleanup of tag {tag_id} failed: {error}", file=sys.stderr) if __name__ == "__main__": sys.exit(main())