Files
claude-config/bin/do_epic/backend/contract.py
T

326 lines
19 KiB
Python

"""What every backend of an epic's plan must hold, as tests. A backend's test case inherits EpicStoreContract and unittest.TestCase, and builds an epic with no issues in new_store. Its comments_on reads an issue's comments. Its assign, close, person_files, score and block change the tracker as a person or the plan store would. Its account is the display name of the account the store works as."""
import re
import typing
from do_epic.backend.protocol import EpicIssue, EpicStore
from failure import Failure
SCORES = {"L": 2, "E": 1, "I": 2, "S": 3}
class EpicStoreContract:
assertEqual: typing.Callable[..., None]
assertIn: typing.Callable[..., None]
assertIsInstance: typing.Callable[..., None]
assertIsNone: typing.Callable[..., None]
subTest: typing.Callable[..., typing.ContextManager[None]]
# The name of a transition the tracker offers an open issue, which leads to the done status "Done".
transition = "Done"
def new_store(self) -> EpicStore:
raise NotImplementedError
def assign(self, store: EpicStore, key: str, name: str) -> None:
"""Assigns the issue named key to the person whose display name is name."""
raise NotImplementedError
def account(self, store: EpicStore) -> str:
raise NotImplementedError
def close(self, store: EpicStore, key: str, status: str) -> None:
"""Moves the issue named key to the done status named status."""
raise NotImplementedError
def comments_on(self, store: EpicStore, key: str) -> list[str]:
"""The text of each comment on the issue named key, in the order posted, as markdown."""
raise NotImplementedError
def person_files(self, store: EpicStore, summary: str) -> str:
"""Files a child issue of the epic as a person does in the tracker, not through the store, and answers its key."""
raise NotImplementedError
def score(self, store: EpicStore, key: str, scores: dict[str, object]) -> None:
"""Sets the scores of the issue named key as `plan_store` writes them: each column's name with its value, a whole number for a score and text for Moves and Exempt, such as {"L": 2, "Moves": "1 by 5"}."""
raise NotImplementedError
def block(self, store: EpicStore, key: str, blocker: str) -> None:
"""Makes the issue named key blocked by the issue named blocker, as a person would link them in the tracker."""
raise NotImplementedError
def filed(self, store: EpicStore, parent: str, summary: str, detail: str = "", labels: tuple[str, ...] = ()) -> str:
key = store.file(parent, summary, detail, labels)
assert isinstance(key, str), key
return key
def issues(self, store: EpicStore) -> list[EpicIssue]:
read = store.read()
assert isinstance(read, list), read
return read
def test_an_epic_with_no_issues_reads_empty(self) -> None:
self.assertEqual(self.new_store().read(), [])
def test_reads_back_a_child_issue_it_filed(self) -> None:
store = self.new_store()
key = self.filed(store, store.epic_key, "Count the runs.", "Why it counts.\n\nA second paragraph.", ("security", "api"))
self.assertEqual(self.issues(store), [EpicIssue(key, "Count the runs.", "Why it counts.\n\nA second paragraph.", ("api", "security"), None, "To Do", False, store.epic_key, by_loop=True)])
def test_reads_back_a_sub_task_it_filed_after_its_parent(self) -> None:
store = self.new_store()
first = self.filed(store, store.epic_key, "Count the runs.")
second = self.filed(store, store.epic_key, "Ship the later thing.")
task = self.filed(store, first, "Count them in the api.", labels=("api",))
read = self.issues(store)
self.assertEqual([(issue.key, issue.parent) for issue in read], [(first, store.epic_key), (task, first), (second, store.epic_key)])
self.assertEqual((read[1].summary, read[1].labels, read[1].detail), ("Count them in the api.", ("api",), ""))
def test_files_each_issue_under_its_own_key_in_the_epics_project(self) -> None:
store = self.new_store()
child = self.filed(store, store.epic_key, "Count the runs.")
keys = [child, self.filed(store, store.epic_key, "Count the runs."), self.filed(store, child, "Count them in the api.")]
self.assertEqual(len(set(keys)), 3)
project = store.epic_key.rpartition("-")[0]
self.assertEqual([re.fullmatch(f"{project}-[1-9][0-9]*", key) is not None for key in keys], [True] * 3)
def test_reads_the_assignee_and_a_done_status(self) -> None:
store = self.new_store()
first = self.filed(store, store.epic_key, "Count the runs.")
second = self.filed(store, store.epic_key, "Ship the later thing.")
self.assign(store, first, "Ada Lovelace")
self.close(store, second, "Done")
read = {issue.key: issue for issue in self.issues(store)}
self.assertEqual((read[first].assignee, read[first].status, read[first].done), ("Ada Lovelace", "To Do", False))
self.assertEqual((read[second].assignee, read[second].status, read[second].done), (None, "Done", True))
def test_refuses_to_file_under_a_sub_task(self) -> None:
store = self.new_store()
child = self.filed(store, store.epic_key, "Count the runs.")
task = self.filed(store, child, "Count them in the api.")
self.assertEqual(store.file(task, "Count more.", "", ()), Failure(f"{task} is neither the epic {store.epic_key} nor one of its child issues, so nothing can be filed under it"))
self.assertEqual(len(self.issues(store)), 2)
def test_files_an_issue_blocked_by_a_child_issue_or_a_sub_task_of_the_epic(self) -> None:
store = self.new_store()
child = self.filed(store, store.epic_key, "Pin the behaviour.")
task = self.filed(store, child, "Pin it in the api.")
second = store.file(store.epic_key, "Change the behaviour.", "", (), child)
third = store.file(child, "Change it in the api.", "", (), task)
assert isinstance(second, str) and isinstance(third, str), (second, third)
read = {issue.key: issue for issue in self.issues(store)}
self.assertEqual((read[second].blockers, read[third].blockers, read[third].parent), ((child,), (task,), child))
def test_refuses_to_file_blocked_by_an_issue_outside_the_epic(self) -> None:
store = self.new_store()
for blocker in ("ZZZ-1", "not a key"):
with self.subTest(blocker=blocker):
self.assertIsInstance(store.file(store.epic_key, "Count more.", "", (), blocker), Failure)
self.assertEqual(self.issues(store), [])
def test_refuses_to_file_blocked_by_the_epic_itself(self) -> None:
store = self.new_store()
self.assertIsInstance(store.file(store.epic_key, "Count more.", "", (), store.epic_key), Failure)
self.assertEqual(self.issues(store), [])
def test_refuses_to_file_under_an_issue_outside_the_epic(self) -> None:
store = self.new_store()
for parent in ("ZZZ-1", "not a key"):
with self.subTest(parent=parent):
self.assertIsInstance(store.file(parent, "Count more.", "", ()), Failure)
self.assertEqual(self.issues(store), [])
def test_refuses_a_label_with_white_space_and_a_summary_of_two_lines(self) -> None:
store = self.new_store()
self.assertEqual(store.file(store.epic_key, "Count the runs.", "", ("two words",)), Failure("the label 'two words' is empty or holds white space"))
self.assertEqual(store.file(store.epic_key, "Count\nthe runs.", "", ()), Failure("the summary must be one line of text"))
self.assertEqual(self.issues(store), [])
def test_adds_a_label_to_a_child_issue_and_keeps_the_others(self) -> None:
store = self.new_store()
key = self.filed(store, store.epic_key, "Count the runs.", labels=("api",))
other = self.filed(store, store.epic_key, "Ship the later thing.")
self.assertEqual([store.add_label(key, "repo:log"), store.add_label(key, "repo:log")], [None, None])
read = {issue.key: issue for issue in self.issues(store)}
self.assertEqual((read[key].labels, read[other].labels), (("api", "repo:log"), ()))
def test_refuses_to_label_a_sub_task_an_issue_outside_the_epic_or_a_label_with_white_space(self) -> None:
store = self.new_store()
child = self.filed(store, store.epic_key, "Count the runs.")
task = self.filed(store, child, "Count them in the api.")
for key, label, reason in (
(task, "repo:log", f"{task} is not one of the child issues of the epic {store.epic_key}, so it cannot be labelled"),
(child, "two words", "the label 'two words' is empty or holds white space"),
):
with self.subTest(key=key, label=label):
self.assertEqual(store.add_label(key, label), Failure(reason))
self.assertIsInstance(store.add_label("ZZZ-1", "repo:log"), Failure)
self.assertEqual([issue.labels for issue in self.issues(store)], [(), ()])
def test_starts_an_issue_nobody_holds_as_its_own_account_and_answers_who_else_holds_one(self) -> None:
store = self.new_store()
free = self.filed(store, store.epic_key, "Count the runs.")
held = self.filed(store, store.epic_key, "Ship the later thing.")
task = self.filed(store, free, "Count them in the api.")
untouched = self.filed(store, store.epic_key, "Close the old thing.")
self.assign(store, held, "Ada Berg")
self.assertEqual([store.start_issue(free), store.start_issue(held), store.start_issue(task), store.start_issue(free)], [None, "Ada Berg", None, None])
self.assertEqual({issue.key: issue.assignee for issue in self.issues(store)}, {free: self.account(store), held: "Ada Berg", task: self.account(store), untouched: None})
def test_refuses_to_start_an_issue_outside_the_epic(self) -> None:
store = self.new_store()
self.filed(store, store.epic_key, "Count the runs.")
self.assertIsInstance(store.start_issue("ZZZ-1"), Failure)
self.assertIsInstance(store.start_issue("not a key"), Failure)
self.assertEqual([issue.assignee for issue in self.issues(store)], [None])
def test_finishes_a_child_issue_so_it_reads_as_done_and_leaves_one_that_is_done_as_it_is(self) -> None:
store = self.new_store()
key = self.filed(store, store.epic_key, "Count the runs.")
other = self.filed(store, store.epic_key, "Ship the later thing.")
closed = self.filed(store, store.epic_key, "Close the old thing.")
self.close(store, closed, "Done")
self.assertEqual([store.finish_issue(key), store.finish_issue(closed)], [None, None])
self.assertEqual({issue.key: issue.done for issue in self.issues(store)}, {key: True, other: False, closed: True})
def test_moves_a_child_issue_or_a_sub_task_to_the_status_named_and_leaves_one_already_there(self) -> None:
store = self.new_store()
child = self.filed(store, store.epic_key, "Count the runs.")
task = self.filed(store, child, "Count them in the api.")
self.assertEqual([store.move_issue(task, "Done"), store.move_issue(task, "done")], [None, None])
self.assertEqual({issue.key: issue.status for issue in self.issues(store)}, {child: "To Do", task: "Done"})
def test_refuses_to_move_an_issue_outside_the_epic(self) -> None:
store = self.new_store()
self.filed(store, store.epic_key, "Count the runs.")
self.assertIsInstance(store.move_issue("ZZZ-1", "Done"), Failure)
self.assertEqual([issue.status for issue in self.issues(store)], ["To Do"])
def test_moves_a_child_issue_or_a_sub_task_by_the_transition_named_and_answers_the_status_it_leads_to(self) -> None:
store = self.new_store()
child = self.filed(store, store.epic_key, "Count the runs.")
task = self.filed(store, child, "Count them in the api.")
self.assertEqual([store.move_issue_by(task, self.transition, ("Done",)), store.move_issue_by(child, self.transition, ("Done",))], ["Done", "Done"])
self.assertEqual({issue.key: (issue.status, issue.done) for issue in self.issues(store)}, {child: ("Done", True), task: ("Done", True)})
def test_leaves_an_issue_already_at_a_status_asked_for_where_it_is(self) -> None:
store = self.new_store()
child = self.filed(store, store.epic_key, "Count the runs.")
self.assertEqual(store.move_issue_by(child, self.transition, ("Done",)), "Done")
self.assertEqual(store.move_issue_by(child, "Release Ready", ("done",)), "Done")
def test_refuses_to_move_an_issue_outside_the_epic_by_a_transition(self) -> None:
store = self.new_store()
self.filed(store, store.epic_key, "Count the runs.")
self.assertIsInstance(store.move_issue_by("ZZZ-1", self.transition, ("Done",)), Failure)
self.assertEqual([issue.status for issue in self.issues(store)], ["To Do"])
def test_finishes_a_sub_task_of_a_child_issue_and_leaves_its_parent_open(self) -> None:
store = self.new_store()
child = self.filed(store, store.epic_key, "Count the runs.")
task = self.filed(store, child, "Count them in the api.")
self.assertIsNone(store.finish_issue(task))
self.assertEqual({issue.key: issue.done for issue in self.issues(store)}, {child: False, task: True})
def test_refuses_to_finish_an_issue_outside_the_epic(self) -> None:
store = self.new_store()
child = self.filed(store, store.epic_key, "Count the runs.")
self.assertIsInstance(store.finish_issue("ZZZ-1"), Failure)
self.assertIsInstance(store.finish_issue("not a key"), Failure)
self.assertEqual([issue.done for issue in self.issues(store)], [False])
def test_posts_comments_on_a_child_issue_in_order(self) -> None:
store = self.new_store()
key = self.filed(store, store.epic_key, "Count the runs.")
other = self.filed(store, store.epic_key, "Ship the later thing.")
self.assertEqual([store.comment(key, "Split by repo."), store.comment(key, "Done in the api.")], [None, None])
self.assertEqual((self.comments_on(store, key), self.comments_on(store, other)), (["Split by repo.", "Done in the api."], []))
def test_refuses_to_comment_on_a_sub_task_an_issue_outside_the_epic_or_with_no_words(self) -> None:
store = self.new_store()
child = self.filed(store, store.epic_key, "Count the runs.")
task = self.filed(store, child, "Count them in the api.")
self.assertEqual(store.comment(task, "Hello."), Failure(f"{task} is not one of the child issues of the epic {store.epic_key}, so it cannot be commented on"))
self.assertEqual(store.comment(child, " \n"), Failure("the comment must hold some text"))
self.assertIsInstance(store.comment("ZZZ-1", "Hello."), Failure)
self.assertEqual([self.comments_on(store, key) for key in (child, task)], [[], []])
def test_closes_the_epic_once_its_summary_is_posted_and_refuses_a_blank_one(self) -> None:
store = self.new_store()
self.assertEqual(store.closed(), False)
self.assertIsInstance(store.close(" \n"), Failure)
self.assertEqual((store.closed(), self.comments_on(store, "ABC-12")), (False, []))
self.assertEqual(store.close("## Shipped\n\nThe import.\n"), None)
self.assertEqual((store.closed(), self.comments_on(store, "ABC-12")), (True, ["## Shipped\n\nThe import."]))
def test_reads_an_issue_without_scores_or_blockers_as_one_with_none(self) -> None:
store = self.new_store()
key = self.filed(store, store.epic_key, "Count the runs.")
[issue] = self.issues(store)
self.assertEqual((issue.key, issue.scores, issue.moves, issue.exempt, issue.blockers), (key, {}, (), "", ()))
def test_reads_the_scores_a_person_or_the_plan_store_set(self) -> None:
store = self.new_store()
key = self.filed(store, store.epic_key, "Count the runs.")
self.score(store, key, {"L": 2, "E": 3, "I": 4, "S": 3, "Moves": "1 by 5", "Exempt": "security"})
[issue] = self.issues(store)
self.assertEqual((issue.scores, issue.moves, issue.exempt), ({"L": 2, "E": 3, "I": 4, "S": 3}, (("1", 5),), "security"))
def test_sets_the_scores_of_a_persons_issue_and_of_a_sub_task_and_tells_the_team(self) -> None:
store = self.new_store()
key = self.person_files(store, "Count the runs.")
task = self.filed(store, key, "Count them in the API.")
self.assertEqual([store.set_scores(key, SCORES, "epic 1 by 5, repo 2 by 3", "Scored: it moves the import."), store.set_scores(task, SCORES, "", "Scored.")], [None, None])
child, sub = self.issues(store)
self.assertEqual((child.scores, child.moves, child.by_loop, sub.scores, sub.moves, sub.by_loop), (SCORES, (("epic 1", 5), ("repo 2", 3)), False, SCORES, (), True))
self.assertEqual((self.comments_on(store, key), self.comments_on(store, task)), (["Scored: it moves the import."], ["Scored."]))
def test_an_issue_that_holds_scores_keeps_them_and_gets_no_comment(self) -> None:
store = self.new_store()
key = self.filed(store, store.epic_key, "Count the runs.")
self.score(store, key, {"L": 2, "E": 3, "I": 4, "S": 3, "Moves": "1 by 5"})
refused = store.set_scores(key, SCORES, "", "Scored.")
assert isinstance(refused, Failure)
self.assertIn(f"{key} holds scores already", refused.reason)
[issue] = self.issues(store)
self.assertEqual((issue.scores, issue.moves, self.comments_on(store, key)), ({"L": 2, "E": 3, "I": 4, "S": 3}, (("1", 5),), []))
def test_refuses_scores_outside_the_epic_out_of_range_or_incomplete_or_without_a_comment(self) -> None:
store = self.new_store()
key = self.filed(store, store.epic_key, "Count the runs.")
refusals = [store.set_scores("ZZZ-1", SCORES, "", "Scored."), store.set_scores("not a key", SCORES, "", "Scored."), store.set_scores(key, SCORES | {"L": 9}, "", "Scored."), store.set_scores(key, {"L": 1}, "", "Scored."), store.set_scores(key, SCORES | {"R": 1}, "", "Scored."), store.set_scores(key, SCORES, "the import by 5", "Scored."), store.set_scores(key, SCORES, "", " \n")]
for refused in refusals:
self.assertIsInstance(refused, Failure)
self.assertEqual(refusals[1], Failure(f"not a key is not one of the child issues of the epic {store.epic_key}, so it cannot be scored"))
assert isinstance(refusals[3], Failure)
self.assertEqual(refusals[3].reason[refusals[3].reason.rindex(key):], f"{key} is given L: set each of L, E, I and S, and nothing else")
[issue] = self.issues(store)
self.assertEqual((issue.scores, self.comments_on(store, key)), ({}, []))
def test_reads_each_blocker_of_an_issue_and_none_for_a_blocker_of_another(self) -> None:
store = self.new_store()
first, second, third = (self.filed(store, store.epic_key, f"Item {n}.") for n in range(3))
self.block(store, third, first)
self.block(store, third, second)
read = {issue.key: issue for issue in self.issues(store)}
self.assertEqual([read[key].blockers for key in (first, second, third)], [(), (), (first, second)])
def test_reads_whether_the_loop_filed_an_issue(self) -> None:
store = self.new_store()
ours = self.filed(store, store.epic_key, "Count the runs.")
theirs = self.person_files(store, "A person's issue.")
# The plan store scores an issue a person filed without making it the loop's.
self.score(store, theirs, {"L": 2, "E": 3, "I": 4, "S": 3, "Moves": "1 by 5"})
task = self.filed(store, ours, "Count them in the api.")
read = {issue.key: issue for issue in self.issues(store)}
self.assertEqual([read[key].by_loop for key in (ours, theirs, task)], [True, False, True])
def test_ranks_a_child_issue_just_before_another_and_its_sub_tasks_follow_it(self) -> None:
store = self.new_store()
first, second, third = (self.filed(store, store.epic_key, f"Item {n}.") for n in range(3))
task = self.filed(store, third, "A task.")
self.assertEqual(store.rank(third, first), None)
self.assertEqual([issue.key for issue in self.issues(store)], [third, task, first, second])
self.assertEqual(store.rank(first, third), None)
self.assertEqual([issue.key for issue in self.issues(store)], [first, third, task, second])