From 578f7eea5d9cde38e2ff1b330544558d16bb0875 Mon Sep 17 00:00:00 2001 From: Daniel McCoy Stephenson Date: Wed, 4 Nov 2026 03:19:35 -0700 Subject: [PATCH 1/2] Characterize main's unguarded cache and location failures Line coverage of main.py is already 100%, but no test or doc said what happens when environments.json is damaged, when an entry has no environment_id, or when fetching locations fails. All of these propagate out of main(), and a non-object cache file only fails after Viron has created an environment. Pin that and describe it in the README. window.close() is left unasserted, since that is the question open in #42. Co-Authored-By: Claude Opus 5.5 --- README.md | 7 +++++ tests/test_main.py | 77 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+) diff --git a/README.md b/README.md index db9f550..d13330b 100644 --- a/README.md +++ b/README.md @@ -176,6 +176,13 @@ If a recorded environment cannot be loaded — because the Viron server is unrea Creating an environment is not guarded in the same way. If the Viron server is unreachable or rejects the request, the exception propagates out of `main()`: the program exits with a traceback and a non-zero status while `Creating environment, please wait...` is still shown, nothing is added to `environments.json`, and no `environment-created` event is reported. `create_environments.bat` relies on that non-zero status to print `Error occurred while running with size .`, with the traceback going to `error_log.txt`. +Only the load itself is guarded. The other failures below also propagate out of `main()`, so the program exits with a traceback and a non-zero status, with no error drawn in the window: + +- If `environments.json` is empty or is not valid JSON, the failure comes before Viron is contacted and the file is left as it is. Deleting the file lets the next run start afresh. +- If `environments.json` holds valid JSON that is not an object, such as `[]`, the failure comes only after the environment has been created through Viron. The new environment is not recorded, and the file is left as it is. +- If the entry for the requested grid size has no `environment_id`, the failure comes before Viron is contacted, so the load error above is not shown. Deleting the entry lets the next run create it afresh. +- If fetching an environment's locations fails, the environment stays recorded in `environments.json`, so the next run loads it rather than creating another. For a new environment, the `environment-created` event has already been reported by then. + The window opens at 800x800 and can be resized. The render loop scales the grid to the window's current size on every frame, so the whole environment stays visible; the cells are stretched rather than kept square when the window is not square. The render loop is capped at 60 frames per second via `RenderWindow.tick()`. Since each location is re-coloured at random on every frame, that cap is also what sets the rate at which the visualization re-randomizes. diff --git a/tests/test_main.py b/tests/test_main.py index 267fc51..ba2da7c 100644 --- a/tests/test_main.py +++ b/tests/test_main.py @@ -209,6 +209,83 @@ def test_a_failed_creation_propagates_without_recording_the_environment(self): self.window.should_continue.assert_not_called() +class TestUnguardedFailures(MainTestCase): + """ + Failures outside the one guarded call, get_environment_by_id. Like a failed creation, + these propagate out of main(), and whether they should be handled like a failed load + is the open question in #42, so nothing here asserts on window.close(). + """ + + def writeRawCacheFile(self, text): + with open("environments.json", "w") as cacheFile: + cacheFile.write(text) + + def readRawCacheFile(self): + with open("environments.json", "r") as cacheFile: + return cacheFile.read() + + def assertLocationFailurePropagates(self, **runMainArguments): + self.locationService.get_locations_in_environment.side_effect = RuntimeError("unreachable") + + with self.assertRaisesRegex(RuntimeError, "unreachable"): + self.runMain(gridSize=10, **runMainArguments) + + def test_a_cache_file_that_is_not_json_propagates_and_is_left_untouched(self): + for name, text in (("malformed", "{not json"), ("empty", "")): + with self.subTest(name): + self.writeRawCacheFile(text) + + with self.assertRaises(json.JSONDecodeError): + self.runMain(gridSize=10) + + self.assertEqual(self.readRawCacheFile(), text) + self.environmentService.create_environment.assert_not_called() + self.environmentService.get_environment_by_id.assert_not_called() + + def test_a_cache_file_that_is_not_an_object_fails_only_after_the_environment_is_created(self): + self.writeRawCacheFile("[]") + + with self.assertRaises(TypeError): + self.runMain(gridSize=10) + + self.environmentService.create_environment.assert_called_once_with("Test", 1, 10) + self.assertEqual(self.readRawCacheFile(), "[]") + + def test_a_cache_entry_without_an_id_propagates_instead_of_failing_as_a_load(self): + self.writeCacheFile({"1x10": {"grid_size": 10}}) + + with self.assertRaisesRegex(KeyError, "environment_id"): + self.runMain(gridSize=10) + + self.environmentService.get_environment_by_id.assert_not_called() + self.environmentService.create_environment.assert_not_called() + self.assertEqual(self.readCacheFile(), {"1x10": {"grid_size": 10}}) + + def test_a_failed_location_fetch_after_creation_keeps_the_environment_recorded(self): + self.setFrames(1) + + self.assertLocationFailurePropagates(reportUsage=True) + + self.assertEqual(self.readCacheFile()["1x10"]["environment_id"], 7) + self.mockStartUsageReporting.return_value.report.assert_called_once_with("environment-created") + + def test_a_failed_location_fetch_with_exit_after_create_keeps_the_environment_recorded(self): + self.assertLocationFailurePropagates(exitAfterCreate=True, reportUsage=True) + + self.assertEqual(self.readCacheFile()["1x10"]["environment_id"], 7) + self.mockStartUsageReporting.return_value.report.assert_called_once_with("environment-created") + + def test_a_failed_location_fetch_after_a_load_shows_no_load_error(self): + self.writeCacheFile({"1x10": {"environment_id": 42}}) + self.setFrames(1) + + self.assertLocationFailurePropagates() + + self.assertEqual(self.readCacheFile(), {"1x10": {"environment_id": 42}}) + drawnTexts = [call.args[0] for call in self.graphik.drawText.call_args_list] + self.assertNotIn("Error loading environment, please check logs.", drawnTexts) + + class TestLoadingMessage(MainTestCase): """Regression coverage for the cached-environment progress message (#21).""" From 8b5bd71faea35c0cecfe3edbe38ad65df2e331e5 Mon Sep 17 00:00:00 2001 From: Daniel McCoy Stephenson Date: Wed, 4 Nov 2026 03:20:21 -0700 Subject: [PATCH 2/2] Say how a non-object cache file is recovered from Every run against such a file creates another unrecorded environment, and it was the only listed failure without a recovery step. Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d13330b..80471d4 100644 --- a/README.md +++ b/README.md @@ -179,7 +179,7 @@ Creating an environment is not guarded in the same way. If the Viron server is u Only the load itself is guarded. The other failures below also propagate out of `main()`, so the program exits with a traceback and a non-zero status, with no error drawn in the window: - If `environments.json` is empty or is not valid JSON, the failure comes before Viron is contacted and the file is left as it is. Deleting the file lets the next run start afresh. -- If `environments.json` holds valid JSON that is not an object, such as `[]`, the failure comes only after the environment has been created through Viron. The new environment is not recorded, and the file is left as it is. +- If `environments.json` holds valid JSON that is not an object, such as `[]`, the failure comes only after the environment has been created through Viron. The new environment is not recorded and the file is left as it is, so every further run creates another one until the file is deleted. - If the entry for the requested grid size has no `environment_id`, the failure comes before Viron is contacted, so the load error above is not shown. Deleting the entry lets the next run create it afresh. - If fetching an environment's locations fails, the environment stays recorded in `environments.json`, so the next run loads it rather than creating another. For a new environment, the `environment-created` event has already been reported by then.