diff --git a/README.md b/README.md index 8713670..a420b83 100644 --- a/README.md +++ b/README.md @@ -358,6 +358,12 @@ To turn reporting off, any one of these is enough: For both variables, case and surrounding whitespace are ignored, and any other value (including an empty one) leaves `settings.json` in charge. +In `settings.json`, `enabled` should be the JSON value `false`, not the string `"false"`: it is read +for its truthiness, so any non-empty string, including `"false"` and `"off"`, leaves reporting on, +while `0`, `""` and `null` turn it off. The `usage_reporting` entry itself must be an object. Any +other value, such as `false`, is overwritten with the default block above, with reporting on, and +the first-launch notice is shown again. + The environment variables win over `settings.json`. `endpoint` selects the trace server and `key` the key reports are sent with; the `PATCHWORK_USAGE_REPORTING_KEY` environment variable, when set, overrides the key in `settings.json` and the shipped one. The client lives in diff --git a/tests/test_usage_reporting.py b/tests/test_usage_reporting.py index 2fa7226..80a88ce 100644 --- a/tests/test_usage_reporting.py +++ b/tests/test_usage_reporting.py @@ -132,6 +132,44 @@ def test_opt_out_is_respected_and_not_rewritten(self): self.assertEqual([], self.logged) self.assertEqual({"usage_reporting": {"enabled": False}}, self.readSettingsFile()) + def test_a_block_that_is_not_an_object_is_replaced_by_the_defaults(self): + # Characterizes current behaviour: only an object counts as the block, so a value + # such as false is overwritten with reporting turned on and the notice shown again. + for name, value in (("false", False), ("string", "off"), ("list", []), ("null", None)): + with self.subTest(name): + self.logged.clear() + with open(self.settingsFile, "w") as f: + json.dump({"usage_reporting": value, "other": {"kept": 1}}, f) + + section = loadSettings(self.settingsFile, self.log) + + self.assertEqual({"enabled": True, "endpoint": DEFAULT_ENDPOINT, "key": DEFAULT_KEY}, section) + self.assertEqual([FIRST_RUN_NOTICE], self.logged) + self.assertEqual({"usage_reporting": section, "other": {"kept": 1}}, self.readSettingsFile()) + + def test_enabled_is_read_by_truthiness(self): + # Characterizes current behaviour: enabled is passed through bool(), so the string + # "false" turns reporting on, while 0, "" and null turn it off like false does. + cases = ( + ("missing", {}, True), + ("string false", {"enabled": "false"}, True), + ("string off", {"enabled": "off"}, True), + ("one", {"enabled": 1}, True), + ("zero", {"enabled": 0}, False), + ("empty string", {"enabled": ""}, False), + ("null", {"enabled": None}, False), + ) + for name, section, expectedEnabled in cases: + with self.subTest(name): + client = buildClient(section, self.log) + try: + self.assertEqual(expectedEnabled, client.enabled) + self.assertEqual(None if expectedEnabled else "config", client.disabled_reason) + finally: + # nothing was reported, so close() sends nothing to the real service + client.close() + self.assertEqual([], self.logged) + def test_unreadable_settings_file_disables_reporting_without_raising(self): with open(self.settingsFile, "w") as f: f.write("{not json")