"""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. **Every entry this script creates carries a token in its title, its author and its tag names.** The library it runs against is a real one and may hold hundreds of entries, so "the search found one row" is only a meaningful assertion about rows this run made. The token is what makes each count below a statement about this run rather than about the library's size. """ from __future__ import annotations import json import sys import urllib.error import urllib.parse import urllib.request import uuid from typing import Any BASE = "http://127.0.0.1:8000/api" #: Stamped into every entry this run creates, so each search below can be scoped #: to this run instead of to an empty database. Short and uppercase: it travels #: in titles, in an author name and in tag names, and shows up in failure output. TOKEN = uuid.uuid4().hex[:6].upper() #: A second token, carried by one contributor's *name* only. Titles and tag names #: carry ``TOKEN``, so searching for it finds every row this run made; finding a #: single row by author needs a string that is in exactly one place. AUTHOR_TOKEN = f"AU{TOKEN}" _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": f" 综述-{TOKEN} ", "color": "rgb(64, 158, 255)", "note": "综述性文献", }, expect=201, ) created_tags.append(survey["id"]) check( "a name is trimmed to one spelling", survey["name"] == f"综述-{TOKEN}", 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": f"必读-{TOKEN}", "color": "#f56c6c"}, expect=201, ) created_tags.append(must_read["id"]) check("the second tag is stored", must_read["name"] == f"必读-{TOKEN}") print("2. a tag name is unique, and only a real colour is accepted") duplicate = call( "POST", "/reference-tags", {"name": f"综述-{TOKEN}"}, expect=409 ) check( "the refusal names the label", TOKEN in duplicate["detail"], duplicate["detail"], ) call( "POST", "/reference-tags", {"name": f"怪颜色-{TOKEN}", "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": f"技术惯性与冲量的耦合机制({TOKEN})", "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": f"Wang Wu {AUTHOR_TOKEN}", "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"]] == ["张三", "李四", f"Wang Wu {AUTHOR_TOKEN}", "世界卫生组织"], 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"]) == [f"必读-{TOKEN}", f"综述-{TOKEN}"], str(article["tags"]), ) print("4. a tag that does not exist is refused by name, not invented") missing_tag = call( "POST", "/references", { "title": f"引用了不存在的标签{TOKEN}", "type": "book", "tag_ids": [999999], }, expect=400, ) check("the refusal names the id", "999999" in missing_tag["detail"], missing_tag["detail"]) orphan = call("GET", f"/references?keyword=引用了不存在的标签{TOKEN}") 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": f"一种基于多层聚类的人工智能技术识别方法({TOKEN})", "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"]] == [f"必读-{TOKEN}"], 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": f"没有标签的书{TOKEN}", "authors": [{"name": "甲"}], "type": "book", }, expect=201, ) probe = call("GET", f"/references?keyword=没有标签的书{TOKEN}") 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", f"/references?keyword={AUTHOR_TOKEN}") check( "search matches an author name", by_author["total"] == 1, f'{by_author["total"]} (the token is on one author name)', ) 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", f"/references?type=patent&keyword={TOKEN}") check("filter by type", by_type["total"] == 1, str(by_type["total"])) by_year = call("GET", f"/references?year=2024&keyword={TOKEN}") check("filter by year", by_year["total"] == 1, str(by_year["total"])) uncited = call("GET", f"/references?cited=false&keyword={TOKEN}") check( "filter by not-yet-cited", uncited["total"] == len(created_references), f'{uncited["total"]} of {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", f"/reference-tags?keyword={TOKEN}") counts = {tag["name"]: tag["reference_count"] for tag in tags["items"]} check("two labels carry this run's token", tags["total"] == 2, str(tags["total"])) check( "the shared label counts two rows", counts[f"必读-{TOKEN}"] == 2, str(counts), ) check("the other counts one", counts[f"综述-{TOKEN}"] == 1, str(counts)) found = call("GET", f"/reference-tags?keyword=综述-{TOKEN}") 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": f"综述文章-{TOKEN}", "note": "综述与述评"}, ) check("the label is renamed", renamed["name"] == f"综述文章-{TOKEN}") after = call("GET", f"/references/{article['id']}") check( "the reference prints the new name", sorted(tag["name"] for tag in after["tags"]) == [f"必读-{TOKEN}", f"综述文章-{TOKEN}"], str(after["tags"]), ) taken = call( "PATCH", f"/reference-tags/{survey['id']}", {"name": f"必读-{TOKEN}"}, expect=409, ) check( "renaming onto a taken name is refused", TOKEN 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"]] == [f"必读-{TOKEN}"], 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"]] == [f"必读-{TOKEN}"], str(cleared["tags"]), ) print("12. cite it from a sentence") templates = call("GET", "/templates?page_size=1")["items"] paper = call( "POST", "/papers", { "title": f"参考文献冒烟测试论文{TOKEN}", "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", f"/references?cited=true&keyword={TOKEN}") 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. the 参考文献 list prints one entry per work, in Springer style") document = call("GET", f"/papers/{paper['id']}/document") check("the style is named in the response", document["reference_style"] == "springer") check( "one entry for the one work cited", len(document["references"]) == 1, str(len(document["references"])), ) entry = document["references"][0] check("the entry is a bibliography line", entry["text"].startswith("张三, 李四"), entry["text"]) check("and carries the year and the DOI", "(2024)" in entry["text"] and "https://doi.org/10.1016/j.techfore.2024.123456" in entry["text"], entry["text"]) check("it names the places it is cited", len(entry["citations"]) == 1, str(len(entry["citations"]))) check( "and the in-text marker is that entry's number", entry["citations"][0]["index"] == entry["index"], f'{entry["citations"][0]["index"]} vs {entry["index"]}', ) print("17. 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() # Scoped by the token rather than by "the library is empty": the library # this runs against holds real literature, and what must be true is that # none of *this run's* rows survive. remaining = call("GET", f"/references?keyword={TOKEN}") check("nothing of ours is left", remaining["total"] == 0, str(remaining["total"])) tags_left = call("GET", f"/reference-tags?keyword={TOKEN}") check("and no labels either", tags_left["total"] == 0, str(tags_left["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())