Add docstrings for all test functions and test helper functions (717c79a) - derivepassphrase.git

Add docstrings for all test functions and test helper functions

Marco Ricci commited on 2025-01-24 23:03:43
Zeige 10 geänderte Dateien mit 1246 Einfügungen und 14 Löschungen.

These docstrings aim to provide intent and context to the test function.

tests/__init__.py 9abf707..764856b
tests/conftest.py 87874c1..c30d9ed
tests/test_derivepassphrase_cli.py f82c69b..ff84e04
tests/test_derivepassphrase_cli_export_vault.py 46e2609..5083182
tests/test_derivepassphrase_exporter.py a8c6faa..6cbd1d5
tests/test_derivepassphrase_sequin.py 1f8308a..a663955
tests/test_derivepassphrase_ssh_agent.py c0d2165..265d3d5
tests/test_derivepassphrase_types.py 3bbe7e1..208ffb5
tests/test_derivepassphrase_vault.py cc51d9b..3ddb88c
tests/test_l10n.py f1bd00c..a8e16c9

tests/__init__.py

Zeige Datei @ 717c79a

...	...	@@ -40,25 +40,85 @@ if TYPE_CHECKING:
40	40
41	41
42	42	class SSHTestKey(NamedTuple):
	43	+ """An SSH test key.
	44	+
	45	+ Attributes:
	46	+ public_key:
	47	+ The SSH public key string, as used e.g. by OpenSSH's
	48	+ `authorized_keys` file. Includes a comment.
	49	+ public_key_data:
	50	+ The SSH protocol wire format of the public key.
	51	+ private_key:
	52	+ A base64 encoded representation of the private key, in
	53	+ OpenSSH's v1 private key format.
	54	+ private_key_blob:
	55	+ The SSH protocol wire format of the private key.
	56	+ expected_signature:
	57	+ For deterministic signature types, this is the expected
	58	+ signature of the vault UUID. For other types this is
	59	+ `None`.
	60	+ derived_passphrase:
	61	+ For deterministic signature types, this is the "equivalent
	62	+ master passphrase" derived from this key (a transformation
	63	+ of [`expected_signature`][]). For other types this is
	64	+ `None`.
	65	+
	66	+ """
	67	+
43	68	public_key: bytes \| str
	69	+ """"""
44	70	public_key_data: bytes
	71	+ """"""
45	72	private_key: bytes
	73	+ """"""
46	74	private_key_blob: bytes \| None = None
	75	+ """"""
47	76	expected_signature: bytes \| None = None
	77	+ """"""
48	78	derived_passphrase: bytes \| str \| None = None
	79	+ """"""
49	80
50	81	def is_suitable(self) -> bool:
	82	+ """Return if this key is suitable for use with vault."""
51	83	return vault.Vault.is_suitable_ssh_key(self.public_key_data)
52	84
53	85
54	86	class ValidationSettings(NamedTuple):
	87	+ """Validation settings for [`VaultTestConfig`][]s.
	88	+
	89	+ Attributes:
	90	+ allow_unknown_settings:
	91	+ See [`_types.validate_vault_config`][].
	92	+
	93	+ """
	94	+
55	95	allow_unknown_settings: bool
	96	+ """"""
56	97
57	98
58	99	class VaultTestConfig(NamedTuple):
	100	+ """A (not necessarily valid) sample vault config, plus metadata.
	101	+
	102	+ Attributes:
	103	+ config:
	104	+ The actual configuration object. Usually a [`dict`][].
	105	+ comment:
	106	+ An explanatory comment for what is wrong with this config,
	107	+ or empty if the config is valid. This is intended as
	108	+ a debugging message to be shown to the user (e.g. when an
	109	+ assertion fails), not as an error message to
	110	+ programmatically match against.
	111	+ validation_settings:
	112	+ See [`_types.validate_vault_config`][].
	113	+
	114	+ """
	115	+
59	116	config: Any
	117	+ """"""
60	118	comment: str
	119	+ """"""
61	120	validation_settings: ValidationSettings \| None
	121	+ """"""
62	122
63	123
64	124	TEST_CONFIGS: list[VaultTestConfig] = [
...	...	@@ -310,6 +370,7 @@ TEST_CONFIGS: list[VaultTestConfig] = [
310	370	ValidationSettings(True),
311	371	),
312	372	]
	373	+"""The master list of test configurations for vault."""
313	374
314	375
315	376	def is_valid_test_config(conf: VaultTestConfig, /) -> bool:
...	...	@@ -333,6 +394,17 @@ def _test_config_ids(val: VaultTestConfig) -> Any: # pragma: no cover
333	394
334	395	@strategies.composite
335	396	def vault_full_service_config(draw: strategies.DrawFn) -> dict[str, int]:
	397	+ """Hypothesis strategy for full vault service configurations.
	398	+
	399	+ Returns a sample configuration with restrictions on length, repeat
	400	+ count, and all character classes, while ensuring the settings are
	401	+ not obviously unsatisfiable.
	402	+
	403	+ Args:
	404	+ draw:
	405	+ The `draw` function, as provided for by hypothesis.
	406	+
	407	+ """
336	408	repeat = draw(strategies.integers(min_value=0, max_value=10))
337	409	lower = draw(strategies.integers(min_value=0, max_value=10))
338	410	upper = draw(strategies.integers(min_value=0, max_value=10))
...	...	@@ -400,7 +472,7 @@ def smudged_vault_test_config(
400	472
401	473	Args:
402	474	draw:
403		- The hypothesis draw function.
	475	+ The `draw` function, as provided for by hypothesis.
404	476	config:
405	477	A strategy which generates [`VaultTestConfig`][] objects.
406	478
...	...	@@ -421,7 +493,7 @@ def smudged_vault_test_config(
421	493	services.append(obj['global'])
422	494	assert all(isinstance(x, dict) for x in services), (
423	495	'is_smudgable_vault_test_config guard failed to '
424		- 'ensure each setings dict is a dict'
	496	+ 'ensure each settings dict is a dict'
425	497	)
426	498	for service in services:
427	499	for key in ('phrase',):
...	...	@@ -453,20 +525,75 @@ def smudged_vault_test_config(
453	525
454	526
455	527	class KnownSSHAgent(str, enum.Enum):
	528	+ """Known SSH agents.
	529	+
	530	+ Attributes:
	531	+ UNKNOWN:
	532	+ Not a known agent, or not known statically.
	533	+ Pageant:
	534	+ The agent from Simon Tatham's PuTTY suite.
	535	+ OpenSSHAgent:
	536	+ The agent from OpenBSD's OpenSSH suite.
	537	+
	538	+ """
	539	+
456	540	UNKNOWN: str = '(unknown)'
	541	+ """"""
457	542	Pageant: str = 'Pageant'
	543	+ """"""
458	544	OpenSSHAgent: str = 'OpenSSHAgent'
	545	+ """"""
459	546
460	547
461	548	class SpawnedSSHAgentInfo(NamedTuple):
	549	+ """Info about a spawned SSH agent, as provided by some fixtures.
	550	+
	551	+ Differs from [`RunningSSHAgentInfo`][] in that this info object
	552	+ already provides a functional client connected to the agent, but not
	553	+ the address.
	554	+
	555	+ Attributes:
	556	+ agent_type:
	557	+ The agent's type.
	558	+ client:
	559	+ An SSH agent client connected to this agent.
	560	+ isolated:
	561	+ Whether this agent was spawned specifically for this test
	562	+ suite, with attempts to isolate it from the user. If false,
	563	+ then the user may be interacting with the agent externally,
	564	+ meaning e.g. keys other than the test keys may be visible in
	565	+ this agent.
	566	+
	567	+ """
	568	+
462	569	agent_type: KnownSSHAgent
	570	+ """"""
463	571	client: ssh_agent.SSHAgentClient
	572	+ """"""
464	573	isolated: bool
	574	+ """"""
465	575
466	576
467	577	class RunningSSHAgentInfo(NamedTuple):
	578	+ """Info about a running SSH agent, as provided by some fixtures.
	579	+
	580	+ Differs from [`SpawnedSSHAgentInfo`][] in that this info object
	581	+ provides only an address of the agent, not a functional client
	582	+ already connected to it. The running SSH agent may or may not be
	583	+ isolated.
	584	+
	585	+ Attributes:
	586	+ socket:
	587	+ A socket address to connect to the agent.
	588	+ agent_type:
	589	+ The agent's type.
	590	+
	591	+ """
	592	+
468	593	socket: str
	594	+ """"""
469	595	agent_type: KnownSSHAgent
	596	+ """"""
470	597
471	598
472	599	ALL_KEYS: Mapping[str, SSHTestKey] = {
...	...	@@ -998,21 +1125,34 @@ Rlc3Qga2V5IHdpdGhvdXQgcGFzc3BocmFzZQ==
998	1125	derived_passphrase=None,
999	1126	),
1000	1127	}
	1128	+"""The master list of SSH test keys."""
1001	1129	SUPPORTED_KEYS: Mapping[str, SSHTestKey] = {
1002	1130	k: v for k, v in ALL_KEYS.items() if v.is_suitable()
1003	1131	}
	1132	+"""The subset of SSH test keys suitable for use with vault."""
1004	1133	UNSUITABLE_KEYS: Mapping[str, SSHTestKey] = {
1005	1134	k: v for k, v in ALL_KEYS.items() if not v.is_suitable()
1006	1135	}
	1136	+"""The subset of SSH test keys not suitable for use with vault."""
1007	1137
1008	1138	DUMMY_SERVICE = 'service1'
	1139	+"""A standard/sample service name."""
1009	1140	DUMMY_PASSPHRASE = 'my secret passphrase'
	1141	+"""A standard/sample passphrase."""
1010	1142	DUMMY_KEY1 = SUPPORTED_KEYS['ed25519'].public_key_data
	1143	+"""A sample universally supported SSH test key (in wire format)."""
1011	1144	DUMMY_KEY1_B64 = base64.standard_b64encode(DUMMY_KEY1).decode('ASCII')
	1145	+"""
	1146	+A sample universally supported SSH test key (in `authorized_keys` format).
	1147	+"""
1012	1148	DUMMY_KEY2 = SUPPORTED_KEYS['rsa'].public_key_data
	1149	+"""A second supported SSH test key (in wire format)."""
1013	1150	DUMMY_KEY2_B64 = base64.standard_b64encode(DUMMY_KEY2).decode('ASCII')
	1151	+"""A second supported SSH test key (in `authorized_keys` format)."""
1014	1152	DUMMY_KEY3 = SUPPORTED_KEYS['ed448'].public_key_data
	1153	+"""A third supported SSH test key (in wire format)."""
1015	1154	DUMMY_KEY3_B64 = base64.standard_b64encode(DUMMY_KEY3).decode('ASCII')
	1155	+"""A third supported SSH test key (in `authorized_keys` format)."""
1016	1156	DUMMY_CONFIG_SETTINGS = {
1017	1157	'length': 10,
1018	1158	'upper': 1,
...	...	@@ -1023,8 +1163,15 @@ DUMMY_CONFIG_SETTINGS = {
1023	1163	'dash': 1,
1024	1164	'symbol': 1,
1025	1165	}
	1166	+"""Sample vault settings."""
1026	1167	DUMMY_RESULT_PASSPHRASE = b'.2V_QJkd o'
	1168	+"""
	1169	+The passphrase derived from [`DUMMY_SERVICE`][] using [`DUMMY_PASSPHRASE`][].
	1170	+"""
1027	1171	DUMMY_RESULT_KEY1 = b'E<b<{ -7iG'
	1172	+"""
	1173	+The passphrase derived from [`DUMMY_SERVICE`][] using [`DUMMY_KEY1`][].
	1174	+"""
1028	1175	DUMMY_PHRASE_FROM_KEY1_RAW = (
1029	1176	b'\x00\x00\x00\x0bssh-ed25519'
1030	1177	b'\x00\x00\x00@\xf0\x98\x19\x80l\x1a\x97\xd5&\x03n'
...	...	@@ -1032,10 +1179,23 @@ DUMMY_PHRASE_FROM_KEY1_RAW = (
1032	1179	b'\x1d\xaf\xfd\r\x08\x1f\xec\xf8s\x9b\x8c_U9\x16\|ST,'
1033	1180	b'\x1eR\xbb0\xed\x7f\x89\xe2/iQU\xd8\x9e\xa6\x02'
1034	1181	)
	1182	+"""
	1183	+The "equivalent master passphrase" derived from [`DUMMY_KEY1`][] (raw format).
	1184	+"""
1035	1185	DUMMY_PHRASE_FROM_KEY1 = b'8JgZgGwal9UmA27M42WPhmYHExkTCSEzM/nkNlMdr/0NCB/s+HObjF9VORZ8U1QsHlK7MO1/ieIvaVFV2J6mAg=='
	1186	+"""
	1187	+The "equivalent master passphrase" derived from [`DUMMY_KEY1`][] (in base64).
	1188	+"""
1036	1189
1037	1190	VAULT_MASTER_KEY = 'vault key'
	1191	+"""
	1192	+The storage passphrase used to encrypt all sample vault native configurations.
	1193	+"""
1038	1194	VAULT_V02_CONFIG = 'P7xeh5y4jmjpJ2pFq4KUcTVoaE9ZOEkwWmpVTURSSWQxbGt6emN4aFE4eFM3anVPbDRNTGpOLzY3eDF5aE1YTm5LNWh5Q1BwWTMwM3M5S083MWRWRFlmOXNqSFJNcStGMWFOS3c2emhiOUNNenZYTmNNMnZxaUErdlRoOGF2ZHdGT1ZLNTNLOVJQcU9jWmJrR3g5N09VcVBRZ0ZnSFNUQy9HdFVWWnFteVhRVkY3MHNBdnF2ZWFEbFBseWRGelE1c3BFTnVUckRQdWJSL29wNjFxd2Y2ZVpob3VyVzRod3FKTElTenJ1WTZacTJFOFBtK3BnVzh0QWVxcWtyWFdXOXYyenNQeFNZbWt1MDU2Vm1kVGtISWIxWTBpcWRFbyswUVJudVVhZkVlNVpGWDA4WUQ2Q2JTWW81SnlhQ2Zxa3cxNmZoQjJES0Uyd29rNXpSck5iWVBrVmEwOXFya1NpMi9saU5LL3F0M3N3MjZKekNCem9ER2svWkZ0SUJLdmlHRno0VlQzQ3pqZTBWcTM3YmRiNmJjTkhqUHZoQ0NxMW1ldW1XOFVVK3pQMEtUMkRMVGNvNHFlOG40ck5KcGhsYXg1b1VzZ1NYU1B2T3RXdEkwYzg4NWE3YWUzOWI1MDI0MThhMWZjODQ3MDA2OTJmNDQ0MDkxNGFiNmRlMGQ2YjZiNjI5NGMwN2IwMmI4MGZi'
	1195	+"""
	1196	+A sample vault native configuration, in v0.2 format, encoded in base64
	1197	+and encrypted with [`VAULT_MASTER_KEY`][].
	1198	+"""
1039	1199	VAULT_V02_CONFIG_DATA = {
1040	1200	'global': {
1041	1201	'phrase': DUMMY_PASSPHRASE.rstrip('\n'),
...	...	@@ -1047,7 +1207,15 @@ VAULT_V02_CONFIG_DATA = {
1047	1207	DUMMY_SERVICE: DUMMY_CONFIG_SETTINGS.copy(),
1048	1208	},
1049	1209	}
	1210	+"""
	1211	+The plaintext contents (a vault native configuration) stored in
	1212	+[`VAULT_V02_CONFIG`][].
	1213	+"""
1050	1214	VAULT_V03_CONFIG = 'sBPBrr8BFHPxSJkV/A53zk9zwDQHFxLe6UIusCVvzFQre103pcj5xxmE11lMTA0U2QTYjkhRXKkH5WegSmYpAnzReuRsYZlWWp6N4kkubf+twZ9C3EeggPm7as2Af4TICHVbX4uXpIHeQJf9y1OtqrO+SRBrgPBzgItoxsIxebxVKgyvh1CZQOSkn7BIzt9xKhDng3ubS4hQ91fB0QCumlldTbUl8tj4Xs5JbvsSlUMxRlVzZ0OgAOrSsoWELXmsp6zXFa9K6wIuZa4wQuMLQFHiA64JO1CR3I+rviWCeMlbTOuJNx6vMB5zotKJqA2hIUpN467TQ9vI4g/QTo40m5LT2EQKbIdTvBQAzcV4lOcpr5Lqt4LHED5mKvm/4YfpuuT3I3XCdWfdG5SB7ciiB4Go+xQdddy3zZMiwm1fEwIB8XjFf2cxoJdccLQ2yxf+9diedBP04EsMHrvxKDhQ7/vHl7xF2MMFTDKl3WFd23vvcjpR1JgNAKYprG/e1p/7'
	1215	+"""
	1216	+A sample vault native configuration, in v0.3 format, encoded in base64
	1217	+and encrypted with [`VAULT_MASTER_KEY`][].
	1218	+"""
1051	1219	VAULT_V03_CONFIG_DATA = {
1052	1220	'global': {
1053	1221	'phrase': DUMMY_PASSPHRASE.rstrip('\n'),
...	...	@@ -1059,6 +1227,10 @@ VAULT_V03_CONFIG_DATA = {
1059	1227	DUMMY_SERVICE: DUMMY_CONFIG_SETTINGS.copy(),
1060	1228	},
1061	1229	}
	1230	+"""
	1231	+The plaintext contents (a vault native configuration) stored in
	1232	+[`VAULT_V03_CONFIG`][].
	1233	+"""
1062	1234	VAULT_STOREROOM_CONFIG_ZIPPED = b"""
1063	1235	UEsDBBQAAAAIAJ1WGVnTVFGT0gAAAOYAAAAFAAAALmtleXMFwclSgzAAANC7n9GrBzBldcYDE5Al
1064	1236	EKbFAvGWklBAtqYsBcd/973fw8LFox76w/vb34tzhD5OATeEAk6tJ6Fbp3WrvkJO7l0KIjtxCLfY
...	...	@@ -1111,6 +1283,11 @@ AAAACACdVhlZ3Wlf4QUDAADUAwAAAgAAAAAAAAABAAAApIH1AAAAMDBQSwECHgMUAAAACACdVhlZ
1111	1283	AgAAAgAAAAAAAAABAAAApIEEBgAAMDlQSwECHgMUAAAACACdVhlZyjtiYvgBAABrAgAAAgAAAAAA
1112	1284	AAABAAAApIHsBwAAMWFQSwUGAAAAAAUABQDzAAAABAoAAAAA
1113	1285	"""
	1286	+"""
	1287	+A sample vault native configuration, in storeroom format, encrypted with
	1288	+[`VAULT_MASTER_KEY`][]. The configuration is compressed (zip archive)
	1289	+and then encoded in base64.
	1290	+"""
1114	1291	VAULT_STOREROOM_CONFIG_DATA = {
1115	1292	'global': {
1116	1293	'phrase': DUMMY_PASSPHRASE.rstrip('\n'),
...	...	@@ -1122,6 +1299,10 @@ VAULT_STOREROOM_CONFIG_DATA = {
1122	1299	DUMMY_SERVICE: DUMMY_CONFIG_SETTINGS.copy(),
1123	1300	},
1124	1301	}
	1302	+"""
	1303	+The parsed vault configuration stored in
	1304	+[`VAULT_STOREROOM_CONFIG_ZIPPED`][].
	1305	+"""
1125	1306
1126	1307	_VAULT_STOREROOM_BROKEN_DIR_CONFIG_ZIPPED_JAVASCRIPT_SOURCE = """
1127	1308	// Executed in the top-level directory of the vault project code, in Node.js.
...	...	@@ -1131,6 +1312,10 @@ let store = new Store(storeroom.createFileAdapter('./broken-dir'), 'vault key')
1131	1312	await store._storeroom.put('/services/array/', ['entry1','entry2'])
1132	1313	// The resulting "broken-dir" was then zipped manually.
1133	1314	"""
	1315	+"""
	1316	+The JavaScript source for the script that generated the storeroom
	1317	+archive in [`VAULT_STOREROOM_BROKEN_DIR_CONFIG_ZIPPED`][].
	1318	+"""
1134	1319	VAULT_STOREROOM_BROKEN_DIR_CONFIG_ZIPPED = b"""
1135	1320	UEsDBBQAAgAIAHijH1kjc0ql0gAAAOYAAAAFAAAALmtleXMFwclygjAAANB7P8Mrh7LIYmd6oGxC
1136	1321	HKwTJJgbNpBKCpGAhNTpv/e952ZpxHTjw+bN+HuJJABEikvHecD0pLgpgYKWjue0CZGk19mKF+4f
...	...	@@ -1167,6 +1352,17 @@ ox9ZI3NKpdIAAADmAAAABQAAAAAAAAABAAAApIEAAAAALmtleXNQSwECHgMUAAIACAB4ox9Zfgvu
1167	1352	AgAAAAAAAAABAAAApIHtAgAAMWFQSwECHgMUAAIACAB4ox9ZGgj3mrkBAAAXAgAAAgAAAAAAAAAB
1168	1353	AAAApIHIBAAAMWVQSwUGAAAAAAQABADDAAAAoQYAAAAA
1169	1354	"""
	1355	+"""
	1356	+A sample corrupted storeroom archive, encrypted with
	1357	+[`VAULT_MASTER_KEY`][]. The configuration is compressed (zip archive)
	1358	+and then encoded in base64.
	1359	+
	1360	+The archive contains a directory `/services/array/` that claims to have
	1361	+two child items 'entry1' and 'entry2', but no such child items are
	1362	+present in the archive. See
	1363	+[`_VAULT_STOREROOM_BROKEN_DIR_CONFIG_ZIPPED_JAVASCRIPT_SOURCE`][] for
	1364	+the exact script that created this archive.
	1365	+"""
1170	1366
1171	1367	_VAULT_STOREROOM_BROKEN_DIR_CONFIG_ZIPPED2_JAVASCRIPT_SOURCE = """
1172	1368	// Executed in the top-level directory of the vault project code, in Node.js.
...	...	@@ -1176,6 +1372,10 @@ let store = new Store(storeroom.createFileAdapter('./broken-dir'), 'vault key')
1176	1372	await store._storeroom.put('/services/array/', 'not a directory index')
1177	1373	// The resulting "broken-dir" was then zipped manually.
1178	1374	"""
	1375	+"""
	1376	+The JavaScript source for the script that generated the storeroom
	1377	+archive in [`VAULT_STOREROOM_BROKEN_DIR_CONFIG_ZIPPED2`][].
	1378	+"""
1179	1379	VAULT_STOREROOM_BROKEN_DIR_CONFIG_ZIPPED2 = b"""
1180	1380	UEsDBAoAAAAAAM6NSVmrcHdV5gAAAOYAAAAFAAAALmtleXN7InZlcnNpb24iOjF9CkV3ZS9LZkJp
1181	1381	L0V0OUcrZmxYM3gxaFU4ZjE4YlE3S253bHoxN0IxSDE3cUhVOGdWK2RpWWY5MTdFZ0YrSStidEpZ
...	...	@@ -1217,6 +1417,16 @@ LmtleXNQSwECHgMKAAAAAADOjUlZJg3/BhcCAAAXAgAAAgAAAAAAAAAAAAAApIEJAQAAMGJQSwEC
1217	1417	HgMKAAAAAADOjUlZTNfdphcCAAAXAgAAAgAAAAAAAAAAAAAApIFAAwAAMGZQSwECHgMKAAAAAADO
1218	1418	jUlZn9rNID8CAAA/AgAAAgAAAAAAAAAAAAAApIF3BQAAMWRQSwUGAAAAAAQABADDAAAA1gcAAAAA
1219	1419	"""
	1420	+"""
	1421	+A sample corrupted storeroom archive, encrypted with
	1422	+[`VAULT_MASTER_KEY`][]. The configuration is compressed (zip archive)
	1423	+and then encoded in base64.
	1424	+
	1425	+The archive contains a directory `/services/array/` whose list of child
	1426	+items does not adhere to the serialization format. See
	1427	+[`_VAULT_STOREROOM_BROKEN_DIR_CONFIG_ZIPPED2_JAVASCRIPT_SOURCE`][] for
	1428	+the exact script that created this archive.
	1429	+"""
1220	1430
1221	1431	_VAULT_STOREROOM_BROKEN_DIR_CONFIG_ZIPPED3_JAVASCRIPT_SOURCE = """
1222	1432	// Executed in the top-level directory of the vault project code, in Node.js.
...	...	@@ -1226,6 +1436,10 @@ let store = new Store(storeroom.createFileAdapter('./broken-dir'), 'vault key')
1226	1436	await store._storeroom.put('/services/array/', [null, 1, true, [], {}])
1227	1437	// The resulting "broken-dir" was then zipped manually.
1228	1438	"""
	1439	+"""
	1440	+The JavaScript source for the script that generated the storeroom
	1441	+archive in [`VAULT_STOREROOM_BROKEN_DIR_CONFIG_ZIPPED3`][].
	1442	+"""
1229	1443	VAULT_STOREROOM_BROKEN_DIR_CONFIG_ZIPPED3 = b"""
1230	1444	UEsDBAoAAAAAAEOPSVnVlcff5gAAAOYAAAAFAAAALmtleXN7InZlcnNpb24iOjF9CkV4dVBHUDBi
1231	1445	YkxrUVdvWnV5ZUJQRy8xdmM2MCt6MThOa3BsS09ydFAvUTVnQmxkYVpIOG10dTE5VWZFNGdGRGRj
...	...	@@ -1267,6 +1481,16 @@ LmtleXNQSwECHgMKAAAAAABDj0lZ77OVHxcCAAAXAgAAAgAAAAAAAAAAAAAApIEJAQAAMGNQSwEC
1267	1481	HgMKAAAAAABDj0lZGk9LVj8CAAA/AgAAAgAAAAAAAAAAAAAApIFAAwAAMTRQSwECHgMKAAAAAABD
1268	1482	j0lZUkzxBhcCAAAXAgAAAgAAAAAAAAAAAAAApIGfBQAAMTZQSwUGAAAAAAQABADDAAAA1gcAAAAA
1269	1483	"""
	1484	+"""
	1485	+A sample corrupted storeroom archive, encrypted with
	1486	+[`VAULT_MASTER_KEY`][]. The configuration is compressed (zip archive)
	1487	+and then encoded in base64.
	1488	+
	1489	+The archive contains a directory `/services/array/` whose list of child
	1490	+items are not all valid item names. See
	1491	+[`_VAULT_STOREROOM_BROKEN_DIR_CONFIG_ZIPPED3_JAVASCRIPT_SOURCE`][] for
	1492	+the exact script that created this archive.
	1493	+"""
1270	1494
1271	1495	_VAULT_STOREROOM_BROKEN_DIR_CONFIG_ZIPPED4_JAVASCRIPT_SOURCE = """
1272	1496	// Executed in the top-level directory of the vault project code, in Node.js.
...	...	@@ -1277,6 +1501,10 @@ await store._storeroom.put('/dir/subdir/', [])
1277	1501	await store._storeroom.put('/dir/', [])
1278	1502	// The resulting "broken-dir" was then zipped manually.
1279	1503	"""
	1504	+"""
	1505	+The JavaScript source for the script that generated the storeroom
	1506	+archive in [`VAULT_STOREROOM_BROKEN_DIR_CONFIG_ZIPPED4`][].
	1507	+"""
1280	1508	VAULT_STOREROOM_BROKEN_DIR_CONFIG_ZIPPED4 = b"""
1281	1509	UEsDBAoAAAAAAE+5SVloORS+5gAAAOYAAAAFAAAALmtleXN7InZlcnNpb24iOjF9CkV6dWRoNkRQ
1282	1510	YTlNSWFabHZ5TytVYTFuamhjV2hIaTFBU0lKYW5zcXBxVlA0blN2V0twUzdZOUc2bjFSbi8vUnVM
...	...	@@ -1318,24 +1546,73 @@ Weut7lIXAgAAFwIAAAIAAAAAAAAAAAAAAKSBCQEAADAzUEsBAh4DCgAAAAAAT7lJWUV5MuArAgAA
1318	1546	KwIAAAIAAAAAAAAAAAAAAKSBQAMAADEwUEsBAh4DCgAAAAAAT7lJWQ98rH0XAgAAFwIAAAIAAAAA
1319	1547	AAAAAAAAAKSBiwUAADFkUEsFBgAAAAAEAAQAwwAAAMIHAAAAAA==
1320	1548	"""
	1549	+"""
	1550	+A sample corrupted storeroom archive, encrypted with
	1551	+[`VAULT_MASTER_KEY`][]. The configuration is compressed (zip archive)
	1552	+and then encoded in base64.
	1553	+
	1554	+The archive contains two directories `/dir/` and `/dir/subdir/`, where
	1555	+`/dir/subdir/` is a correctly serialized directory, but `/dir/` does not
	1556	+contain `/dir/subdir/` in its list of child items. See
	1557	+[`_VAULT_STOREROOM_BROKEN_DIR_CONFIG_ZIPPED4_JAVASCRIPT_SOURCE`][] for
	1558	+the exact script that created this archive.
	1559	+"""
1321	1560
1322	1561	CANNOT_LOAD_CRYPTOGRAPHY = (
1323	1562	"Cannot load the required Python module 'cryptography'."
1324	1563	)
	1564	+"""
	1565	+The expected `derivepassphrase` error message when the `cryptography`
	1566	+module cannot be loaded, which is needed e.g. by the `export vault`
	1567	+subcommands.
	1568	+"""
1325	1569
1326	1570	skip_if_cryptography_support = pytest.mark.skipif(
1327	1571	importlib.util.find_spec('cryptography') is not None,
1328	1572	reason='cryptography support available; cannot test "no support" scenario',
1329	1573	)
	1574	+"""
	1575	+A cached pytest mark to skip this test if cryptography support is
	1576	+available. Usually this means that the test targets
	1577	+`derivepassphrase`'s fallback functionality, which is not available
	1578	+whenever the primary functionality is.
	1579	+"""
1330	1580	skip_if_no_cryptography_support = pytest.mark.skipif(
1331	1581	importlib.util.find_spec('cryptography') is None,
1332	1582	reason='no "cryptography" support',
1333	1583	)
	1584	+"""
	1585	+A cached pytest mark to skip this test if cryptography support is not
	1586	+available. Usually this means that the test targets the
	1587	+`derivepassphrase export vault` subcommand, whose functionality depends
	1588	+on cryptography support being available.
	1589	+"""
1334	1590
1335	1591
1336	1592	def hypothesis_settings_coverage_compatible(
1337	1593	f: Any = None,
1338	1594	) -> Any:
	1595	+ """Return (or decorate `f` with) coverage-friendly hypothesis settings.
	1596	+
	1597	+ Specifically, we increase the deadline 40-fold if we detect we are
	1598	+ running under coverage testing, because the slow Python trace
	1599	+ function (necessary on PyPy) drastically increases runtime for
	1600	+ hypothesis tests.
	1601	+
	1602	+ In any case, we also reduce the state machine step count to 32
	1603	+ steps per run, because the current state machines defined in the
	1604	+ tests rather benefit from broad testing rather than deep testing.
	1605	+
	1606	+ Args:
	1607	+ f:
	1608	+ An optional object to decorate with these settings.
	1609	+
	1610	+ Returns:
	1611	+ The modified hypothesis settings, as a settings object. If
	1612	+ decorating a function/class, return that function/class
	1613	+ directly, after decorating.
	1614	+
	1615	+ """
1339	1616	settings = (
1340	1617	hypothesis.settings(
1341	1618	# Running under coverage with the Python tracer increases
...	...	@@ -1362,6 +1639,22 @@ def hypothesis_settings_coverage_compatible(
1362	1639	def hypothesis_settings_coverage_compatible_with_caplog(
1363	1640	f: Any = None,
1364	1641	) -> Any:
	1642	+ """Return (or decorate `f` with) coverage-friendly hypothesis settings.
	1643	+
	1644	+ This variant of [`hypothesis_settings_coverage_compatible`][] does
	1645	+ all the same, and additionally disables the check for function
	1646	+ scoped pytest fixtures such as `caplog`.
	1647	+
	1648	+ Args:
	1649	+ f:
	1650	+ An optional object to decorate with these settings.
	1651	+
	1652	+ Returns:
	1653	+ The modified hypothesis settings, as a settings object. If
	1654	+ decorating a function/class, return that function/class
	1655	+ directly, after decorating.
	1656	+
	1657	+ """
1365	1658	parent_settings = hypothesis_settings_coverage_compatible()
1366	1659	settings = hypothesis.settings(
1367	1660	parent=parent_settings,
...	...	@@ -1374,6 +1667,12 @@ def hypothesis_settings_coverage_compatible_with_caplog(
1374	1667
1375	1668
1376	1669	def list_keys(self: Any = None) -> list[_types.SSHKeyCommentPair]:
	1670	+ """Return a list of all SSH test keys, as key/comment pairs.
	1671	+
	1672	+ Intended as a monkeypatching replacement for
	1673	+ [`ssh_agent.SSHAgentClient.list_keys`][].
	1674	+
	1675	+ """
1377	1676	del self # Unused.
1378	1677	Pair = _types.SSHKeyCommentPair # noqa: N806
1379	1678	return [
...	...	@@ -1385,6 +1684,15 @@ def list_keys(self: Any = None) -> list[_types.SSHKeyCommentPair]:
1385	1684	def sign(
1386	1685	self: Any, key: bytes \| bytearray, message: bytes \| bytearray
1387	1686	) -> bytes:
	1687	+ """Return the signature of `message` under `key`.
	1688	+
	1689	+ Can only handle keys in [`SUPPORTED_KEYS`][], and only the vault
	1690	+ UUID as the message.
	1691	+
	1692	+ Intended as a monkeypatching replacement for
	1693	+ [`ssh_agent.SSHAgentClient.sign`][].
	1694	+
	1695	+ """
1388	1696	del self # Unused.
1389	1697	assert message == vault.Vault._UUID
1390	1698	for value in SUPPORTED_KEYS.values():
...	...	@@ -1395,6 +1703,14 @@ def sign(
1395	1703
1396	1704
1397	1705	def list_keys_singleton(self: Any = None) -> list[_types.SSHKeyCommentPair]:
	1706	+ """Return a singleton list of the first supported SSH test key.
	1707	+
	1708	+ The key is returned as a key/comment pair.
	1709	+
	1710	+ Intended as a monkeypatching replacement for
	1711	+ [`ssh_agent.SSHAgentClient.list_keys`][].
	1712	+
	1713	+ """
1398	1714	del self # Unused.
1399	1715	Pair = _types.SSHKeyCommentPair # noqa: N806
1400	1716	list1 = [
...	...	@@ -1405,6 +1721,14 @@ def list_keys_singleton(self: Any = None) -> list[_types.SSHKeyCommentPair]:
1405	1721
1406	1722
1407	1723	def suitable_ssh_keys(conn: Any) -> Iterator[_types.SSHKeyCommentPair]:
	1724	+ """Return a two-item list of SSH test keys (key/comment pairs).
	1725	+
	1726	+ Intended as a monkeypatching replacement for
	1727	+ `cli._get_suitable_ssh_keys` to better script and test the
	1728	+ interactive key selection. When used this way, `derivepassphrase`
	1729	+ believes that only those two keys are loaded and suitable.
	1730	+
	1731	+ """
1408	1732	del conn # Unused.
1409	1733	Pair = _types.SSHKeyCommentPair # noqa: N806
1410	1734	yield from [
...	...	@@ -1419,6 +1743,15 @@ def phrase_from_key(
1419	1743	*,
1420	1744	conn: ssh_agent.SSHAgentClient \| socket.socket \| None = None,
1421	1745	) -> bytes:
	1746	+ """Return the "equivalent master passphrase" for key.
	1747	+
	1748	+ Only works for key [`DUMMY_KEY1`][].
	1749	+
	1750	+ Intended as a monkeypatching replacement for
	1751	+ [`vault.Vault.phrase_from_key`][], bypassing communication with an
	1752	+ actual SSH agent.
	1753	+
	1754	+ """
1422	1755	del conn
1423	1756	if key == DUMMY_KEY1: # pragma: no branch
1424	1757	return DUMMY_PHRASE_FROM_KEY1
...	...	@@ -1431,6 +1764,28 @@ def isolated_config(
1431	1764	runner: click.testing.CliRunner,
1432	1765	main_config_str: str \| None = None,
1433	1766	) -> Iterator[None]:
	1767	+ """Provide an isolated configuration setup, as a context.
	1768	+
	1769	+ This context manager sets up (and changes into) a temporary
	1770	+ directory, which holds the user configuration specified in
	1771	+ `main_config_str`, if any. The manager also ensures that the
	1772	+ environment variables `HOME` and `USERPROFILE` are set, and that
	1773	+ `DERIVEPASSPHRASE_PATH` is unset. Upon exiting the context, the
	1774	+ changes are undone and the temporary directory is removed.
	1775	+
	1776	+ Args:
	1777	+ monkeypatch:
	1778	+ A monkeypatch fixture object.
	1779	+ runner:
	1780	+ A `click` CLI runner harness.
	1781	+ main_config_str:
	1782	+ Optional TOML file contents, to be used as the user
	1783	+ configuration.
	1784	+
	1785	+ Returns:
	1786	+ A context manager, without a return value.
	1787	+
	1788	+ """
1434	1789	prog_name = cli.PROG_NAME
1435	1790	env_name = prog_name.replace(' ', '_').upper() + '_PATH'
1436	1791	# TODO(the-13th-letter): Rewrite using parenthesized with-statements.
...	...	@@ -1461,6 +1816,28 @@ def isolated_vault_config(
1461	1816	vault_config: Any,
1462	1817	main_config_str: str \| None = None,
1463	1818	) -> Iterator[None]:
	1819	+ """Provide an isolated vault configuration setup, as a context.
	1820	+
	1821	+ Uses [`isolated_config`][] internally. Beyond those actions, this
	1822	+ manager also loads the specified vault configuration into the
	1823	+ context.
	1824	+
	1825	+ Args:
	1826	+ monkeypatch:
	1827	+ A monkeypatch fixture object.
	1828	+ runner:
	1829	+ A `click` CLI runner harness.
	1830	+ vault_config:
	1831	+ A valid vault configuration, to be integrated into the
	1832	+ context.
	1833	+ main_config_str:
	1834	+ Optional TOML file contents, to be used as the user
	1835	+ configuration.
	1836	+
	1837	+ Returns:
	1838	+ A context manager, without a return value.
	1839	+
	1840	+ """
1464	1841	with isolated_config(
1465	1842	monkeypatch=monkeypatch, runner=runner, main_config_str=main_config_str
1466	1843	):
...	...	@@ -1477,6 +1854,35 @@ def isolated_vault_exporter_config(
1477	1854	vault_config: str \| bytes \| None = None,
1478	1855	vault_key: str \| None = None,
1479	1856	) -> Iterator[None]:
	1857	+ """Provide an isolated vault configuration setup, as a context.
	1858	+
	1859	+ Works similarly to [`isolated_config`][], except that no user
	1860	+ configuration is accepted or integrated into the context. This
	1861	+ manager also accepts a serialized vault-native configuration and
	1862	+ a vault encryption key to integrate into the context.
	1863	+
	1864	+ Args:
	1865	+ monkeypatch:
	1866	+ A monkeypatch fixture object.
	1867	+ runner:
	1868	+ A `click` CLI runner harness.
	1869	+ vault_config:
	1870	+ An optional serialized vault-native configuration, to be
	1871	+ integrated into the context. If a text string, then the
	1872	+ contents are written to the file `.vault`. If a byte
	1873	+ string, then it is treated as base64-encoded zip file
	1874	+ contents, which---once inside the `.vault` directory---will
	1875	+ be extracted into the current directory.
	1876	+ vault_key:
	1877	+ An optional encryption key presumably for the stored
	1878	+ vault-native configuration. If given, then the environment
	1879	+ variable `VAULT_KEY` will be populated with this key while
	1880	+ the context is active.
	1881	+
	1882	+ Returns:
	1883	+ A context manager, without a return value.
	1884	+
	1885	+ """
1480	1886	# TODO(the-13th-letter): Remove the fallback implementation.
1481	1887	# https://the13thletter.info/derivepassphrase/latest/pycompatibility/#after-eol-py3.10
1482	1888	if TYPE_CHECKING:
...	...	@@ -1535,6 +1941,13 @@ def isolated_vault_exporter_config(
1535	1941
1536	1942
1537	1943	def auto_prompt(args: Any, *kwargs: Any) -> str:
	1944	+ """Return [`DUMMY_PASSPHRASE`][].
	1945	+
	1946	+ Intended as a monkeypatching replacement for
	1947	+ `cli.prompt_for_passphrase` to better script and test the
	1948	+ interactive passphrase queries.
	1949	+
	1950	+ """
1538	1951	del args, kwargs # Unused.
1539	1952	return DUMMY_PASSPHRASE
1540	1953
...	...	@@ -1601,6 +2014,7 @@ class ReadableResult(NamedTuple):
1601	2014
1602	2015	@classmethod
1603	2016	def parse(cls, r: click.testing.Result, /) -> Self:
	2017	+ """Return a readable result object, given a result."""
1604	2018	try:
1605	2019	stderr = r.stderr
1606	2020	except ValueError:
...	...	@@ -1672,6 +2086,29 @@ class ReadableResult(NamedTuple):
1672	2086
1673	2087
1674	2088	def parse_sh_export_line(line: str, *, env_name: str) -> str:
	2089	+ """Parse the output of typical SSH agents' SSH_AUTH_SOCK lines.
	2090	+
	2091	+ Intentionally parses only a small subset of sh(1) syntax which works
	2092	+ with current OpenSSH and PuTTY output. We require exactly one
	2093	+ variable setting, and one export instruction, both on the same line,
	2094	+ and perhaps combined into one statement. Terminating semicolons
	2095	+ after each command are ignored.
	2096	+
	2097	+ Args:
	2098	+ line:
	2099	+ A line of sh(1) script to parse.
	2100	+ env_name:
	2101	+ The name of the environment variable to expect.
	2102	+
	2103	+ Returns:
	2104	+ The parsed environment variable value.
	2105	+
	2106	+ Raises:
	2107	+ ValueError:
	2108	+ Cannot parse the sh script. Perhaps it is too complex,
	2109	+ perhaps it is malformed.
	2110	+
	2111	+ """
1675	2112	line = line.rstrip('\r\n')
1676	2113	shlex_parser = shlex.shlex(
1677	2114	instream=line, posix=True, punctuation_chars=True

tests/conftest.py

Zeige Datei @ 717c79a

@@ -70,7 +70,28 @@ class SpawnFunc(Protocol):
         self,
         executable: str | None,
         env: dict[str, str],
-    ) -> subprocess.Popen[str] | None: ...
+    ) -> subprocess.Popen[str] | None:
+        """Spawn the SSH agent.
+
+        Args:
+            executable:
+                The respective SSH agent executable.
+            env:
+                The new environment for the respective agent.  Should
+                typically not include an SSH_AUTH_SOCK variable.
+
+        Returns:
+            The spawned SSH agent subprocess.  If the executable is
+            `None`, then return `None` directly.
+
+            It is the caller's responsibility to clean up the spawned
+            subprocess.
+
+        Raises:
+            OSError:
+                The [`subprocess.Popen`][] call failed.  See there.
+
+        """
 
 
 def _spawn_pageant(  # pragma: no cover
@@ -190,12 +211,27 @@ _spawn_handlers = [
     ('ssh-agent', _spawn_openssh_agent, tests.KnownSSHAgent.OpenSSHAgent),
     ('(system)', _spawn_noop, tests.KnownSSHAgent.UNKNOWN),
 ]
+"""
+The standard registry of agent spawning functions.
+"""
 
 Popen = TypeVar('Popen', bound=subprocess.Popen)
 
 
 @contextlib.contextmanager
 def _terminate_on_exit(proc: Popen) -> Iterator[Popen]:
+    """Terminate and wait for the subprocess upon exiting the context.
+
+    Args:
+        proc:
+            The subprocess to manage.
+
+    Returns:
+        A context manager.  Upon entering the manager, return the
+        managed subprocess.  Upon exiting the manager, terminate the
+        process and wait for it.
+
+    """
     try:
         yield proc
     finally:
@@ -204,7 +240,7 @@ def _terminate_on_exit(proc: Popen) -> Iterator[Popen]:
 
 
 class CannotSpawnError(RuntimeError):
-    pass
+    """Cannot spawn the SSH agent."""
 
 
 def _spawn_named_agent(
@@ -212,6 +248,41 @@ def _spawn_named_agent(
     spawn_func: SpawnFunc,
     agent_type: tests.KnownSSHAgent,
 ) -> Iterator[tests.SpawnedSSHAgentInfo]:  # pragma: no cover
+    """Spawn the named SSH agent and check that it is operational.
+
+    Using the correct agent-specific spawn function from the
+    [`spawn_handlers`][] registry, spawn the named SSH agent (according
+    to its declared type), then set up the communication channel and
+    yield an SSH agent client connected to this agent.  After resuming,
+    tear down the communication channel and terminate the SSH agent.
+
+    The SSH agent's instructions for setting up the communication
+    channel are parsed with [`tests.parse_sh_export_line`][].  See the
+    caveats there.
+
+    Args:
+        exec_name:
+            The executable to spawn.
+        spawn_func:
+            The agent-specific spawn function.
+        agent_type:
+            The agent type.
+
+    Yields:
+        A 3-tuple containing the agent type, an SSH agent client
+        connected to this agent, and a boolean indicating whether this
+        agent was actually spawned in an isolated manner.
+
+        Only one tuple will ever be yielded.  After resuming, the
+        connected client will be torn down, as will the agent if it was
+        isolated.
+
+    Raises:
+        CannotSpawnError:
+            We failed to spawn the agent or otherwise set up the
+            environment/communication channel/etc.
+
+    """
     # pytest's fixture system does not seem to guarantee that
     # environment variables are set up correctly if nested and
     # parametrized fixtures are used: it is possible that "outer"

tests/test_derivepassphrase_cli.py

Zeige Datei @ 717c79a

@@ -242,6 +242,15 @@ def vault_config_exporter_shell_interpreter(  # noqa: C901
     command: click.BaseCommand | None = None,
     runner: click.testing.CliRunner | None = None,
 ) -> Iterator[click.testing.Result]:
+    """A rudimentary sh(1) interpreter for `--export-as=sh` output.
+
+    Assumes a script as emitted by `derivepassphrase vault
+    --export-as=sh --export -` and interprets the calls to
+    `derivepassphrase vault` within.  (One call per line, skips all
+    other lines.)  Also has rudimentary support for (quoted)
+    here-documents using `HERE` as the marker.
+
+    """
     if isinstance(script, str):  # pragma: no cover
         script = script.splitlines(False)
     if prog_name_list is None:  # pragma: no cover
@@ -285,6 +294,8 @@ def vault_config_exporter_shell_interpreter(  # noqa: C901
 
 
 class TestAllCLI:
+    """Tests uniformly for all command-line interfaces."""
+
     @pytest.mark.parametrize(
         ['command', 'non_eager_arguments'],
         [
@@ -342,6 +353,7 @@ class TestAllCLI:
         arguments: list[str],
         non_eager_arguments: list[str],
     ) -> None:
+        """Eager options terminate option and argument processing."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(
             monkeypatch=monkeypatch,
@@ -389,6 +401,7 @@ class TestAllCLI:
         command_line: list[str],
         input: str | None,
     ) -> None:
+        """Respect the `NO_COLOR` and `FORCE_COLOR` environment variables."""
         # Force color on if force_color.  Otherwise force color off if
         # no_color.  Otherwise set color if and only if we have a TTY.
         color = force_color or not no_color if isatty else force_color
@@ -420,10 +433,13 @@ class TestAllCLI:
 
 
 class TestCLI:
+    """Tests for the `derivepassphrase vault` command-line interface."""
+
     def test_200_help_output(
         self,
         monkeypatch: pytest.MonkeyPatch,
     ) -> None:
+        """The `--help` option emits help text."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(
             monkeypatch=monkeypatch,
@@ -446,6 +462,7 @@ class TestCLI:
         self,
         monkeypatch: pytest.MonkeyPatch,
     ) -> None:
+        """The `--version` option emits version information."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(
             monkeypatch=monkeypatch,
@@ -470,6 +487,7 @@ class TestCLI:
     def test_201_disable_character_set(
         self, monkeypatch: pytest.MonkeyPatch, charset_name: str
     ) -> None:
+        """Named character classes can be disabled on the command-line."""
         monkeypatch.setattr(cli, '_prompt_for_passphrase', tests.auto_prompt)
         option = f'--{charset_name}'
         charset = vault.Vault._CHARSETS[charset_name].decode('ascii')
@@ -494,6 +512,7 @@ class TestCLI:
     def test_202_disable_repetition(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
+        """Character repetition can be disabled on the command-line."""
         monkeypatch.setattr(cli, '_prompt_for_passphrase', tests.auto_prompt)
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(
@@ -546,6 +565,7 @@ class TestCLI:
         monkeypatch: pytest.MonkeyPatch,
         config: _types.VaultConfig,
     ) -> None:
+        """A stored configured SSH key will be used."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch, runner=runner, vault_config=config
@@ -573,6 +593,7 @@ class TestCLI:
     def test_204b_key_from_command_line(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
+        """An SSH key requested on the command-line will be used."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,
@@ -633,6 +654,7 @@ class TestCLI:
         config: dict[str, Any],
         key_index: int,
     ) -> None:
+        """A command-line SSH key will override the configured key."""
         with monkeypatch.context():
             monkeypatch.setenv('SSH_AUTH_SOCK', running_ssh_agent.socket)
             monkeypatch.setattr(
@@ -661,6 +683,7 @@ class TestCLI:
         monkeypatch: pytest.MonkeyPatch,
         running_ssh_agent: tests.RunningSSHAgentInfo,
     ) -> None:
+        """A command-line passphrase will override the configured key."""
         with monkeypatch.context():
             monkeypatch.setenv('SSH_AUTH_SOCK', running_ssh_agent.socket)
             monkeypatch.setattr(
@@ -738,6 +761,7 @@ class TestCLI:
         config: _types.VaultConfig,
         command_line: list[str],
     ) -> None:
+        """Configuring a passphrase atop an SSH key works, but warns."""
         with monkeypatch.context():
             monkeypatch.setenv('SSH_AUTH_SOCK', running_ssh_agent.socket)
             monkeypatch.setattr(
@@ -790,6 +814,7 @@ class TestCLI:
     def test_210_invalid_argument_range(
         self, monkeypatch: pytest.MonkeyPatch, option: str
     ) -> None:
+        """Requesting invalidly many characters from a class fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(
             monkeypatch=monkeypatch,
@@ -829,6 +854,7 @@ class TestCLI:
         input: str | None,
         check_success: bool,
     ) -> None:
+        """We require or forbid a service argument, depending on options."""
         monkeypatch.setattr(cli, '_prompt_for_passphrase', tests.auto_prompt)
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
@@ -879,6 +905,12 @@ class TestCLI:
         monkeypatch: pytest.MonkeyPatch,
         caplog: pytest.LogCaptureFixture,
     ) -> None:
+        """Using an empty service name (where permissible) warns.
+
+        Only the `--config` option can optionally take a service name.
+
+        """
+
         def is_expected_warning(record: tuple[str, int, str]) -> bool:
             return is_harmless_config_import_warning(
                 record
@@ -940,6 +972,7 @@ class TestCLI:
         options: list[str],
         service: bool | None,
     ) -> None:
+        """Incompatible options are detected."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(
             monkeypatch=monkeypatch,
@@ -970,6 +1003,7 @@ class TestCLI:
         caplog: pytest.LogCaptureFixture,
         config: Any,
     ) -> None:
+        """Importing a configuration works."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,
@@ -1006,6 +1040,11 @@ class TestCLI:
         caplog: pytest.LogCaptureFixture,
         conf: tests.VaultTestConfig,
     ) -> None:
+        """Importing a smudged configuration works.
+
+        Tested via hypothesis.
+
+        """
         config = conf.config
         config2 = copy.deepcopy(config)
         _types.clean_up_falsy_vault_config_values(config2)
@@ -1036,6 +1075,7 @@ class TestCLI:
         self,
         monkeypatch: pytest.MonkeyPatch,
     ) -> None:
+        """Importing an invalid config fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(monkeypatch=monkeypatch, runner=runner):
             result_ = runner.invoke(
@@ -1053,6 +1093,7 @@ class TestCLI:
         self,
         monkeypatch: pytest.MonkeyPatch,
     ) -> None:
+        """Importing an invalid config fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(monkeypatch=monkeypatch, runner=runner):
             result_ = runner.invoke(
@@ -1070,6 +1111,7 @@ class TestCLI:
         self,
         monkeypatch: pytest.MonkeyPatch,
     ) -> None:
+        """Importing an invalid config fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         # `isolated_vault_config` validates the configuration.  So, to
         # pass an actual broken configuration, we must open the
@@ -1102,6 +1144,7 @@ class TestCLI:
         monkeypatch: pytest.MonkeyPatch,
         export_options: list[str],
     ) -> None:
+        """Exporting the default, empty config works."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(monkeypatch=monkeypatch, runner=runner):
             cli._config_filename(subsystem='vault').unlink(missing_ok=True)
@@ -1129,6 +1172,7 @@ class TestCLI:
         monkeypatch: pytest.MonkeyPatch,
         export_options: list[str],
     ) -> None:
+        """Exporting an invalid config fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch, runner=runner, vault_config={}
@@ -1156,6 +1200,7 @@ class TestCLI:
         monkeypatch: pytest.MonkeyPatch,
         export_options: list[str],
     ) -> None:
+        """Exporting an invalid config fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(monkeypatch=monkeypatch, runner=runner):
             config_file = cli._config_filename(subsystem='vault')
@@ -1184,6 +1229,7 @@ class TestCLI:
         monkeypatch: pytest.MonkeyPatch,
         export_options: list[str],
     ) -> None:
+        """Exporting an invalid config fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(monkeypatch=monkeypatch, runner=runner):
             dname = cli._config_filename(subsystem=None)
@@ -1210,6 +1256,7 @@ class TestCLI:
         monkeypatch: pytest.MonkeyPatch,
         export_options: list[str],
     ) -> None:
+        """Exporting an invalid config fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(monkeypatch=monkeypatch, runner=runner):
             config_dir = cli._config_filename(subsystem=None)
@@ -1232,6 +1279,7 @@ class TestCLI:
     def test_220_edit_notes_successfully(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
+        """Editing notes works."""
         edit_result = """
 
 # - - - - - >8 - - - - - >8 - - - - - >8 - - - - - >8 - - - - -
@@ -1263,6 +1311,7 @@ contents go here
     def test_221_edit_notes_noop(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
+        """Abandoning edited notes works."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,
@@ -1283,9 +1332,16 @@ contents go here
                 config = json.load(infile)
             assert config == {'global': {'phrase': 'abc'}, 'services': {}}
 
+    # TODO(the-13th-letter): Keep this behavior or not, with or without
+    # warning?
     def test_222_edit_notes_marker_removed(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
+        """Removing the notes marker still saves the notes.
+
+        TODO: Keep this behavior or not, with or without warning?
+
+        """
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,
@@ -1312,6 +1368,7 @@ contents go here
     def test_223_edit_notes_abort(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
+        """Aborting editing notes works."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,
@@ -1388,6 +1445,7 @@ contents go here
         input: str,
         result_config: Any,
     ) -> None:
+        """Storing valid settings via `--config` works."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,
@@ -1449,6 +1507,7 @@ contents go here
         input: str,
         err_text: str,
     ) -> None:
+        """Storing invalid settings via `--config` fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,
@@ -1473,6 +1532,7 @@ contents go here
         self,
         monkeypatch: pytest.MonkeyPatch,
     ) -> None:
+        """Not selecting an SSH key during `--config --key` fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,
@@ -1500,6 +1560,7 @@ contents go here
         monkeypatch: pytest.MonkeyPatch,
         skip_if_no_af_unix_support: None,
     ) -> None:
+        """Not running an SSH agent during `--config --key` fails."""
         del skip_if_no_af_unix_support
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
@@ -1522,6 +1583,7 @@ contents go here
         self,
         monkeypatch: pytest.MonkeyPatch,
     ) -> None:
+        """Not running a reachable SSH agent during `--config --key` fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,
@@ -1546,6 +1608,7 @@ contents go here
         monkeypatch: pytest.MonkeyPatch,
         try_race_free_implementation: bool,
     ) -> None:
+        """Using a read-only configuration file with `--config` fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,
@@ -1570,6 +1633,7 @@ contents go here
         self,
         monkeypatch: pytest.MonkeyPatch,
     ) -> None:
+        """OS-erroring with `--config` fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,
@@ -1597,6 +1661,7 @@ contents go here
         self,
         monkeypatch: pytest.MonkeyPatch,
     ) -> None:
+        """Issuing conflicting settings to `--config` fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,
@@ -1624,6 +1689,7 @@ contents go here
         monkeypatch: pytest.MonkeyPatch,
         running_ssh_agent: tests.RunningSSHAgentInfo,
     ) -> None:
+        """Not holding any SSH keys during `--config --key` fails."""
         del running_ssh_agent
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
@@ -1654,6 +1720,7 @@ contents go here
         monkeypatch: pytest.MonkeyPatch,
         running_ssh_agent: tests.RunningSSHAgentInfo,
     ) -> None:
+        """The SSH agent erroring during `--config --key` fails."""
         del running_ssh_agent
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
@@ -1681,6 +1748,7 @@ contents go here
         monkeypatch: pytest.MonkeyPatch,
         running_ssh_agent: tests.RunningSSHAgentInfo,
     ) -> None:
+        """The SSH agent refusing during `--config --key` fails."""
         del running_ssh_agent
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
@@ -1706,6 +1774,7 @@ contents go here
         )
 
     def test_226_no_arguments(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Calling `derivepassphrase vault` without any arguments fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(
             monkeypatch=monkeypatch,
@@ -1722,6 +1791,7 @@ contents go here
     def test_226a_no_passphrase_or_key(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
+        """Deriving a passphrase without a passphrase or key fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(
             monkeypatch=monkeypatch,
@@ -1740,7 +1810,13 @@ contents go here
     def test_230_config_directory_nonexistant(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
-        """https://github.com/the-13th-letter/derivepassphrase/issues/6"""
+        """Running without an existing config directory works.
+
+        This is a regression test; see [issue\u00a0#6][] for context.
+
+        [issue #6]: https://github.com/the-13th-letter/derivepassphrase/issues/6
+
+        """
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(
             monkeypatch=monkeypatch,
@@ -1771,7 +1847,16 @@ contents go here
     def test_230a_config_directory_not_a_file(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
-        """https://github.com/the-13th-letter/derivepassphrase/issues/6"""
+        """Erroring without an existing config directory errors normally.
+
+        That is, the missing configuration directory does not cause any
+        errors by itself.
+
+        This is a regression test; see [issue\u00a0#6][] for context.
+
+        [issue #6]: https://github.com/the-13th-letter/derivepassphrase/issues/6
+
+        """
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(
             monkeypatch=monkeypatch,
@@ -1802,6 +1887,7 @@ contents go here
     def test_230b_store_config_custom_error(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
+        """Storing the configuration reacts even to weird errors."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(
             monkeypatch=monkeypatch,
@@ -1933,6 +2019,7 @@ contents go here
         input: str | None,
         warning_message: str,
     ) -> None:
+        """Using unnormalized Unicode passphrases warns."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,
@@ -2003,6 +2090,7 @@ contents go here
         input: str | None,
         error_message: str,
     ) -> None:
+        """Using unknown Unicode normalization forms fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,
@@ -2044,6 +2132,7 @@ contents go here
         monkeypatch: pytest.MonkeyPatch,
         command_line: list[str],
     ) -> None:
+        """Using unknown Unicode normalization forms in the config fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,
@@ -2077,6 +2166,7 @@ contents go here
         self,
         monkeypatch: pytest.MonkeyPatch,
     ) -> None:
+        """Loading a user configuration file in an invalid format fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,
@@ -2101,6 +2191,7 @@ contents go here
         self,
         monkeypatch: pytest.MonkeyPatch,
     ) -> None:
+        """Querying the SSH agent without `AF_UNIX` support fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,
@@ -2123,6 +2214,8 @@ contents go here
 
 
 class TestCLIUtils:
+    """Tests for command-line utility functions."""
+
     @pytest.mark.parametrize(
         'config',
         [
@@ -2145,6 +2238,7 @@ class TestCLIUtils:
     def test_100_load_config(
         self, monkeypatch: pytest.MonkeyPatch, config: Any
     ) -> None:
+        """`cli._load_config` works for valid configurations."""
         runner = click.testing.CliRunner()
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch, runner=runner, vault_config=config
@@ -2157,6 +2251,7 @@ class TestCLIUtils:
     def test_110_save_bad_config(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
+        """`cli._save_config` fails for bad configurations."""
         runner = click.testing.CliRunner()
         # TODO(the-13th-letter): Rewrite using parenthesized
         # with-statements.
@@ -2173,6 +2268,7 @@ class TestCLIUtils:
             cli._save_config(None)  # type: ignore[arg-type]
 
     def test_111_prompt_for_selection_multiple(self) -> None:
+        """`cli._prompt_for_selection` works in the "multiple" case."""
         @click.command()
         @click.option('--heading', default='Our menu:')
         @click.argument('items', nargs=-1)
@@ -2248,6 +2344,7 @@ Your selection? (1-10, leave empty to abort):\x20
         ), 'expected known output'
 
     def test_112_prompt_for_selection_single(self) -> None:
+        """`cli._prompt_for_selection` works in the "single" case."""
         @click.command()
         @click.option('--item', default='baked beans')
         @click.argument('prompt')
@@ -2295,6 +2392,7 @@ Boo.
     def test_113_prompt_for_passphrase(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
+        """`cli._prompt_for_passphrase` works."""
         monkeypatch.setattr(
             click,
             'prompt',
@@ -2315,6 +2413,12 @@ Boo.
         caplog: pytest.LogCaptureFixture,
         capsys: pytest.CaptureFixture[str],
     ) -> None:
+        """The standard logging context manager works.
+
+        It registers its handlers, once, and emits formatted calls to
+        standard error prefixed with the program name.
+
+        """
         prog_name = cli.StandardCLILogging.prog_name
         package_name = cli.StandardCLILogging.package_name
         logger = logging.getLogger(package_name)
@@ -2371,6 +2475,14 @@ Boo.
         caplog: pytest.LogCaptureFixture,
         capsys: pytest.CaptureFixture[str],
     ) -> None:
+        """The standard warnings logging context manager works.
+
+        It registers its handlers, once, and emits formatted calls to
+        standard error prefixed with the program name.  It also adheres
+        to the global warnings filter concerning which messages it
+        actually emits to standard error.
+
+        """
         warnings_cm = cli.StandardCLILogging.ensure_standard_warnings_logging()
         THE_FUTURE = 'the future will be here sooner than you think'  # noqa: N806
         JUST_TESTING = 'just testing whether warnings work'  # noqa: N806
@@ -2419,6 +2531,19 @@ Boo.
         self,
         config: Any,
     ) -> None:
+        """Emits a config in sh(1) format, then reads it back to verify it.
+
+        This function exports the configuration, sets up a new
+        enviroment, then calls
+        [`vault_config_exporter_shell_interpreter`][] on the export
+        script, verifying that each command ran successfully and that
+        the final configuration matches the initial one.
+
+        Args:
+            config:
+                The configuration to emit and read back.
+
+        """
         prog_name_list = ('derivepassphrase', 'vault')
         with io.StringIO() as outfile:
             cli._print_config_as_sh_script(
@@ -2464,6 +2589,15 @@ Boo.
         global_config_settable: _types.VaultConfigServicesSettings,
         global_config_importable: _types.VaultConfigServicesSettings,
     ) -> None:
+        """Exporting configurations as sh(1) script works.
+
+        Here, we check global-only configurations which use both
+        settings settable via `--config` and settings requiring
+        `--import`.
+
+        The actual verification is done by [`_export_as_sh_helper`][].
+
+        """
         config: _types.VaultConfig = {
             'global': global_config_settable | global_config_importable,
             'services': {},
@@ -2497,6 +2631,14 @@ Boo.
         self,
         global_config_importable: _types.VaultConfigServicesSettings,
     ) -> None:
+        """Exporting configurations as sh(1) script works.
+
+        Here, we check global-only configurations which only use
+        settings requiring `--import`.
+
+        The actual verification is done by [`_export_as_sh_helper`][].
+
+        """
         config: _types.VaultConfig = {
             'global': global_config_importable,
             'services': {},
@@ -2551,6 +2693,15 @@ Boo.
         service_config_settable: _types.VaultConfigServicesSettings,
         service_config_importable: _types.VaultConfigServicesSettings,
     ) -> None:
+        """Exporting configurations as sh(1) script works.
+
+        Here, we check service-only configurations which use both
+        settings settable via `--config` and settings requiring
+        `--import`.
+
+        The actual verification is done by [`_export_as_sh_helper`][].
+
+        """
         config: _types.VaultConfig = {
             'services': {
                 service_name: (
@@ -2604,6 +2755,14 @@ Boo.
         service_name: str,
         service_config_importable: _types.VaultConfigServicesSettings,
     ) -> None:
+        """Exporting configurations as sh(1) script works.
+
+        Here, we check service-only configurations which only use
+        settings requiring `--import`.
+
+        The actual verification is done by [`_export_as_sh_helper`][].
+
+        """
         config: _types.VaultConfig = {
             'services': {
                 service_name: service_config_importable,
@@ -2649,6 +2808,7 @@ Boo.
         config: _types.VaultConfig,
         result_config: _types.VaultConfig,
     ) -> None:
+        """Repeatedly removing the same parts of a configuration works."""
         runner = click.testing.CliRunner(mix_stderr=False)
         for start_config in [config, result_config]:
             with tests.isolated_vault_config(
@@ -2672,6 +2832,7 @@ Boo.
                 assert config_readback == result_config
 
     def test_204_phrase_from_key_manually(self) -> None:
+        """The dummy service, key and config settings are consistent."""
         assert (
             vault.Vault(
                 phrase=DUMMY_PHRASE_FROM_KEY1, **DUMMY_CONFIG_SETTINGS
@@ -2691,6 +2852,7 @@ Boo.
         vfunc: Callable[[click.Context, click.Parameter, Any], int | None],
         input: int,
     ) -> None:
+        """Command-line argument constraint validation works."""
         ctx = cli.derivepassphrase_vault.make_context(cli.PROG_NAME, [])
         param = cli.derivepassphrase_vault.params[0]
         assert vfunc(ctx, param, input) == input
@@ -2702,6 +2864,7 @@ Boo.
         running_ssh_agent: tests.RunningSSHAgentInfo,
         conn_hint: str,
     ) -> None:
+        """`cli._get_suitable_ssh_keys` works."""
         with monkeypatch.context():
             monkeypatch.setenv('SSH_AUTH_SOCK', running_ssh_agent.socket)
             monkeypatch.setattr(
@@ -2737,6 +2900,8 @@ Boo.
         skip_if_no_af_unix_support: None,
         ssh_agent_client_with_test_keys_loaded: ssh_agent.SSHAgentClient,
     ) -> None:
+        """All errors in `cli._key_to_phrase` are handled."""
+
         class ErrCallback(BaseException):
             def __init__(self, *args: Any, **kwargs: Any) -> None:
                 super().__init__(*args[:1])
@@ -2818,7 +2983,10 @@ Boo.
 # TODO(the-13th-letter): Remove this class in v1.0.
 # https://the13thletter.info/derivepassphrase/latest/upgrade-notes/#upgrading-to-v1.0
 class TestCLITransition:
+    """Transition tests for the command-line interface up to v1.0."""
+
     def test_100_help_output(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """The top-level help text mentions subcommands."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(
             monkeypatch=monkeypatch,
@@ -2835,6 +3003,7 @@ class TestCLITransition:
     def test_101_help_output_export(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
+        """The "export" subcommand help text mentions subcommands."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(
             monkeypatch=monkeypatch,
@@ -2853,6 +3022,7 @@ class TestCLITransition:
     def test_102_help_output_export_vault(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
+        """The "export vault" subcommand help text has known content."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(
             monkeypatch=monkeypatch,
@@ -2871,6 +3041,7 @@ class TestCLITransition:
     def test_103_help_output_vault(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
+        """The "vault" subcommand help text has known content."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(
             monkeypatch=monkeypatch,
@@ -2911,6 +3082,7 @@ class TestCLITransition:
     def test_110_load_config_backup(
         self, monkeypatch: pytest.MonkeyPatch, config: Any
     ) -> None:
+        """Loading the old settings file works."""
         runner = click.testing.CliRunner()
         with tests.isolated_config(monkeypatch=monkeypatch, runner=runner):
             cli._config_filename(subsystem='old settings.json').write_text(
@@ -2940,6 +3112,7 @@ class TestCLITransition:
     def test_111_migrate_config(
         self, monkeypatch: pytest.MonkeyPatch, config: Any
     ) -> None:
+        """Migrating the old settings file works."""
         runner = click.testing.CliRunner()
         with tests.isolated_config(monkeypatch=monkeypatch, runner=runner):
             cli._config_filename(subsystem='old settings.json').write_text(
@@ -2969,6 +3142,7 @@ class TestCLITransition:
     def test_112_migrate_config_error(
         self, monkeypatch: pytest.MonkeyPatch, config: Any
     ) -> None:
+        """Migrating the old settings file atop a directory fails."""
         runner = click.testing.CliRunner()
         with tests.isolated_config(monkeypatch=monkeypatch, runner=runner):
             cli._config_filename(subsystem='old settings.json').write_text(
@@ -3004,6 +3178,7 @@ class TestCLITransition:
     def test_113_migrate_config_error_bad_config_value(
         self, monkeypatch: pytest.MonkeyPatch, config: Any
     ) -> None:
+        """Migrating an invalid old settings file fails."""
         runner = click.testing.CliRunner()
         with tests.isolated_config(monkeypatch=monkeypatch, runner=runner):
             cli._config_filename(subsystem='old settings.json').write_text(
@@ -3017,6 +3192,7 @@ class TestCLITransition:
         monkeypatch: pytest.MonkeyPatch,
         caplog: pytest.LogCaptureFixture,
     ) -> None:
+        """Forwarding arguments from "export" to "export vault" works."""
         pytest.importorskip('cryptography', minversion='38.0')
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_exporter_config(
@@ -3045,6 +3221,7 @@ class TestCLITransition:
         monkeypatch: pytest.MonkeyPatch,
         caplog: pytest.LogCaptureFixture,
     ) -> None:
+        """Deferring from "export" to "export vault" works."""
         pytest.importorskip('cryptography', minversion='38.0')
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(
@@ -3075,6 +3252,7 @@ class TestCLITransition:
         caplog: pytest.LogCaptureFixture,
         charset_name: str,
     ) -> None:
+        """Forwarding arguments from top-level to "vault" works."""
         monkeypatch.setattr(cli, '_prompt_for_passphrase', tests.auto_prompt)
         option = f'--{charset_name}'
         charset = vault.Vault._CHARSETS[charset_name].decode('ascii')
@@ -3107,6 +3285,7 @@ class TestCLITransition:
         monkeypatch: pytest.MonkeyPatch,
         caplog: pytest.LogCaptureFixture,
     ) -> None:
+        """Deferring from top-level to "vault" works."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(
             monkeypatch=monkeypatch,
@@ -3134,6 +3313,7 @@ class TestCLITransition:
         monkeypatch: pytest.MonkeyPatch,
         caplog: pytest.LogCaptureFixture,
     ) -> None:
+        """Exporting from (and migrating) the old settings file works."""
         caplog.set_level(logging.INFO)
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(
@@ -3167,6 +3347,7 @@ class TestCLITransition:
         monkeypatch: pytest.MonkeyPatch,
         caplog: pytest.LogCaptureFixture,
     ) -> None:
+        """Exporting from (and not migrating) the old settings file fails."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_config(
             monkeypatch=monkeypatch,
@@ -3208,6 +3389,7 @@ class TestCLITransition:
         self,
         monkeypatch: pytest.MonkeyPatch,
     ) -> None:
+        """Completing service names from the old settings file works."""
         runner = click.testing.CliRunner(mix_stderr=False)
         config = {'services': {DUMMY_SERVICE: DUMMY_CONFIG_SETTINGS.copy()}}
         with tests.isolated_vault_config(
@@ -3227,6 +3409,7 @@ class TestCLITransition:
 
 
 _known_services = (DUMMY_SERVICE, 'email', 'bank', 'work')
+"""Known service names.  Used for the [`ConfigManagementStateMachine`][]."""
 _valid_properties = (
     'length',
     'repeat',
@@ -3237,12 +3420,22 @@ _valid_properties = (
     'dash',
     'symbol',
 )
+"""Known vault properties.  Used for the [`ConfigManagementStateMachine`][]."""
 
 
 def _build_reduced_vault_config_settings(
     config: _types.VaultConfigServicesSettings,
     keys_to_purge: frozenset[str],
 ) -> _types.VaultConfigServicesSettings:
+    """Return a service settings object with certain keys pruned.
+
+    Args:
+        config:
+            The original service settings object.
+        keys_to_purge:
+            The keys to purge from the settings object.
+
+    """
     config2 = copy.deepcopy(config)
     for key in keys_to_purge:
         config2.pop(key, None)  # type: ignore[misc]
@@ -3257,12 +3450,14 @@ _services_strategy = strategies.builds(
         max_size=7,
     ),
 )
+"""A hypothesis strategy to build incomplete service configurations."""
 
 
 def _assemble_config(
     global_data: _types.VaultConfigGlobalSettings,
     service_data: list[tuple[str, _types.VaultConfigServicesSettings]],
 ) -> _types.VaultConfig:
+    """Return a vault config using the global and service data."""
     services_dict = dict(service_data)
     return (
         {'global': global_data, 'services': services_dict}
@@ -3276,6 +3471,21 @@ def _draw_service_name_and_data(
     draw: hypothesis.strategies.DrawFn,
     num_entries: int,
 ) -> tuple[tuple[str, _types.VaultConfigServicesSettings], ...]:
+    """Draw a service name and settings, as a hypothesis strategy.
+
+    Will draw service names from [`_known_services`][] and service
+    settings via [`_services_strategy`][].
+
+    Args:
+        draw:
+            The `draw` function, as provided for by hypothesis.
+        num_entries:
+            The number of services to draw.
+
+    Returns:
+        A sequence of pairs of service names and service settings.
+
+    """
     possible_services = list(_known_services)
     selected_services: list[str] = []
     for _ in range(num_entries):
@@ -3296,11 +3506,26 @@ _vault_full_config = strategies.builds(
         max_value=4,
     ).flatmap(_draw_service_name_and_data),
 )
+"""A hypothesis strategy to build full vault configurations."""
 
 
 @tests.hypothesis_settings_coverage_compatible
 class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
+    """A state machine recording changes in the vault configuration.
+
+    Record possible configuration states in bundles, then in each rule,
+    take a configuration and manipulate it somehow.
+
+    Attributes:
+        setting:
+            A bundle for single-service settings.
+        configuration:
+            A bundle for full vault configurations.
+
+    """
+
     def __init__(self) -> None:
+        """Initialize self, set up context managers and enter them."""
         super().__init__()
         self.runner = click.testing.CliRunner(mix_stderr=False)
         self.exit_stack = contextlib.ExitStack().__enter__()
@@ -3315,8 +3540,14 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
             )
         )
 
-    setting = stateful.Bundle('setting')
-    configuration = stateful.Bundle('configuration')
+    setting: stateful.Bundle[_types.VaultConfigServicesSettings] = (
+        stateful.Bundle('setting')
+    )
+    """"""
+    configuration: stateful.Bundle[_types.VaultConfig] = stateful.Bundle(
+        'configuration'
+    )
+    """"""
 
     @stateful.initialize(
         target=configuration,
@@ -3329,7 +3560,8 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
     def declare_initial_configs(
         self,
         configs: Iterable[_types.VaultConfig],
-    ) -> Iterable[_types.VaultConfig]:
+    ) -> stateful.MultipleResults[_types.VaultConfig]:
+        """Initialize the configuration bundle with eight configurations."""
         return stateful.multiple(*configs)
 
     @stateful.initialize(
@@ -3343,7 +3575,8 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
     def extract_initial_settings(
         self,
         configs: list[_types.VaultConfig],
-    ) -> Iterable[_types.VaultConfigServicesSettings]:
+    ) -> stateful.MultipleResults[_types.VaultConfigServicesSettings]:
+        """Initialize the settings bundle with four service settings."""
         settings: list[_types.VaultConfigServicesSettings] = []
         for c in configs:
             settings.extend(c['services'].values())
@@ -3381,6 +3614,26 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
         maybe_unset: set[str],
         overwrite: bool,
     ) -> _types.VaultConfig:
+        """Set the global settings of a configuration.
+
+        Args:
+            config:
+                The configuration to edit.
+            setting:
+                The new global settings.
+            maybe_unset:
+                Settings keys to additionally unset, if not already
+                present in the new settings.  Corresponds to the
+                `--unset` command-line argument.
+            overwrite:
+                Overwrite the settings object if true, or merge if
+                false.  Corresponds to the `--overwrite-existing` and
+                `--merge-existing` command-line arguments.
+
+        Returns:
+            The amended configuration.
+
+        """
         cli._save_config(config)
         config_global = config.get('global', {})
         maybe_unset = set(maybe_unset) - setting.keys()
@@ -3432,6 +3685,28 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
         maybe_unset: set[str],
         overwrite: bool,
     ) -> _types.VaultConfig:
+        """Set the named service settings for a configuration.
+
+        Args:
+            config:
+                The configuration to edit.
+            service:
+                The name of the service to set.
+            setting:
+                The new service settings.
+            maybe_unset:
+                Settings keys to additionally unset, if not already
+                present in the new settings.  Corresponds to the
+                `--unset` command-line argument.
+            overwrite:
+                Overwrite the settings object if true, or merge if
+                false.  Corresponds to the `--overwrite-existing` and
+                `--merge-existing` command-line arguments.
+
+        Returns:
+            The amended configuration.
+
+        """
         cli._save_config(config)
         config_service = config['services'].get(service, {})
         maybe_unset = set(maybe_unset) - setting.keys()
@@ -3473,6 +3748,16 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
         self,
         config: _types.VaultConfig,
     ) -> _types.VaultConfig:
+        """Purge the globals of a configuration.
+
+        Args:
+            config:
+                The configuration to edit.
+
+        Returns:
+            The pruned configuration.
+
+        """
         cli._save_config(config)
         config.pop('global', None)
         result_ = self.runner.invoke(
@@ -3501,6 +3786,17 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
         self,
         config_and_service: tuple[_types.VaultConfig, str],
     ) -> _types.VaultConfig:
+        """Purge the settings of a named service in a configuration.
+
+        Args:
+            config_and_service:
+                A 2-tuple containing the configuration to edit, and the
+                service name to purge.
+
+        Returns:
+            The pruned configuration.
+
+        """
         config, service = config_and_service
         cli._save_config(config)
         config['services'].pop(service, None)
@@ -3523,6 +3819,16 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
         self,
         config: _types.VaultConfig,
     ) -> _types.VaultConfig:
+        """Purge the entire configuration.
+
+        Args:
+            config:
+                The configuration to edit.
+
+        Returns:
+            The empty configuration.
+
+        """
         cli._save_config(config)
         config = {'services': {}}
         result_ = self.runner.invoke(
@@ -3548,6 +3854,22 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
         config_to_import: _types.VaultConfig,
         overwrite: bool,
     ) -> _types.VaultConfig:
+        """Import the given configuration into a base configuration.
+
+        Args:
+            base_config:
+                The configuration to import into.
+            config_to_import:
+                The configuration to import.
+            overwrite:
+                Overwrite the base configuration if true, or merge if
+                false.  Corresponds to the `--overwrite-existing` and
+                `--merge-existing` command-line arguments.
+
+        Returns:
+            The imported or merged configuration.
+
+        """
         cli._save_config(base_config)
         config = (
             self.fold_configs(config_to_import, base_config)
@@ -3569,13 +3891,20 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
         return config
 
     def teardown(self) -> None:
+        """Upon teardown, exit all contexts entered in `__init__`."""
         self.exit_stack.close()
 
 
 TestConfigManagement = ConfigManagementStateMachine.TestCase
+"""The [`unittest.TestCase`][] class that will actually be run."""
 
 
 def bash_format(item: click.shell_completion.CompletionItem) -> str:
+    """A formatter for `bash`-style shell completion items.
+
+    The format is `type,value`, and is dictated by [`click`][].
+
+    """
     type, value = (  # noqa: A001
         item.type,
         item.value,
@@ -3584,6 +3913,11 @@ def bash_format(item: click.shell_completion.CompletionItem) -> str:
 
 
 def fish_format(item: click.shell_completion.CompletionItem) -> str:
+    r"""A formatter for `fish`-style shell completion items.
+
+    The format is `type,value<tab>help`, and is dictated by [`click`][].
+
+    """
     type, value, help = (  # noqa: A001
         item.type,
         item.value,
@@ -3593,6 +3927,19 @@ def fish_format(item: click.shell_completion.CompletionItem) -> str:
 
 
 def zsh_format(item: click.shell_completion.CompletionItem) -> str:
+    r"""A formatter for `zsh`-style shell completion items.
+
+    The format is `type<newline>value<newline>help<newline>`, and is
+    dictated by [`click`][].  Upstream `click` currently (v8.2.0) does
+    not deal with colons in the value correctly when the help text is
+    non-degenerate.  Our formatter here does, provided the upstream
+    `zsh` completion script is used; see the [`cli.ZshComplete`][]
+    class.  A request is underway to merge this change into upstream
+    `click`; see [`pallets/click#2846`][PR2846].
+
+    [PR2846]: https://github.com/pallets/click/pull/2846
+
+    """
     empty_help = '_'
     help_, value = (
         (item.help, item.value.replace(':', r'\:'))
@@ -3605,6 +3952,7 @@ def zsh_format(item: click.shell_completion.CompletionItem) -> str:
 def completion_item(
     item: str | click.shell_completion.CompletionItem,
 ) -> click.shell_completion.CompletionItem:
+    """Convert a string to a completion item, if necessary."""
     return (
         click.shell_completion.CompletionItem(item, type='plain')
         if isinstance(item, str)
@@ -3615,21 +3963,41 @@ def completion_item(
 def assertable_item(
     item: str | click.shell_completion.CompletionItem,
 ) -> tuple[str, Any, str | None]:
+    """Convert a completion item into a pretty-printable item.
+
+    Intended to make completion items introspectable in pytest's
+    `assert` output.
+
+    """
     item = completion_item(item)
     return (item.type, item.value, item.help)
 
 
 class TestShellCompletion:
+    """Tests for the shell completion machinery."""
+
     class Completions:
+        """A deferred completion call."""
+
         def __init__(
             self,
             args: Sequence[str],
             incomplete: str,
         ) -> None:
+            """Initialize the object.
+
+            Args:
+                args:
+                    The sequence of complete command-line arguments.
+                incomplete:
+                    The final, incomplete, partial argument.
+
+            """
             self.args = tuple(args)
             self.incomplete = incomplete
 
         def __call__(self) -> Sequence[click.shell_completion.CompletionItem]:
+            """Return the completion items."""
             args = list(self.args)
             completion = click.shell_completion.ShellComplete(
                 cli=cli.derivepassphrase,
@@ -3640,6 +4008,7 @@ class TestShellCompletion:
             return completion.get_completions(args, self.incomplete)
 
         def get_words(self) -> Sequence[str]:
+            """Return the completion items' values, as a sequence."""
             return tuple(c.value for c in self())
 
     @pytest.mark.parametrize(
@@ -3661,6 +4030,7 @@ class TestShellCompletion:
         partial: str,
         is_completable: bool,
     ) -> None:
+        """Our `_is_completable_item` predicate for service names works."""
         assert cli._is_completable_item(partial) == is_completable
 
     @pytest.mark.parametrize(
@@ -3769,6 +4139,7 @@ class TestShellCompletion:
         incomplete: str,
         completions: AbstractSet[str],
     ) -> None:
+        """Our completion machinery works for all commands' options."""
         comp = self.Completions(command_prefix, incomplete)
         assert frozenset(comp.get_words()) == completions
 
@@ -3795,6 +4166,7 @@ class TestShellCompletion:
         incomplete: str,
         completions: AbstractSet[str],
     ) -> None:
+        """Our completion machinery works for all commands' subcommands."""
         comp = self.Completions(command_prefix, incomplete)
         assert frozenset(comp.get_words()) == completions
 
@@ -3821,6 +4193,7 @@ class TestShellCompletion:
         command_prefix: Sequence[str],
         incomplete: str,
     ) -> None:
+        """Our completion machinery works for all commands' paths."""
         file = click.shell_completion.CompletionItem('', type='file')
         completions = frozenset({(file.type, file.value, file.help)})
         comp = self.Completions(command_prefix, incomplete)
@@ -3870,6 +4243,7 @@ class TestShellCompletion:
         incomplete: str,
         completions: AbstractSet[str],
     ) -> None:
+        """Our completion machinery works for vault service names."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,
@@ -3994,6 +4368,7 @@ class TestShellCompletion:
         incomplete: str,
         results: list[str | click.shell_completion.CompletionItem],
     ) -> None:
+        """Custom completion functions work for all shells."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,
@@ -4196,6 +4571,7 @@ class TestShellCompletion:
         incomplete: str,
         completions: AbstractSet[str],
     ) -> None:
+        """Completion skips incompletable items."""
         runner = click.testing.CliRunner(mix_stderr=False)
         vault_config = config if mode == 'config' else {'services': {}}
         with tests.isolated_vault_config(
@@ -4232,6 +4608,7 @@ class TestShellCompletion:
         self,
         monkeypatch: pytest.MonkeyPatch,
     ) -> None:
+        """Service name completion quietly fails on missing configuration."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,
@@ -4251,6 +4628,7 @@ class TestShellCompletion:
         monkeypatch: pytest.MonkeyPatch,
         exc_type: type[Exception],
     ) -> None:
+        """Service name completion quietly fails on configuration errors."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_config(
             monkeypatch=monkeypatch,

tests/test_derivepassphrase_cli_export_vault.py

Zeige Datei @ 717c79a

@@ -40,7 +40,16 @@ if TYPE_CHECKING:
 
 
 class TestCLI:
+    """Test the command-line interface for `derivepassphrase export vault`."""
+
     def test_200_path_parameter(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """The path `VAULT_PATH` is supported.
+
+        Using `VAULT_PATH` as the path looks up the actual path in the
+        `VAULT_PATH` environment variable.  See
+        [`exporter.get_vault_path`][] for details.
+
+        """
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_exporter_config(
             monkeypatch=monkeypatch,
@@ -58,6 +67,7 @@ class TestCLI:
         assert json.loads(result.output) == tests.VAULT_V03_CONFIG_DATA
 
     def test_201_key_parameter(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """The `--key` option is supported."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_exporter_config(
             monkeypatch=monkeypatch,
@@ -102,6 +112,12 @@ class TestCLI:
         config: str | bytes,
         config_data: dict[str, Any],
     ) -> None:
+        """Passing a specific format works.
+
+        Passing a specific format name causes `derivepassphrase export
+        vault` to only attempt decoding in that named format.
+
+        """
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_exporter_config(
             monkeypatch=monkeypatch,
@@ -124,6 +140,7 @@ class TestCLI:
         monkeypatch: pytest.MonkeyPatch,
         caplog: pytest.LogCaptureFixture,
     ) -> None:
+        """Fail when trying to decode non-existant files/directories."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_exporter_config(
             monkeypatch=monkeypatch,
@@ -150,6 +167,7 @@ class TestCLI:
         monkeypatch: pytest.MonkeyPatch,
         caplog: pytest.LogCaptureFixture,
     ) -> None:
+        """Fail to parse invalid vault configurations (files)."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_exporter_config(
             monkeypatch=monkeypatch,
@@ -173,6 +191,7 @@ class TestCLI:
         monkeypatch: pytest.MonkeyPatch,
         caplog: pytest.LogCaptureFixture,
     ) -> None:
+        """Fail to parse invalid vault configurations (directories)."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_exporter_config(
             monkeypatch=monkeypatch,
@@ -199,6 +218,7 @@ class TestCLI:
         monkeypatch: pytest.MonkeyPatch,
         caplog: pytest.LogCaptureFixture,
     ) -> None:
+        """Fail to parse vault configurations with invalid integrity checks."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_exporter_config(
             monkeypatch=monkeypatch,
@@ -222,6 +242,7 @@ class TestCLI:
         monkeypatch: pytest.MonkeyPatch,
         caplog: pytest.LogCaptureFixture,
     ) -> None:
+        """The decoded vault configuration data is valid."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_exporter_config(
             monkeypatch=monkeypatch,
@@ -251,6 +272,8 @@ class TestCLI:
 
 
 class TestStoreroom:
+    """Test the "storeroom" handler and handler machinery."""
+
     @pytest.mark.parametrize('path', ['.vault', None])
     @pytest.mark.parametrize(
         'key',
@@ -282,6 +305,12 @@ class TestStoreroom:
         key: str | Buffer | None,
         handler: exporter.ExportVaultConfigDataFunction,
     ) -> None:
+        """Support different argument types.
+
+        The [`exporter.export_vault_config_data`][] dispatcher supports
+        them as well.
+
+        """
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_exporter_config(
             monkeypatch=monkeypatch,
@@ -295,6 +324,7 @@ class TestStoreroom:
             )
 
     def test_400_decrypt_bucket_item_unknown_version(self) -> None:
+        """Fail on unknown versions of the master keys file."""
         bucket_item = (
             b'\xff' + bytes(storeroom.ENCRYPTED_KEYPAIR_SIZE) + bytes(3)
         )
@@ -312,6 +342,12 @@ class TestStoreroom:
         monkeypatch: pytest.MonkeyPatch,
         config: str,
     ) -> None:
+        """Fail on bad or unsupported bucket file contents.
+
+        These include unknown versions, invalid JSON, or JSON of the
+        wrong shape.
+
+        """
         runner = click.testing.CliRunner(mix_stderr=False)
         master_keys = _types.StoreroomMasterKeys(
             encryption_key=bytes(storeroom.KEY_SIZE),
@@ -363,6 +399,11 @@ class TestStoreroom:
         err_msg: str,
         handler: exporter.ExportVaultConfigDataFunction,
     ) -> None:
+        """Fail on bad or unsupported master keys file contents.
+
+        These include unknown versions, and data of the wrong shape.
+
+        """
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_exporter_config(
             monkeypatch=monkeypatch,
@@ -415,6 +456,20 @@ class TestStoreroom:
         error_text: str,
         handler: exporter.ExportVaultConfigDataFunction,
     ) -> None:
+        """Fail on bad decoded directory structures.
+
+        If the decoded configuration contains directories whose
+        structures are inconsistent, it detects this and fails:
+
+          - The key indicates a directory, but the contents don't.
+          - The directory indicates children with invalid path names.
+          - The directory indicates children that are missing from the
+            configuration entirely.
+          - The configuration contains nested subdirectories, but the
+            higher-level directories don't indicate their
+            subdirectories.
+
+        """
         runner = click.testing.CliRunner(mix_stderr=False)
         # TODO(the-13th-letter): Rewrite using parenthesized
         # with-statements.
@@ -432,6 +487,15 @@ class TestStoreroom:
             handler(format='storeroom')
 
     def test_404_decrypt_keys_wrong_data_length(self) -> None:
+        """Fail on internal structural data of the wrong size.
+
+        Specifically, fail on internal structural data such as master
+        keys or session keys that is correctly encrypted according to
+        its MAC, but is of the wrong shape.  (Since the data usually are
+        keys and thus are opaque, the only detectable shape violation is
+        the wrong size of the data.)
+
+        """
         payload = (
             b"Any text here, as long as it isn't exactly 64 or 96 bytes long."
         )
@@ -480,6 +544,7 @@ class TestStoreroom:
         ),
     )
     def test_405_decrypt_keys_invalid_signature(self, data: bytes) -> None:
+        """Fail on bad MAC values."""
         key = b'DEADBEEFdeadbeefDeAdBeEfdEaDbEeF'
         # Guessing a correct payload plus MAC would be a pre-image
         # attack on the underlying hash function (SHA-256), i.e. is
@@ -500,6 +565,8 @@ class TestStoreroom:
 
 
 class TestVaultNativeConfig:
+    """Test the vault-native handler and handler machinery."""
+
     @pytest.mark.parametrize(
         ['iterations', 'result'],
         [
@@ -508,6 +575,7 @@ class TestVaultNativeConfig:
         ],
     )
     def test_200_pbkdf2_manually(self, iterations: int, result: bytes) -> None:
+        """The PBKDF2 helper function works."""
         assert (
             vault_native.VaultNativeConfigParser._pbkdf2(
                 tests.VAULT_MASTER_KEY.encode('utf-8'), 32, iterations
@@ -551,7 +619,7 @@ class TestVaultNativeConfig:
             pytest.param(exporter.export_vault_config_data, id='dispatcher'),
         ],
     )
-    def test_201_export_vault_native_data_no_arguments(
+    def test_201_export_vault_native_data_explicit_version(
         self,
         monkeypatch: pytest.MonkeyPatch,
         config: str,
@@ -559,6 +627,16 @@ class TestVaultNativeConfig:
         result: _types.VaultConfig | type[Exception],
         handler: exporter.ExportVaultConfigDataFunction,
     ) -> None:
+        """Accept data only of the correct version.
+
+        Note: Historic behavior
+            `derivepassphrase` versions prior to 0.5 automatically tried
+            to parse vault-native configurations as v0.3-type, then
+            v0.2-type.  Since `derivepassphrase` 0.5, the command-line
+            interface still tries multi-version parsing, but the API
+            no longer does.
+
+        """
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_exporter_config(
             monkeypatch=monkeypatch,
@@ -604,6 +682,12 @@ class TestVaultNativeConfig:
         key: str | Buffer | None,
         handler: exporter.ExportVaultConfigDataFunction,
     ) -> None:
+        """The handler supports different argument types.
+
+        The [`exporter.export_vault_config_data`][] dispatcher supports
+        them as well.
+
+        """
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_exporter_config(
             monkeypatch=monkeypatch,
@@ -640,6 +724,8 @@ class TestVaultNativeConfig:
         config: str,
         result: dict[str, Any],
     ) -> None:
+        """Cache the results of decrypting/decoding a configuration."""
+
         def null_func(name: str) -> Callable[..., None]:
             def func(*_args: Any, **_kwargs: Any) -> None:  # pragma: no cover
                 msg = f'disallowed and stubbed out function {name} called'
@@ -675,5 +761,6 @@ class TestVaultNativeConfig:
             assert super_call(parser) == result
 
     def test_400_no_password(self) -> None:
+        """Fail on empty master keys/master passphrases."""
         with pytest.raises(ValueError, match='Password must not be empty'):
             vault_native.VaultNativeV03ConfigParser(b'', b'')

tests/test_derivepassphrase_exporter.py

Zeige Datei @ 717c79a

@@ -19,6 +19,8 @@ if TYPE_CHECKING:
 
 
 class Test001ExporterUtils:
+    """Test the utility functions in the `exporter` subpackage."""
+
     @pytest.mark.parametrize(
         ['expected', 'vault_key', 'logname', 'user', 'username'],
         [
@@ -48,6 +50,12 @@ class Test001ExporterUtils:
         user: str | None,
         username: str | None,
     ) -> None:
+        """Look up the vault key in `VAULT_KEY`/`LOGNAME`/`USER`/`USERNAME`.
+
+        The correct environment variable value is used, according to
+        their relative priorities.
+
+        """
         priority_list = [
             ('VAULT_KEY', vault_key),
             ('LOGNAME', logname),
@@ -77,6 +85,11 @@ class Test001ExporterUtils:
         expected: pathlib.Path,
         path: str | os.PathLike[str] | None,
     ) -> None:
+        """Determine the vault path from `VAULT_PATH`.
+
+        Handle relative paths, absolute paths, and missing paths.
+
+        """
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_exporter_config(
             monkeypatch=monkeypatch, runner=runner
@@ -93,6 +106,8 @@ class Test001ExporterUtils:
     def test_220_register_export_vault_config_data_handler(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
+        """Register vault config data export handlers."""
+
         def handler(  # pragma: no cover
             path: str | bytes | os.PathLike | None = None,
             key: str | Buffer | None = None,
@@ -120,6 +135,7 @@ class Test001ExporterUtils:
     def test_300_get_vault_key_without_envs(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
+        """Fail to look up the vault key in the empty environment."""
         monkeypatch.delenv('VAULT_KEY', raising=False)
         monkeypatch.delenv('LOGNAME', raising=False)
         monkeypatch.delenv('USER', raising=False)
@@ -130,6 +146,8 @@ class Test001ExporterUtils:
     def test_310_get_vault_path_without_home(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
+        """Fail to look up the vault path without `HOME`."""
+
         def raiser(*_args: Any, **_kwargs: Any) -> Any:
             raise RuntimeError('Cannot determine home directory.')  # noqa: EM101,TRY003
 
@@ -162,6 +180,13 @@ class Test001ExporterUtils:
         namelist: tuple[str, ...],
         err_pat: str,
     ) -> None:
+        """Fail to register a vault config data export handler.
+
+        Fail because e.g. the associated name is missing, or already
+        present in the handler registry.
+
+        """
+
         def handler(  # pragma: no cover
             path: str | bytes | os.PathLike | None = None,
             key: str | Buffer | None = None,
@@ -183,6 +208,7 @@ class Test001ExporterUtils:
     def test_321_export_vault_config_data_bad_handler(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
+        """Fail to export vault config data without known handlers."""
         monkeypatch.setattr(exporter, '_export_vault_config_data_registry', {})
         monkeypatch.setattr(
             exporter, 'find_vault_config_data_handlers', lambda: None
@@ -195,10 +221,13 @@ class Test001ExporterUtils:
 
 
 class Test002CLI:
+    """Test the command-line functionality of the `exporter` subpackage."""
+
     def test_300_invalid_format(
         self,
         monkeypatch: pytest.MonkeyPatch,
     ) -> None:
+        """Reject invalid vault configuration format names."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_exporter_config(
             monkeypatch=monkeypatch,
@@ -249,6 +278,7 @@ class Test002CLI:
         config: str | bytes,
         key: str,
     ) -> None:
+        """Abort export call if no cryptography is available."""
         runner = click.testing.CliRunner(mix_stderr=False)
         with tests.isolated_vault_exporter_config(
             monkeypatch=monkeypatch,

tests/test_derivepassphrase_sequin.py

Zeige Datei @ 717c79a

@@ -19,6 +19,8 @@ def bitseq(string: str) -> list[int]:
 
 
 class TestStaticFunctionality:
+    """Test the static functionality in the `sequin` module."""
+
     @pytest.mark.parametrize(
         ['sequence', 'base', 'expected'],
         [
@@ -32,6 +34,11 @@ class TestStaticFunctionality:
     def test_200_big_endian_number(
         self, sequence: list[int], base: int, expected: int
     ) -> None:
+        """Conversion to big endian numbers in any base works.
+
+        See [`sequin.Sequin.generate`][] for where this is used.
+
+        """
         assert (
             sequin.Sequin._big_endian_number(sequence, base=base)
         ) == expected
@@ -51,11 +58,18 @@ class TestStaticFunctionality:
         sequence: list[int],
         base: int,
     ) -> None:
+        """Nonsensical conversion of numbers in a given base raises.
+
+        See [`sequin.Sequin.generate`][] for where this is used.
+
+        """
         with pytest.raises(exc_type, match=exc_pattern):
             sequin.Sequin._big_endian_number(sequence, base=base)
 
 
 class TestSequin:
+    """Test the `Sequin` class."""
+
     @pytest.mark.parametrize(
         ['sequence', 'is_bitstring', 'expected'],
         [
@@ -75,10 +89,12 @@ class TestSequin:
         is_bitstring: bool,
         expected: list[int],
     ) -> None:
+        """The constructor handles both bit and integer sequences."""
         seq = sequin.Sequin(sequence, is_bitstring=is_bitstring)
         assert seq.bases == {2: collections.deque(expected)}
 
     def test_201_generating(self) -> None:
+        """The sequin generates deterministic sequences."""
         seq = sequin.Sequin(
             [1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 0, 1], is_bitstring=True
         )
@@ -97,6 +113,7 @@ class TestSequin:
             seq.generate(0)
 
     def test_210_internal_generating(self) -> None:
+        """The sequin internals generate deterministic sequences."""
         seq = sequin.Sequin(
             [1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 0, 1], is_bitstring=True
         )
@@ -115,6 +132,12 @@ class TestSequin:
             seq._generate_inner(16, base=1)
 
     def test_211_shifting(self) -> None:
+        """The sequin manages the pool of remaining entropy for each base.
+
+        Specifically, the sequin implements all-or-nothing fixed-length
+        draws from the entropy pool.
+
+        """
         seq = sequin.Sequin([1, 0, 1, 0, 0, 1, 0, 0, 0, 1], is_bitstring=True)
         assert seq.bases == {
             2: collections.deque([1, 0, 1, 0, 0, 1, 0, 0, 0, 1])
@@ -149,5 +172,6 @@ class TestSequin:
         exc_type: type[Exception],
         exc_pattern: str,
     ) -> None:
+        """The sequin raises on invalid bit and integer sequences."""
         with pytest.raises(exc_type, match=exc_pattern):
             sequin.Sequin(sequence, is_bitstring=is_bitstring)

tests/test_derivepassphrase_ssh_agent.py

Zeige Datei @ 717c79a

@@ -28,6 +28,10 @@ if TYPE_CHECKING:
 
 
 class TestStaticFunctionality:
+    """Test the static functionality of the `ssh_agent` module."""
+
+    # TODO(the-13th-letter): Re-evaluate if this check is worth keeping.
+    # It cannot provide true tamper-resistence, but probably appears to.
     @pytest.mark.parametrize(
         ['public_key', 'public_key_data'],
         [
@@ -39,6 +43,7 @@ class TestStaticFunctionality:
     def test_100_key_decoding(
         self, public_key: bytes, public_key_data: bytes
     ) -> None:
+        """The [`tests.ALL_KEYS`][] public key data looks sane."""
         keydata = base64.b64decode(public_key.split(None, 2)[1])
         assert keydata == public_key_data, (
             "recorded public key data doesn't match"
@@ -118,6 +123,7 @@ class TestStaticFunctionality:
     def test_190_sh_export_line_parsing(
         self, line: str, env_name: str, value: str | None
     ) -> None:
+        """[`tests.parse_sh_export_line`][] works."""
         if value is not None:
             assert tests.parse_sh_export_line(line, env_name=env_name) == value
         else:
@@ -129,6 +135,7 @@ class TestStaticFunctionality:
         monkeypatch: pytest.MonkeyPatch,
         skip_if_no_af_unix_support: None,
     ) -> None:
+        """Abort if the running agent cannot be located."""
         del skip_if_no_af_unix_support
         monkeypatch.delenv('SSH_AUTH_SOCK', raising=False)
         with pytest.raises(
@@ -143,6 +150,7 @@ class TestStaticFunctionality:
         ],
     )
     def test_210_uint32(self, input: int, expected: bytes | bytearray) -> None:
+        """`uint32` encoding works."""
         uint32 = ssh_agent.SSHAgentClient.uint32
         assert uint32(input) == expected
 
@@ -169,6 +177,7 @@ class TestStaticFunctionality:
     def test_211_string(
         self, input: bytes | bytearray, expected: bytes | bytearray
     ) -> None:
+        """SSH string encoding works."""
         string = ssh_agent.SSHAgentClient.string
         assert bytes(string(input)) == expected
 
@@ -190,6 +199,7 @@ class TestStaticFunctionality:
     def test_212_unstring(
         self, input: bytes | bytearray, expected: bytes | bytearray
     ) -> None:
+        """SSH string decoding works."""
         unstring = ssh_agent.SSHAgentClient.unstring
         unstring_prefix = ssh_agent.SSHAgentClient.unstring_prefix
         assert bytes(unstring(input)) == expected
@@ -218,6 +228,7 @@ class TestStaticFunctionality:
     def test_310_uint32_exceptions(
         self, value: int, exc_type: type[Exception], exc_pattern: str
     ) -> None:
+        """`uint32` encoding fails for out-of-bound values."""
         uint32 = ssh_agent.SSHAgentClient.uint32
         with pytest.raises(exc_type, match=exc_pattern):
             uint32(value)
@@ -233,6 +244,7 @@ class TestStaticFunctionality:
     def test_311_string_exceptions(
         self, input: Any, exc_type: type[Exception], exc_pattern: str
     ) -> None:
+        """SSH string encoding fails for non-strings."""
         string = ssh_agent.SSHAgentClient.string
         with pytest.raises(exc_type, match=exc_pattern):
             string(input)
@@ -274,6 +286,7 @@ class TestStaticFunctionality:
         has_trailer: bool,
         parts: tuple[bytes | bytearray, bytes | bytearray] | None,
     ) -> None:
+        """SSH string decoding fails for invalid values."""
         unstring = ssh_agent.SSHAgentClient.unstring
         unstring_prefix = ssh_agent.SSHAgentClient.unstring_prefix
         with pytest.raises(exc_type, match=exc_pattern):
@@ -286,6 +299,11 @@ class TestStaticFunctionality:
 
 
 class TestAgentInteraction:
+    """Test actually talking to the SSH agent."""
+
+    # TODO(the-13th-letter): Convert skip into xfail, and include the
+    # key type in the skip/xfail message.  This means the key type needs
+    # to be passed to the test function as well.
     @pytest.mark.parametrize(
         'ssh_test_key',
         list(tests.SUPPORTED_KEYS.values()),
@@ -296,6 +314,13 @@ class TestAgentInteraction:
         ssh_agent_client_with_test_keys_loaded: ssh_agent.SSHAgentClient,
         ssh_test_key: tests.SSHTestKey,
     ) -> None:
+        """Signing data with specific SSH keys works.
+
+        Single tests may abort early (skip) if the indicated key is not
+        loaded in the agent.  Presumably this means the key type is
+        unsupported.
+
+        """
         client = ssh_agent_client_with_test_keys_loaded
         key_comment_pairs = {bytes(k): bytes(c) for k, c in client.list_keys()}
         public_key_data = ssh_test_key.public_key_data
@@ -318,6 +343,9 @@ class TestAgentInteraction:
             == derived_passphrase
         ), 'SSH signature mismatch'
 
+    # TODO(the-13th-letter): Include the key type in the skip message.
+    # This means the key type needs to be passed to the test function as
+    # well.
     @pytest.mark.parametrize(
         'ssh_test_key',
         list(tests.UNSUITABLE_KEYS.values()),
@@ -328,6 +356,15 @@ class TestAgentInteraction:
         ssh_agent_client_with_test_keys_loaded: ssh_agent.SSHAgentClient,
         ssh_test_key: tests.SSHTestKey,
     ) -> None:
+        """Using an unsuitable key with [`vault.Vault`][] fails.
+
+        Single tests may abort early (skip) if the indicated key is not
+        loaded in the agent.  Presumably this means the key type is
+        unsupported.  Single tests may also abort early if the agent
+        ensures that the generally unsuitable key is actually suitable
+        under this agent.
+
+        """
         client = ssh_agent_client_with_test_keys_loaded
         key_comment_pairs = {bytes(k): bytes(c) for k, c in client.list_keys()}
         public_key_data = ssh_test_key.public_key_data
@@ -357,9 +394,16 @@ class TestAgentInteraction:
         key: bytes,
         single: bool,
     ) -> None:
+        """The key selector presents exactly the suitable keys.
+
+        "Suitable" here means suitability for this SSH agent
+        specifically.
+
+        """
         client = ssh_agent_client_with_test_keys_loaded
 
         def key_is_suitable(key: bytes) -> bool:
+            """Stub out [`vault.Vault.key_is_suitable`][]."""
             always = {v.public_key_data for v in tests.SUPPORTED_KEYS.values()}
             dsa = {
                 v.public_key_data
@@ -370,6 +414,11 @@ class TestAgentInteraction:
                 client.has_deterministic_dsa_signatures() and key in dsa
             )
 
+        # TODO(the-13th-letter): Handle the unlikely(?) case that only
+        # one test key is loaded, but `single` is False.  Rename the
+        # `index` variable to `input`, store the `input` in there, and
+        # make the definition of `text` in the else block dependent on
+        # `n` being singular or non-singular.
         if single:
             monkeypatch.setattr(
                 ssh_agent.SSHAgentClient,
@@ -399,9 +448,12 @@ class TestAgentInteraction:
 
         @click.command()
         def driver() -> None:
+            """Call `cli._select_ssh_key` directly, as a command."""
             key = cli._select_ssh_key()
             click.echo(base64.standard_b64encode(key).decode('ASCII'))
 
+        # TODO(the-13th-letter): (Continued from above.)  Update input
+        # data to use `index`/`input` directly and unconditionally.
         runner = click.testing.CliRunner(mix_stderr=True)
         result_ = runner.invoke(
             driver,
@@ -418,6 +470,7 @@ class TestAgentInteraction:
         monkeypatch: pytest.MonkeyPatch,
         running_ssh_agent: tests.RunningSSHAgentInfo,
     ) -> None:
+        """Fail if the agent address is invalid."""
         with monkeypatch.context() as monkeypatch2:
             monkeypatch2.setenv(
                 'SSH_AUTH_SOCK', running_ssh_agent.socket + '~'
@@ -430,6 +483,7 @@ class TestAgentInteraction:
         self,
         monkeypatch: pytest.MonkeyPatch,
     ) -> None:
+        """Fail without [`socket.AF_UNIX`][] support."""
         with monkeypatch.context() as monkeypatch2:
             monkeypatch2.setenv('SSH_AUTH_SOCK', "the value doesn't matter")
             monkeypatch2.delattr(socket, 'AF_UNIX', raising=False)
@@ -453,6 +507,7 @@ class TestAgentInteraction:
         running_ssh_agent: tests.RunningSSHAgentInfo,
         response: bytes,
     ) -> None:
+        """Fail on truncated responses from the SSH agent."""
         del running_ssh_agent
         client = ssh_agent.SSHAgentClient()
         response_stream = io.BytesIO(response)
@@ -504,6 +559,16 @@ class TestAgentInteraction:
         exc_type: type[Exception],
         exc_pattern: str,
     ) -> None:
+        """Fail on problems during key listing.
+
+        Known problems:
+
+          - The agent refuses, or otherwise indicates the operation
+            failed.
+          - The agent response is truncated.
+          - The agent response is overlong.
+
+        """
         del running_ssh_agent
 
         passed_response_code = response_code
@@ -584,6 +649,15 @@ class TestAgentInteraction:
         exc_type: type[Exception],
         exc_pattern: str,
     ) -> None:
+        """Fail on problems during signing.
+
+        Known problems:
+
+          - The key is not loaded into the agent.
+          - The agent refuses, or otherwise indicates the operation
+            failed.
+
+        """
         del running_ssh_agent
         passed_response_code = response_code
 
@@ -651,6 +725,15 @@ class TestAgentInteraction:
         exc_type: type[Exception],
         exc_pattern: str,
     ) -> None:
+        """Fail on problems during signing.
+
+        Known problems:
+
+          - The key is not loaded into the agent.
+          - The agent refuses, or otherwise indicates the operation
+            failed.
+
+        """
         del running_ssh_agent
 
         # TODO(the-13th-letter): Rewrite using parenthesized
@@ -683,6 +766,7 @@ class TestAgentInteraction:
         running_ssh_agent: tests.RunningSSHAgentInfo,
         response_data: bytes,
     ) -> None:
+        """Fail on malformed responses while querying extensions."""
         del running_ssh_agent
 
         def request(
@@ -738,17 +822,21 @@ class TestAgentInteraction:
 
 
 class TestHypotheses:
+    """Test properties via hypothesis."""
+
     @hypothesis.given(strategies.integers(min_value=0, max_value=0xFFFFFFFF))
     # standard example value
     @hypothesis.example(0xDEADBEEF)
-    def test_210_uint32(self, num: int) -> None:
+    def test_210a_uint32_from_number(self, num: int) -> None:
+        """`uint32` encoding works, starting from numbers."""
         uint32 = ssh_agent.SSHAgentClient.uint32
         assert int.from_bytes(uint32(num), 'big', signed=False) == num
 
     @hypothesis.given(strategies.binary(min_size=4, max_size=4))
     # standard example value
     @hypothesis.example(b'\xde\xad\xbe\xef')
-    def test_210a_uint32(self, bytestring: bytes) -> None:
+    def test_210b_uint32_from_bytestring(self, bytestring: bytes) -> None:
+        """`uint32` encoding works, starting from length four byte strings."""
         uint32 = ssh_agent.SSHAgentClient.uint32
         assert (
             uint32(int.from_bytes(bytestring, 'big', signed=False))
@@ -758,7 +846,8 @@ class TestHypotheses:
     @hypothesis.given(strategies.binary(max_size=0x0001FFFF))
     # example: highest order bit is set
     @hypothesis.example(b'DEADBEEF' * 10000)
-    def test_211_string(self, bytestring: bytes) -> None:
+    def test_211a_string_from_bytestring(self, bytestring: bytes) -> None:
+        """SSH string encoding works, starting from a byte string."""
         res = ssh_agent.SSHAgentClient.string(bytestring)
         assert res.startswith((b'\x00\x00', b'\x00\x01'))
         assert int.from_bytes(res[:4], 'big', signed=False) == len(bytestring)
@@ -768,6 +857,7 @@ class TestHypotheses:
     # example: check for double-deserialization
     @hypothesis.example(b'\x00\x00\x00\x07ssh-rsa')
     def test_212_string_unstring(self, bytestring: bytes) -> None:
+        """SSH string decoding of encoded SSH strings works."""
         string = ssh_agent.SSHAgentClient.string
         unstring = ssh_agent.SSHAgentClient.unstring
         unstring_prefix = ssh_agent.SSHAgentClient.unstring_prefix

tests/test_derivepassphrase_types.py

Zeige Datei @ 717c79a

...	...	@@ -58,6 +58,11 @@ from derivepassphrase import _types
58	58	),
59	59	)
60	60	def test_100_js_truthiness(value: Any) -> None:
	61	+ """Determine the truthiness of a value according to JavaScript.
	62	+
	63	+ Use hypothesis to generate test values.
	64	+
	65	+ """
61	66	expected = (
62	67	value is not None # noqa: PLR1714
63	68	and value != False # noqa: E712
...	...	@@ -78,6 +83,15 @@ def test_100_js_truthiness(value: Any) -> None:
78	83	ids=tests._test_config_ids,
79	84	)
80	85	def test_200_is_vault_config(test_config: tests.VaultTestConfig) -> None:
	86	+ """Is this vault configuration recognized as valid/invalid?
	87	+
	88	+ Check all test configurations that do not need custom validation
	89	+ settings.
	90	+
	91	+ This primarily tests the [`_types.is_vault_config`][] and
	92	+ [`_types.clean_up_falsy_vault_config_values`][] functions.
	93	+
	94	+ """
81	95	obj, comment, _ = test_config
82	96	obj = copy.deepcopy(obj)
83	97	_types.clean_up_falsy_vault_config_values(obj)
...	...	@@ -99,6 +113,15 @@ def test_200_is_vault_config(test_config: tests.VaultTestConfig) -> None:
99	113	def test_200a_is_vault_config_smudged(
100	114	test_config: tests.VaultTestConfig,
101	115	) -> None:
	116	+ """Is this vault configuration recognized as valid/invalid?
	117	+
	118	+ Generate test data via hypothesis by smudging all valid test
	119	+ configurations.
	120	+
	121	+ This primarily tests the [`_types.is_vault_config`][] and
	122	+ [`_types.clean_up_falsy_vault_config_values`][] functions.
	123	+
	124	+ """
102	125	obj_, comment, _ = test_config
103	126	obj = copy.deepcopy(obj_)
104	127	did_cleanup = _types.clean_up_falsy_vault_config_values(obj)
...	...	@@ -116,6 +139,15 @@ def test_200a_is_vault_config_smudged(
116	139	'test_config', tests.TEST_CONFIGS, ids=tests._test_config_ids
117	140	)
118	141	def test_400_validate_vault_config(test_config: tests.VaultTestConfig) -> None:
	142	+ """Validate this vault configuration.
	143	+
	144	+ Check all test configurations, including those with non-standard
	145	+ validation settings.
	146	+
	147	+ This primarily tests the [`_types.validate_vault_config`][] and
	148	+ [`_types.clean_up_falsy_vault_config_values`][] functions.
	149	+
	150	+ """
119	151	obj, comment, validation_settings = test_config
120	152	(allow_unknown_settings,) = validation_settings or (True,)
121	153	obj = copy.deepcopy(obj)
...	...	@@ -147,6 +179,15 @@ def test_400_validate_vault_config(test_config: tests.VaultTestConfig) -> None:
147	179	def test_400a_validate_vault_config_smudged(
148	180	test_config: tests.VaultTestConfig,
149	181	) -> None:
	182	+ """Validate this vault configuration.
	183	+
	184	+ Generate test data via hypothesis by smudging all smudgable test
	185	+ configurations.
	186	+
	187	+ This primarily tests the [`_types.validate_vault_config`][] and
	188	+ [`_types.clean_up_falsy_vault_config_values`][] functions.
	189	+
	190	+ """
150	191	obj_, comment, validation_settings = test_config
151	192	(allow_unknown_settings,) = validation_settings or (True,)
152	193	obj = copy.deepcopy(obj_)

tests/test_derivepassphrase_vault.py

Zeige Datei @ 717c79a

@@ -24,9 +24,20 @@ Vault: TypeAlias = derivepassphrase.vault.Vault
 
 
 class TestVault:
+    """Test passphrase derivation with the "vault" scheme."""
+
     phrase = b'She cells C shells bye the sea shoars'
+    """The standard passphrase from <i>vault</i>(1)'s test suite."""
     google_phrase = rb': 4TVH#5:aZl8LueOT\{'
+    """
+    The standard derived passphrase for the "google" service, from
+    <i>vault</i>(1)'s test suite.
+    """
     twitter_phrase = rb"[ (HN_N:lI&<ro=)3'g9"
+    """
+    The standard derived passphrase for the "twitter" service, from
+    <i>vault</i>(1)'s test suite.
+    """
 
     @pytest.mark.parametrize(
         ['service', 'expected'],
@@ -38,30 +49,36 @@ class TestVault:
     def test_200_basic_configuration(
         self, service: bytes | str, expected: bytes
     ) -> None:
+        """Deriving a passphrase principally works."""
         assert Vault(phrase=self.phrase).generate(service) == expected
 
     def test_201_phrase_dependence(self) -> None:
+        """The derived passphrase is dependent on the master passphrase."""
         assert (
             Vault(phrase=(self.phrase + b'X')).generate('google')
             == b'n+oIz6sL>K*lTEWYRO%7'
         )
 
     def test_202_reproducibility_and_bytes_service_name(self) -> None:
+        """Deriving a passphrase works equally for byte strings."""
         assert Vault(phrase=self.phrase).generate(b'google') == Vault(
             phrase=self.phrase
         ).generate('google')
 
     def test_203_reproducibility_and_bytearray_service_name(self) -> None:
+        """Deriving a passphrase works equally for byte arrays."""
         assert Vault(phrase=self.phrase).generate(b'google') == Vault(
             phrase=self.phrase
         ).generate(bytearray(b'google'))
 
     def test_210_nonstandard_length(self) -> None:
+        """Deriving a passphrase adheres to imposed length limits."""
         assert (
             Vault(phrase=self.phrase, length=4).generate('google') == b'xDFu'
         )
 
     def test_211_repetition_limit(self) -> None:
+        """Deriving a passphrase adheres to imposed repetition limits."""
         assert (
             Vault(
                 phrase=b'', length=24, symbol=0, number=0, repeat=1
@@ -70,36 +87,44 @@ class TestVault:
         )
 
     def test_212_without_symbols(self) -> None:
+        """Deriving a passphrase adheres to imposed limits on symbols."""
         assert (
             Vault(phrase=self.phrase, symbol=0).generate('google')
             == b'XZ4wRe0bZCazbljCaMqR'
         )
 
     def test_213_no_numbers(self) -> None:
+        """Deriving a passphrase adheres to imposed limits on numbers."""
         assert (
             Vault(phrase=self.phrase, number=0).generate('google')
             == b'_*$TVH.%^aZl(LUeOT?>'
         )
 
     def test_214_no_lowercase_letters(self) -> None:
+        """
+        Deriving a passphrase adheres to imposed limits on lowercase letters.
+        """
         assert (
             Vault(phrase=self.phrase, lower=0).generate('google')
             == b':{?)+7~@OA:L]!0E$)(+'
         )
 
     def test_215_at_least_5_digits(self) -> None:
+        """Deriving a passphrase adheres to imposed counts of numbers."""
         assert (
             Vault(phrase=self.phrase, length=8, number=5).generate('songkick')
             == b'i0908.7['
         )
 
     def test_216_lots_of_spaces(self) -> None:
+        """Deriving a passphrase adheres to imposed counts of spaces."""
         assert (
             Vault(phrase=self.phrase, space=12).generate('songkick')
             == b' c   6 Bq  % 5fR    '
         )
 
     def test_217_all_character_classes(self) -> None:
+        """Deriving a passphrase adheres to imposed counts of all types."""
         assert (
             Vault(
                 phrase=self.phrase,
@@ -114,6 +139,11 @@ class TestVault:
         )
 
     def test_218_only_numbers_and_very_high_repetition_limit(self) -> None:
+        """Deriving a passphrase adheres to imposed repetition limits.
+
+        This example is checked explicitly against forbidden substrings.
+
+        """
         generated = Vault(
             phrase=b'',
             length=40,
@@ -140,12 +170,14 @@ class TestVault:
             assert substring not in generated
 
     def test_219_very_limited_character_set(self) -> None:
+        """Deriving a passphrase works even with limited character sets."""
         generated = Vault(
             phrase=b'', length=24, lower=0, upper=0, space=0, symbol=0
         ).generate('testing')
         assert generated == b'763252593304946694588866'
 
     def test_220_character_set_subtraction(self) -> None:
+        """Removing allowed characters internally works."""
         assert Vault._subtract(b'be', b'abcdef') == bytearray(b'acdf')
 
     @pytest.mark.parametrize(
@@ -170,6 +202,7 @@ class TestVault:
     def test_221_entropy(
         self, length: int, settings: dict[str, int], entropy: int
     ) -> None:
+        """Estimating the entropy and sufficient hash length works."""
         v = Vault(length=length, **settings)  # type: ignore[arg-type]
         assert math.isclose(v._entropy(), entropy)
         assert v._estimate_sufficient_hash_length() > 0
@@ -180,6 +213,9 @@ class TestVault:
         assert v._estimate_sufficient_hash_length(8.0) >= entropy
 
     def test_222_hash_length_estimation(self) -> None:
+        """
+        Estimating the entropy and hash length for degenerate cases works.
+        """
         v = Vault(
             phrase=self.phrase,
             lower=0,
@@ -205,6 +241,9 @@ class TestVault:
         service: str | bytes,
         expected: bytes,
     ) -> None:
+        """
+        Estimating the entropy and hash length for the degenerate case works.
+        """
         v = Vault(phrase=self.phrase)
         monkeypatch.setattr(
             v,
@@ -226,6 +265,7 @@ class TestVault:
         ],
     )
     def test_224_binary_strings(self, s: str | bytes | bytearray) -> None:
+        """Byte string conversion is idempotent."""
         binstr = Vault._get_binary_string
         if isinstance(s, str):
             assert binstr(s) == s.encode('UTF-8')
@@ -235,12 +275,14 @@ class TestVault:
             assert binstr(binstr(s)) == bytes(s)
 
     def test_310_too_many_symbols(self) -> None:
+        """Deriving short passphrases with large length constraints fails."""
         with pytest.raises(
             ValueError, match='requested passphrase length too short'
         ):
             Vault(phrase=self.phrase, symbol=100)
 
     def test_311_no_viable_characters(self) -> None:
+        """Deriving passphrases without allowed characters fails."""
         with pytest.raises(ValueError, match='no allowed characters left'):
             Vault(
                 phrase=self.phrase,
@@ -253,12 +295,14 @@ class TestVault:
             )
 
     def test_320_character_set_subtraction_duplicate(self) -> None:
+        """Character sets do not contain duplicate characters."""
         with pytest.raises(ValueError, match='duplicate characters'):
             Vault._subtract(b'abcdef', b'aabbccddeeff')
         with pytest.raises(ValueError, match='duplicate characters'):
             Vault._subtract(b'aabbccddeeff', b'abcdef')
 
     def test_322_hash_length_estimation(self) -> None:
+        """Hash length estimation rejects invalid safety factors."""
         v = Vault(phrase=self.phrase)
         with pytest.raises(ValueError, match='invalid safety factor'):
             assert v._estimate_sufficient_hash_length(-1.0)
@@ -269,6 +313,8 @@ class TestVault:
 
 
 class TestHypotheses:
+    """Test properties via hypothesis."""
+
     @tests.hypothesis_settings_coverage_compatible
     @hypothesis.given(
         phrase=strategies.one_of(
@@ -328,6 +374,7 @@ class TestHypotheses:
         config: dict[str, int],
         service: str,
     ) -> None:
+        """Derived passphrases obey character and occurrence restraints."""
         try:
             password = Vault(phrase=phrase, **config).generate(service)
         except ValueError as exc:
@@ -386,6 +433,7 @@ class TestHypotheses:
         length: int,
         service: str,
     ) -> None:
+        """Derived passphrases have the requested length."""
         password = Vault(phrase=phrase, length=length).generate(service)
         assert len(password) == length
 
@@ -412,6 +460,7 @@ class TestHypotheses:
         repeat: int,
         service: str,
     ) -> None:
+        """Derived passphrases obey the given occurrence constraint."""
         password = Vault(phrase=phrase, length=length, repeat=repeat).generate(
             service
         )

tests/test_l10n.py

Zeige Datei @ 717c79a

@@ -42,6 +42,7 @@ all_translatable_strings = [
 
 @pytest.fixture(scope='class')
 def use_debug_translations() -> Iterator[None]:
+    """Force the use of debug translations (pytest class fixture)."""
     with pytest.MonkeyPatch.context() as monkeypatch:
         monkeypatch.setattr(msg, 'translation', msg.DebugTranslations())
         yield
@@ -49,6 +50,7 @@ def use_debug_translations() -> Iterator[None]:
 
 @contextlib.contextmanager
 def monkeypatched_null_translations() -> Iterator[None]:
+    """Force the use of no-op translations in this context."""
     with pytest.MonkeyPatch.context() as monkeypatch:
         monkeypatch.setattr(msg, 'translation', gettext.NullTranslations())
         yield
@@ -56,21 +58,29 @@ def monkeypatched_null_translations() -> Iterator[None]:
 
 @pytest.mark.usefixtures('use_debug_translations')
 class TestL10nMachineryWithDebugTranslations:
+    """Test the localization machinery together with debug translations."""
     error_codes = tuple(
         sorted(errno.errorcode, key=errno.errorcode.__getitem__)
     )
+    """A cache of the known error codes from the [`errno`][] module."""
     known_fields_error_messages = tuple(
         e
         for e in sorted(msg.ErrMsgTemplate, key=str)
         if e.value.fields() == ['error', 'filename']
     )
+    """
+    A cache of known error messages that contain both `error` and
+    `filename` replacement fields.
+    """
     no_fields_messages = tuple(
         e for e in all_translatable_strings_enum_values if not e.value.fields()
     )
+    """A cache of known messages that don't contain replacement fields."""
 
     @hypothesis.given(value=strategies.text(max_size=100))
     @hypothesis.example('{')
     def test_100_debug_translation_get_str(self, value: str) -> None:
+        """Translating a raw string object does nothing."""
         translated = msg.translation.gettext(value)
         assert translated == value
 
@@ -79,6 +89,7 @@ class TestL10nMachineryWithDebugTranslations:
         self,
         value: msg.TranslatableString,
     ) -> None:
+        """Translating a TranslatableString translates and interpolates."""
         ts_name = str(all_translatable_strings_dict[value])
         context = value.l10n_context
         singular = value.singular
@@ -94,6 +105,7 @@ class TestL10nMachineryWithDebugTranslations:
         self,
         value: msg.MsgTemplate,
     ) -> None:
+        """Translating a MsgTemplate operates on the enum value."""
         ts_name = str(value)
         inner_value = cast('msg.TranslatableString', value.value)
         context = inner_value.l10n_context
@@ -106,6 +118,7 @@ class TestL10nMachineryWithDebugTranslations:
     @hypothesis.given(value=strategies.text(max_size=100))
     @hypothesis.example('{')
     def test_100c_debug_translation_get_ts_str(self, value: str) -> None:
+        """Translating a constant TranslatableString does nothing."""
         translated = msg.TranslatedString.constant(value)
         assert str(translated) == value
 
@@ -121,6 +134,7 @@ class TestL10nMachineryWithDebugTranslations:
         self,
         values: list[msg.MsgTemplate],
     ) -> None:
+        """TranslatableStrings are hashable."""
         assert len(values) == 2
         ts0 = msg.TranslatedString(values[0])
         ts1 = msg.TranslatedString(values[0])
@@ -148,6 +162,7 @@ class TestL10nMachineryWithDebugTranslations:
         value: msg.ErrMsgTemplate,
         errnos: list[int],
     ) -> None:
+        """TranslatableStrings are hashable even with interpolations."""
         assert len(errnos) == 2
         error1, error2 = [os.strerror(c) for c in errnos]
         ts1 = msg.TranslatedString(
@@ -169,6 +184,7 @@ class TestL10nMachineryWithDebugTranslations:
         value: msg.ErrMsgTemplate,
         errno_: int,
     ) -> None:
+        """Interpolated TranslatableStrings with error/filename are hashable."""
         error = os.strerror(errno_)
         # The debug translations specifically do *not* differ in output
         # when the filename is trimmed.  So we need to request some
@@ -190,6 +206,13 @@ class TestL10nMachineryWithDebugTranslations:
         self,
         s: str,
     ) -> None:
+        """TranslatableStrings require fixed replacement fields.
+
+        They reject attempts at stringification if unknown fields are
+        passed, or if fields are missing, or if the format string is
+        invalid.
+
+        """
         with monkeypatched_null_translations():
             ts1 = msg.TranslatedString(s)
             with pytest.raises((KeyError, ValueError)) as excinfo:
@@ -223,6 +246,7 @@ class TestL10nMachineryWithDebugTranslations:
         self,
         s: str,
     ) -> None:
+        """Constant TranslatedStrings don't interpolate fields."""
         with monkeypatched_null_translations():
             ts = msg.TranslatedString.constant(s)
             try:
@@ -244,6 +268,7 @@ class TestL10nMachineryWithDebugTranslations:
         self,
         s: str,
     ) -> None:
+        """Non-format TranslatedStrings don't interpolate fields."""
         with monkeypatched_null_translations():
             ts_inner = msg.TranslatableString(
                 '',


...	...	@@ -70,7 +70,28 @@ class SpawnFunc(Protocol):
70	70	self,
71	71	executable: str \| None,
72	72	env: dict[str, str],
73		- ) -> subprocess.Popen[str] \| None: ...
	73	+ ) -> subprocess.Popen[str] \| None:
	74	+ """Spawn the SSH agent.
	75	+
	76	+ Args:
	77	+ executable:
	78	+ The respective SSH agent executable.
	79	+ env:
	80	+ The new environment for the respective agent. Should
	81	+ typically not include an SSH_AUTH_SOCK variable.
	82	+
	83	+ Returns:
	84	+ The spawned SSH agent subprocess. If the executable is
	85	+ `None`, then return `None` directly.
	86	+
	87	+ It is the caller's responsibility to clean up the spawned
	88	+ subprocess.
	89	+
	90	+ Raises:
	91	+ OSError:
	92	+ The [`subprocess.Popen`][] call failed. See there.
	93	+
	94	+ """
74	95
75	96
76	97	def _spawn_pageant( # pragma: no cover
...	...	@@ -190,12 +211,27 @@ _spawn_handlers = [
190	211	('ssh-agent', _spawn_openssh_agent, tests.KnownSSHAgent.OpenSSHAgent),
191	212	('(system)', _spawn_noop, tests.KnownSSHAgent.UNKNOWN),
192	213	]
	214	+"""
	215	+The standard registry of agent spawning functions.
	216	+"""
193	217
194	218	Popen = TypeVar('Popen', bound=subprocess.Popen)
195	219
196	220
197	221	@contextlib.contextmanager
198	222	def _terminate_on_exit(proc: Popen) -> Iterator[Popen]:
	223	+ """Terminate and wait for the subprocess upon exiting the context.
	224	+
	225	+ Args:
	226	+ proc:
	227	+ The subprocess to manage.
	228	+
	229	+ Returns:
	230	+ A context manager. Upon entering the manager, return the
	231	+ managed subprocess. Upon exiting the manager, terminate the
	232	+ process and wait for it.
	233	+
	234	+ """
199	235	try:
200	236	yield proc
201	237	finally:
...	...	@@ -204,7 +240,7 @@ def _terminate_on_exit(proc: Popen) -> Iterator[Popen]:
204	240
205	241
206	242	class CannotSpawnError(RuntimeError):
207		- pass
	243	+ """Cannot spawn the SSH agent."""
208	244
209	245
210	246	def _spawn_named_agent(
...	...	@@ -212,6 +248,41 @@ def _spawn_named_agent(
212	248	spawn_func: SpawnFunc,
213	249	agent_type: tests.KnownSSHAgent,
214	250	) -> Iterator[tests.SpawnedSSHAgentInfo]: # pragma: no cover
	251	+ """Spawn the named SSH agent and check that it is operational.
	252	+
	253	+ Using the correct agent-specific spawn function from the
	254	+ [`spawn_handlers`][] registry, spawn the named SSH agent (according
	255	+ to its declared type), then set up the communication channel and
	256	+ yield an SSH agent client connected to this agent. After resuming,
	257	+ tear down the communication channel and terminate the SSH agent.
	258	+
	259	+ The SSH agent's instructions for setting up the communication
	260	+ channel are parsed with [`tests.parse_sh_export_line`][]. See the
	261	+ caveats there.
	262	+
	263	+ Args:
	264	+ exec_name:
	265	+ The executable to spawn.
	266	+ spawn_func:
	267	+ The agent-specific spawn function.
	268	+ agent_type:
	269	+ The agent type.
	270	+
	271	+ Yields:
	272	+ A 3-tuple containing the agent type, an SSH agent client
	273	+ connected to this agent, and a boolean indicating whether this
	274	+ agent was actually spawned in an isolated manner.
	275	+
	276	+ Only one tuple will ever be yielded. After resuming, the
	277	+ connected client will be torn down, as will the agent if it was
	278	+ isolated.
	279	+
	280	+ Raises:
	281	+ CannotSpawnError:
	282	+ We failed to spawn the agent or otherwise set up the
	283	+ environment/communication channel/etc.
	284	+
	285	+ """
215	286	# pytest's fixture system does not seem to guarantee that
216	287	# environment variables are set up correctly if nested and
217	288	# parametrized fixtures are used: it is possible that "outer"

...	...	@@ -40,7 +40,16 @@ if TYPE_CHECKING:
40	40
41	41
42	42	class TestCLI:
	43	+ """Test the command-line interface for `derivepassphrase export vault`."""
	44	+
43	45	def test_200_path_parameter(self, monkeypatch: pytest.MonkeyPatch) -> None:
	46	+ """The path `VAULT_PATH` is supported.
	47	+
	48	+ Using `VAULT_PATH` as the path looks up the actual path in the
	49	+ `VAULT_PATH` environment variable. See
	50	+ [`exporter.get_vault_path`][] for details.
	51	+
	52	+ """
44	53	runner = click.testing.CliRunner(mix_stderr=False)
45	54	with tests.isolated_vault_exporter_config(
46	55	monkeypatch=monkeypatch,
...	...	@@ -58,6 +67,7 @@ class TestCLI:
58	67	assert json.loads(result.output) == tests.VAULT_V03_CONFIG_DATA
59	68
60	69	def test_201_key_parameter(self, monkeypatch: pytest.MonkeyPatch) -> None:
	70	+ """The `--key` option is supported."""
61	71	runner = click.testing.CliRunner(mix_stderr=False)
62	72	with tests.isolated_vault_exporter_config(
63	73	monkeypatch=monkeypatch,
...	...	@@ -102,6 +112,12 @@ class TestCLI:
102	112	config: str \| bytes,
103	113	config_data: dict[str, Any],
104	114	) -> None:
	115	+ """Passing a specific format works.
	116	+
	117	+ Passing a specific format name causes `derivepassphrase export
	118	+ vault` to only attempt decoding in that named format.
	119	+
	120	+ """
105	121	runner = click.testing.CliRunner(mix_stderr=False)
106	122	with tests.isolated_vault_exporter_config(
107	123	monkeypatch=monkeypatch,
...	...	@@ -124,6 +140,7 @@ class TestCLI:
124	140	monkeypatch: pytest.MonkeyPatch,
125	141	caplog: pytest.LogCaptureFixture,
126	142	) -> None:
	143	+ """Fail when trying to decode non-existant files/directories."""
127	144	runner = click.testing.CliRunner(mix_stderr=False)
128	145	with tests.isolated_vault_exporter_config(
129	146	monkeypatch=monkeypatch,
...	...	@@ -150,6 +167,7 @@ class TestCLI:
150	167	monkeypatch: pytest.MonkeyPatch,
151	168	caplog: pytest.LogCaptureFixture,
152	169	) -> None:
	170	+ """Fail to parse invalid vault configurations (files)."""
153	171	runner = click.testing.CliRunner(mix_stderr=False)
154	172	with tests.isolated_vault_exporter_config(
155	173	monkeypatch=monkeypatch,
...	...	@@ -173,6 +191,7 @@ class TestCLI:
173	191	monkeypatch: pytest.MonkeyPatch,
174	192	caplog: pytest.LogCaptureFixture,
175	193	) -> None:
	194	+ """Fail to parse invalid vault configurations (directories)."""
176	195	runner = click.testing.CliRunner(mix_stderr=False)
177	196	with tests.isolated_vault_exporter_config(
178	197	monkeypatch=monkeypatch,
...	...	@@ -199,6 +218,7 @@ class TestCLI:
199	218	monkeypatch: pytest.MonkeyPatch,
200	219	caplog: pytest.LogCaptureFixture,
201	220	) -> None:
	221	+ """Fail to parse vault configurations with invalid integrity checks."""
202	222	runner = click.testing.CliRunner(mix_stderr=False)
203	223	with tests.isolated_vault_exporter_config(
204	224	monkeypatch=monkeypatch,
...	...	@@ -222,6 +242,7 @@ class TestCLI:
222	242	monkeypatch: pytest.MonkeyPatch,
223	243	caplog: pytest.LogCaptureFixture,
224	244	) -> None:
	245	+ """The decoded vault configuration data is valid."""
225	246	runner = click.testing.CliRunner(mix_stderr=False)
226	247	with tests.isolated_vault_exporter_config(
227	248	monkeypatch=monkeypatch,
...	...	@@ -251,6 +272,8 @@ class TestCLI:
251	272
252	273
253	274	class TestStoreroom:
	275	+ """Test the "storeroom" handler and handler machinery."""
	276	+
254	277	@pytest.mark.parametrize('path', ['.vault', None])
255	278	@pytest.mark.parametrize(
256	279	'key',
...	...	@@ -282,6 +305,12 @@ class TestStoreroom:
282	305	key: str \| Buffer \| None,
283	306	handler: exporter.ExportVaultConfigDataFunction,
284	307	) -> None:
	308	+ """Support different argument types.
	309	+
	310	+ The [`exporter.export_vault_config_data`][] dispatcher supports
	311	+ them as well.
	312	+
	313	+ """
285	314	runner = click.testing.CliRunner(mix_stderr=False)
286	315	with tests.isolated_vault_exporter_config(
287	316	monkeypatch=monkeypatch,
...	...	@@ -295,6 +324,7 @@ class TestStoreroom:
295	324	)
296	325
297	326	def test_400_decrypt_bucket_item_unknown_version(self) -> None:
	327	+ """Fail on unknown versions of the master keys file."""
298	328	bucket_item = (
299	329	b'\xff' + bytes(storeroom.ENCRYPTED_KEYPAIR_SIZE) + bytes(3)
300	330	)
...	...	@@ -312,6 +342,12 @@ class TestStoreroom:
312	342	monkeypatch: pytest.MonkeyPatch,
313	343	config: str,
314	344	) -> None:
	345	+ """Fail on bad or unsupported bucket file contents.
	346	+
	347	+ These include unknown versions, invalid JSON, or JSON of the
	348	+ wrong shape.
	349	+
	350	+ """
315	351	runner = click.testing.CliRunner(mix_stderr=False)
316	352	master_keys = _types.StoreroomMasterKeys(
317	353	encryption_key=bytes(storeroom.KEY_SIZE),
...	...	@@ -363,6 +399,11 @@ class TestStoreroom:
363	399	err_msg: str,
364	400	handler: exporter.ExportVaultConfigDataFunction,
365	401	) -> None:
	402	+ """Fail on bad or unsupported master keys file contents.
	403	+
	404	+ These include unknown versions, and data of the wrong shape.
	405	+
	406	+ """
366	407	runner = click.testing.CliRunner(mix_stderr=False)
367	408	with tests.isolated_vault_exporter_config(
368	409	monkeypatch=monkeypatch,
...	...	@@ -415,6 +456,20 @@ class TestStoreroom:
415	456	error_text: str,
416	457	handler: exporter.ExportVaultConfigDataFunction,
417	458	) -> None:
	459	+ """Fail on bad decoded directory structures.
	460	+
	461	+ If the decoded configuration contains directories whose
	462	+ structures are inconsistent, it detects this and fails:
	463	+
	464	+ - The key indicates a directory, but the contents don't.
	465	+ - The directory indicates children with invalid path names.
	466	+ - The directory indicates children that are missing from the
	467	+ configuration entirely.
	468	+ - The configuration contains nested subdirectories, but the
	469	+ higher-level directories don't indicate their
	470	+ subdirectories.
	471	+
	472	+ """
418	473	runner = click.testing.CliRunner(mix_stderr=False)
419	474	# TODO(the-13th-letter): Rewrite using parenthesized
420	475	# with-statements.
...	...	@@ -432,6 +487,15 @@ class TestStoreroom:
432	487	handler(format='storeroom')
433	488
434	489	def test_404_decrypt_keys_wrong_data_length(self) -> None:
	490	+ """Fail on internal structural data of the wrong size.
	491	+
	492	+ Specifically, fail on internal structural data such as master
	493	+ keys or session keys that is correctly encrypted according to
	494	+ its MAC, but is of the wrong shape. (Since the data usually are
	495	+ keys and thus are opaque, the only detectable shape violation is
	496	+ the wrong size of the data.)
	497	+
	498	+ """
435	499	payload = (
436	500	b"Any text here, as long as it isn't exactly 64 or 96 bytes long."
437	501	)
...	...	@@ -480,6 +544,7 @@ class TestStoreroom:
480	544	),
481	545	)
482	546	def test_405_decrypt_keys_invalid_signature(self, data: bytes) -> None:
	547	+ """Fail on bad MAC values."""
483	548	key = b'DEADBEEFdeadbeefDeAdBeEfdEaDbEeF'
484	549	# Guessing a correct payload plus MAC would be a pre-image
485	550	# attack on the underlying hash function (SHA-256), i.e. is
...	...	@@ -500,6 +565,8 @@ class TestStoreroom:
500	565
501	566
502	567	class TestVaultNativeConfig:
	568	+ """Test the vault-native handler and handler machinery."""
	569	+
503	570	@pytest.mark.parametrize(
504	571	['iterations', 'result'],
505	572	[
...	...	@@ -508,6 +575,7 @@ class TestVaultNativeConfig:
508	575	],
509	576	)
510	577	def test_200_pbkdf2_manually(self, iterations: int, result: bytes) -> None:
	578	+ """The PBKDF2 helper function works."""
511	579	assert (
512	580	vault_native.VaultNativeConfigParser._pbkdf2(
513	581	tests.VAULT_MASTER_KEY.encode('utf-8'), 32, iterations
...	...	@@ -551,7 +619,7 @@ class TestVaultNativeConfig:
551	619	pytest.param(exporter.export_vault_config_data, id='dispatcher'),
552	620	],
553	621	)
554		- def test_201_export_vault_native_data_no_arguments(
	622	+ def test_201_export_vault_native_data_explicit_version(
555	623	self,
556	624	monkeypatch: pytest.MonkeyPatch,
557	625	config: str,
...	...	@@ -559,6 +627,16 @@ class TestVaultNativeConfig:
559	627	result: _types.VaultConfig \| type[Exception],
560	628	handler: exporter.ExportVaultConfigDataFunction,
561	629	) -> None:
	630	+ """Accept data only of the correct version.
	631	+
	632	+ Note: Historic behavior
	633	+ `derivepassphrase` versions prior to 0.5 automatically tried
	634	+ to parse vault-native configurations as v0.3-type, then
	635	+ v0.2-type. Since `derivepassphrase` 0.5, the command-line
	636	+ interface still tries multi-version parsing, but the API
	637	+ no longer does.
	638	+
	639	+ """
562	640	runner = click.testing.CliRunner(mix_stderr=False)
563	641	with tests.isolated_vault_exporter_config(
564	642	monkeypatch=monkeypatch,
...	...	@@ -604,6 +682,12 @@ class TestVaultNativeConfig:
604	682	key: str \| Buffer \| None,
605	683	handler: exporter.ExportVaultConfigDataFunction,
606	684	) -> None:
	685	+ """The handler supports different argument types.
	686	+
	687	+ The [`exporter.export_vault_config_data`][] dispatcher supports
	688	+ them as well.
	689	+
	690	+ """
607	691	runner = click.testing.CliRunner(mix_stderr=False)
608	692	with tests.isolated_vault_exporter_config(
609	693	monkeypatch=monkeypatch,
...	...	@@ -640,6 +724,8 @@ class TestVaultNativeConfig:
640	724	config: str,
641	725	result: dict[str, Any],
642	726	) -> None:
	727	+ """Cache the results of decrypting/decoding a configuration."""
	728	+
643	729	def null_func(name: str) -> Callable[..., None]:
644	730	def func(_args: Any, *_kwargs: Any) -> None: # pragma: no cover
645	731	msg = f'disallowed and stubbed out function {name} called'
...	...	@@ -675,5 +761,6 @@ class TestVaultNativeConfig:
675	761	assert super_call(parser) == result
676	762
677	763	def test_400_no_password(self) -> None:
	764	+ """Fail on empty master keys/master passphrases."""
678	765	with pytest.raises(ValueError, match='Password must not be empty'):
679	766	vault_native.VaultNativeV03ConfigParser(b'', b'')

...	...	@@ -19,6 +19,8 @@ if TYPE_CHECKING:
19	19
20	20
21	21	class Test001ExporterUtils:
	22	+ """Test the utility functions in the `exporter` subpackage."""
	23	+
22	24	@pytest.mark.parametrize(
23	25	['expected', 'vault_key', 'logname', 'user', 'username'],
24	26	[
...	...	@@ -48,6 +50,12 @@ class Test001ExporterUtils:
48	50	user: str \| None,
49	51	username: str \| None,
50	52	) -> None:
	53	+ """Look up the vault key in `VAULT_KEY`/`LOGNAME`/`USER`/`USERNAME`.
	54	+
	55	+ The correct environment variable value is used, according to
	56	+ their relative priorities.
	57	+
	58	+ """
51	59	priority_list = [
52	60	('VAULT_KEY', vault_key),
53	61	('LOGNAME', logname),
...	...	@@ -77,6 +85,11 @@ class Test001ExporterUtils:
77	85	expected: pathlib.Path,
78	86	path: str \| os.PathLike[str] \| None,
79	87	) -> None:
	88	+ """Determine the vault path from `VAULT_PATH`.
	89	+
	90	+ Handle relative paths, absolute paths, and missing paths.
	91	+
	92	+ """
80	93	runner = click.testing.CliRunner(mix_stderr=False)
81	94	with tests.isolated_vault_exporter_config(
82	95	monkeypatch=monkeypatch, runner=runner
...	...	@@ -93,6 +106,8 @@ class Test001ExporterUtils:
93	106	def test_220_register_export_vault_config_data_handler(
94	107	self, monkeypatch: pytest.MonkeyPatch
95	108	) -> None:
	109	+ """Register vault config data export handlers."""
	110	+
96	111	def handler( # pragma: no cover
97	112	path: str \| bytes \| os.PathLike \| None = None,
98	113	key: str \| Buffer \| None = None,
...	...	@@ -120,6 +135,7 @@ class Test001ExporterUtils:
120	135	def test_300_get_vault_key_without_envs(
121	136	self, monkeypatch: pytest.MonkeyPatch
122	137	) -> None:
	138	+ """Fail to look up the vault key in the empty environment."""
123	139	monkeypatch.delenv('VAULT_KEY', raising=False)
124	140	monkeypatch.delenv('LOGNAME', raising=False)
125	141	monkeypatch.delenv('USER', raising=False)
...	...	@@ -130,6 +146,8 @@ class Test001ExporterUtils:
130	146	def test_310_get_vault_path_without_home(
131	147	self, monkeypatch: pytest.MonkeyPatch
132	148	) -> None:
	149	+ """Fail to look up the vault path without `HOME`."""
	150	+
133	151	def raiser(_args: Any, *_kwargs: Any) -> Any:
134	152	raise RuntimeError('Cannot determine home directory.') # noqa: EM101,TRY003
135	153
...	...	@@ -162,6 +180,13 @@ class Test001ExporterUtils:
162	180	namelist: tuple[str, ...],
163	181	err_pat: str,
164	182	) -> None:
	183	+ """Fail to register a vault config data export handler.
	184	+
	185	+ Fail because e.g. the associated name is missing, or already
	186	+ present in the handler registry.
	187	+
	188	+ """
	189	+
165	190	def handler( # pragma: no cover
166	191	path: str \| bytes \| os.PathLike \| None = None,
167	192	key: str \| Buffer \| None = None,
...	...	@@ -183,6 +208,7 @@ class Test001ExporterUtils:
183	208	def test_321_export_vault_config_data_bad_handler(
184	209	self, monkeypatch: pytest.MonkeyPatch
185	210	) -> None:
	211	+ """Fail to export vault config data without known handlers."""
186	212	monkeypatch.setattr(exporter, '_export_vault_config_data_registry', {})
187	213	monkeypatch.setattr(
188	214	exporter, 'find_vault_config_data_handlers', lambda: None
...	...	@@ -195,10 +221,13 @@ class Test001ExporterUtils:
195	221
196	222
197	223	class Test002CLI:
	224	+ """Test the command-line functionality of the `exporter` subpackage."""
	225	+
198	226	def test_300_invalid_format(
199	227	self,
200	228	monkeypatch: pytest.MonkeyPatch,
201	229	) -> None:
	230	+ """Reject invalid vault configuration format names."""
202	231	runner = click.testing.CliRunner(mix_stderr=False)
203	232	with tests.isolated_vault_exporter_config(
204	233	monkeypatch=monkeypatch,
...	...	@@ -249,6 +278,7 @@ class Test002CLI:
249	278	config: str \| bytes,
250	279	key: str,
251	280	) -> None:
	281	+ """Abort export call if no cryptography is available."""
252	282	runner = click.testing.CliRunner(mix_stderr=False)
253	283	with tests.isolated_vault_exporter_config(
254	284	monkeypatch=monkeypatch,

...	...	@@ -19,6 +19,8 @@ def bitseq(string: str) -> list[int]:
19	19
20	20
21	21	class TestStaticFunctionality:
	22	+ """Test the static functionality in the `sequin` module."""
	23	+
22	24	@pytest.mark.parametrize(
23	25	['sequence', 'base', 'expected'],
24	26	[
...	...	@@ -32,6 +34,11 @@ class TestStaticFunctionality:
32	34	def test_200_big_endian_number(
33	35	self, sequence: list[int], base: int, expected: int
34	36	) -> None:
	37	+ """Conversion to big endian numbers in any base works.
	38	+
	39	+ See [`sequin.Sequin.generate`][] for where this is used.
	40	+
	41	+ """
35	42	assert (
36	43	sequin.Sequin._big_endian_number(sequence, base=base)
37	44	) == expected
...	...	@@ -51,11 +58,18 @@ class TestStaticFunctionality:
51	58	sequence: list[int],
52	59	base: int,
53	60	) -> None:
	61	+ """Nonsensical conversion of numbers in a given base raises.
	62	+
	63	+ See [`sequin.Sequin.generate`][] for where this is used.
	64	+
	65	+ """
54	66	with pytest.raises(exc_type, match=exc_pattern):
55	67	sequin.Sequin._big_endian_number(sequence, base=base)
56	68
57	69
58	70	class TestSequin:
	71	+ """Test the `Sequin` class."""
	72	+
59	73	@pytest.mark.parametrize(
60	74	['sequence', 'is_bitstring', 'expected'],
61	75	[
...	...	@@ -75,10 +89,12 @@ class TestSequin:
75	89	is_bitstring: bool,
76	90	expected: list[int],
77	91	) -> None:
	92	+ """The constructor handles both bit and integer sequences."""
78	93	seq = sequin.Sequin(sequence, is_bitstring=is_bitstring)
79	94	assert seq.bases == {2: collections.deque(expected)}
80	95
81	96	def test_201_generating(self) -> None:
	97	+ """The sequin generates deterministic sequences."""
82	98	seq = sequin.Sequin(
83	99	[1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 0, 1], is_bitstring=True
84	100	)
...	...	@@ -97,6 +113,7 @@ class TestSequin:
97	113	seq.generate(0)
98	114
99	115	def test_210_internal_generating(self) -> None:
	116	+ """The sequin internals generate deterministic sequences."""
100	117	seq = sequin.Sequin(
101	118	[1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 0, 1], is_bitstring=True
102	119	)
...	...	@@ -115,6 +132,12 @@ class TestSequin:
115	132	seq._generate_inner(16, base=1)
116	133
117	134	def test_211_shifting(self) -> None:
	135	+ """The sequin manages the pool of remaining entropy for each base.
	136	+
	137	+ Specifically, the sequin implements all-or-nothing fixed-length
	138	+ draws from the entropy pool.
	139	+
	140	+ """
118	141	seq = sequin.Sequin([1, 0, 1, 0, 0, 1, 0, 0, 0, 1], is_bitstring=True)
119	142	assert seq.bases == {
120	143	2: collections.deque([1, 0, 1, 0, 0, 1, 0, 0, 0, 1])
...	...	@@ -149,5 +172,6 @@ class TestSequin:
149	172	exc_type: type[Exception],
150	173	exc_pattern: str,
151	174	) -> None:
	175	+ """The sequin raises on invalid bit and integer sequences."""
152	176	with pytest.raises(exc_type, match=exc_pattern):
153	177	sequin.Sequin(sequence, is_bitstring=is_bitstring)

...	...	@@ -28,6 +28,10 @@ if TYPE_CHECKING:
28	28
29	29
30	30	class TestStaticFunctionality:
	31	+ """Test the static functionality of the `ssh_agent` module."""
	32	+
	33	+ # TODO(the-13th-letter): Re-evaluate if this check is worth keeping.
	34	+ # It cannot provide true tamper-resistence, but probably appears to.
31	35	@pytest.mark.parametrize(
32	36	['public_key', 'public_key_data'],
33	37	[
...	...	@@ -39,6 +43,7 @@ class TestStaticFunctionality:
39	43	def test_100_key_decoding(
40	44	self, public_key: bytes, public_key_data: bytes
41	45	) -> None:
	46	+ """The [`tests.ALL_KEYS`][] public key data looks sane."""
42	47	keydata = base64.b64decode(public_key.split(None, 2)[1])
43	48	assert keydata == public_key_data, (
44	49	"recorded public key data doesn't match"
...	...	@@ -118,6 +123,7 @@ class TestStaticFunctionality:
118	123	def test_190_sh_export_line_parsing(
119	124	self, line: str, env_name: str, value: str \| None
120	125	) -> None:
	126	+ """[`tests.parse_sh_export_line`][] works."""
121	127	if value is not None:
122	128	assert tests.parse_sh_export_line(line, env_name=env_name) == value
123	129	else:
...	...	@@ -129,6 +135,7 @@ class TestStaticFunctionality:
129	135	monkeypatch: pytest.MonkeyPatch,
130	136	skip_if_no_af_unix_support: None,
131	137	) -> None:
	138	+ """Abort if the running agent cannot be located."""
132	139	del skip_if_no_af_unix_support
133	140	monkeypatch.delenv('SSH_AUTH_SOCK', raising=False)
134	141	with pytest.raises(
...	...	@@ -143,6 +150,7 @@ class TestStaticFunctionality:
143	150	],
144	151	)
145	152	def test_210_uint32(self, input: int, expected: bytes \| bytearray) -> None:
	153	+ """`uint32` encoding works."""
146	154	uint32 = ssh_agent.SSHAgentClient.uint32
147	155	assert uint32(input) == expected
148	156
...	...	@@ -169,6 +177,7 @@ class TestStaticFunctionality:
169	177	def test_211_string(
170	178	self, input: bytes \| bytearray, expected: bytes \| bytearray
171	179	) -> None:
	180	+ """SSH string encoding works."""
172	181	string = ssh_agent.SSHAgentClient.string
173	182	assert bytes(string(input)) == expected
174	183
...	...	@@ -190,6 +199,7 @@ class TestStaticFunctionality:
190	199	def test_212_unstring(
191	200	self, input: bytes \| bytearray, expected: bytes \| bytearray
192	201	) -> None:
	202	+ """SSH string decoding works."""
193	203	unstring = ssh_agent.SSHAgentClient.unstring
194	204	unstring_prefix = ssh_agent.SSHAgentClient.unstring_prefix
195	205	assert bytes(unstring(input)) == expected
...	...	@@ -218,6 +228,7 @@ class TestStaticFunctionality:
218	228	def test_310_uint32_exceptions(
219	229	self, value: int, exc_type: type[Exception], exc_pattern: str
220	230	) -> None:
	231	+ """`uint32` encoding fails for out-of-bound values."""
221	232	uint32 = ssh_agent.SSHAgentClient.uint32
222	233	with pytest.raises(exc_type, match=exc_pattern):
223	234	uint32(value)
...	...	@@ -233,6 +244,7 @@ class TestStaticFunctionality:
233	244	def test_311_string_exceptions(
234	245	self, input: Any, exc_type: type[Exception], exc_pattern: str
235	246	) -> None:
	247	+ """SSH string encoding fails for non-strings."""
236	248	string = ssh_agent.SSHAgentClient.string
237	249	with pytest.raises(exc_type, match=exc_pattern):
238	250	string(input)
...	...	@@ -274,6 +286,7 @@ class TestStaticFunctionality:
274	286	has_trailer: bool,
275	287	parts: tuple[bytes \| bytearray, bytes \| bytearray] \| None,
276	288	) -> None:
	289	+ """SSH string decoding fails for invalid values."""
277	290	unstring = ssh_agent.SSHAgentClient.unstring
278	291	unstring_prefix = ssh_agent.SSHAgentClient.unstring_prefix
279	292	with pytest.raises(exc_type, match=exc_pattern):
...	...	@@ -286,6 +299,11 @@ class TestStaticFunctionality:
286	299
287	300
288	301	class TestAgentInteraction:
	302	+ """Test actually talking to the SSH agent."""
	303	+
	304	+ # TODO(the-13th-letter): Convert skip into xfail, and include the
	305	+ # key type in the skip/xfail message. This means the key type needs
	306	+ # to be passed to the test function as well.
289	307	@pytest.mark.parametrize(
290	308	'ssh_test_key',
291	309	list(tests.SUPPORTED_KEYS.values()),
...	...	@@ -296,6 +314,13 @@ class TestAgentInteraction:
296	314	ssh_agent_client_with_test_keys_loaded: ssh_agent.SSHAgentClient,
297	315	ssh_test_key: tests.SSHTestKey,
298	316	) -> None:
	317	+ """Signing data with specific SSH keys works.
	318	+
	319	+ Single tests may abort early (skip) if the indicated key is not
	320	+ loaded in the agent. Presumably this means the key type is
	321	+ unsupported.
	322	+
	323	+ """
299	324	client = ssh_agent_client_with_test_keys_loaded
300	325	key_comment_pairs = {bytes(k): bytes(c) for k, c in client.list_keys()}
301	326	public_key_data = ssh_test_key.public_key_data
...	...	@@ -318,6 +343,9 @@ class TestAgentInteraction:
318	343	== derived_passphrase
319	344	), 'SSH signature mismatch'
320	345
	346	+ # TODO(the-13th-letter): Include the key type in the skip message.
	347	+ # This means the key type needs to be passed to the test function as
	348	+ # well.
321	349	@pytest.mark.parametrize(
322	350	'ssh_test_key',
323	351	list(tests.UNSUITABLE_KEYS.values()),
...	...	@@ -328,6 +356,15 @@ class TestAgentInteraction:
328	356	ssh_agent_client_with_test_keys_loaded: ssh_agent.SSHAgentClient,
329	357	ssh_test_key: tests.SSHTestKey,
330	358	) -> None:
	359	+ """Using an unsuitable key with [`vault.Vault`][] fails.
	360	+
	361	+ Single tests may abort early (skip) if the indicated key is not
	362	+ loaded in the agent. Presumably this means the key type is
	363	+ unsupported. Single tests may also abort early if the agent
	364	+ ensures that the generally unsuitable key is actually suitable
	365	+ under this agent.
	366	+
	367	+ """
331	368	client = ssh_agent_client_with_test_keys_loaded
332	369	key_comment_pairs = {bytes(k): bytes(c) for k, c in client.list_keys()}
333	370	public_key_data = ssh_test_key.public_key_data
...	...	@@ -357,9 +394,16 @@ class TestAgentInteraction:
357	394	key: bytes,
358	395	single: bool,
359	396	) -> None:
	397	+ """The key selector presents exactly the suitable keys.
	398	+
	399	+ "Suitable" here means suitability for this SSH agent
	400	+ specifically.
	401	+
	402	+ """
360	403	client = ssh_agent_client_with_test_keys_loaded
361	404
362	405	def key_is_suitable(key: bytes) -> bool:
	406	+ """Stub out [`vault.Vault.key_is_suitable`][]."""
363	407	always = {v.public_key_data for v in tests.SUPPORTED_KEYS.values()}
364	408	dsa = {
365	409	v.public_key_data
...	...	@@ -370,6 +414,11 @@ class TestAgentInteraction:
370	414	client.has_deterministic_dsa_signatures() and key in dsa
371	415	)
372	416
	417	+ # TODO(the-13th-letter): Handle the unlikely(?) case that only
	418	+ # one test key is loaded, but `single` is False. Rename the
	419	+ # `index` variable to `input`, store the `input` in there, and
	420	+ # make the definition of `text` in the else block dependent on
	421	+ # `n` being singular or non-singular.
373	422	if single:
374	423	monkeypatch.setattr(
375	424	ssh_agent.SSHAgentClient,
...	...	@@ -399,9 +448,12 @@ class TestAgentInteraction:
399	448
400	449	@click.command()
401	450	def driver() -> None:
	451	+ """Call `cli._select_ssh_key` directly, as a command."""
402	452	key = cli._select_ssh_key()
403	453	click.echo(base64.standard_b64encode(key).decode('ASCII'))
404	454
	455	+ # TODO(the-13th-letter): (Continued from above.) Update input
	456	+ # data to use `index`/`input` directly and unconditionally.
405	457	runner = click.testing.CliRunner(mix_stderr=True)
406	458	result_ = runner.invoke(
407	459	driver,
...	...	@@ -418,6 +470,7 @@ class TestAgentInteraction:
418	470	monkeypatch: pytest.MonkeyPatch,
419	471	running_ssh_agent: tests.RunningSSHAgentInfo,
420	472	) -> None:
	473	+ """Fail if the agent address is invalid."""
421	474	with monkeypatch.context() as monkeypatch2:
422	475	monkeypatch2.setenv(
423	476	'SSH_AUTH_SOCK', running_ssh_agent.socket + '~'
...	...	@@ -430,6 +483,7 @@ class TestAgentInteraction:
430	483	self,
431	484	monkeypatch: pytest.MonkeyPatch,
432	485	) -> None:
	486	+ """Fail without [`socket.AF_UNIX`][] support."""
433	487	with monkeypatch.context() as monkeypatch2:
434	488	monkeypatch2.setenv('SSH_AUTH_SOCK', "the value doesn't matter")
435	489	monkeypatch2.delattr(socket, 'AF_UNIX', raising=False)
...	...	@@ -453,6 +507,7 @@ class TestAgentInteraction:
453	507	running_ssh_agent: tests.RunningSSHAgentInfo,
454	508	response: bytes,
455	509	) -> None:
	510	+ """Fail on truncated responses from the SSH agent."""
456	511	del running_ssh_agent
457	512	client = ssh_agent.SSHAgentClient()
458	513	response_stream = io.BytesIO(response)
...	...	@@ -504,6 +559,16 @@ class TestAgentInteraction:
504	559	exc_type: type[Exception],
505	560	exc_pattern: str,
506	561	) -> None:
	562	+ """Fail on problems during key listing.
	563	+
	564	+ Known problems:
	565	+
	566	+ - The agent refuses, or otherwise indicates the operation
	567	+ failed.
	568	+ - The agent response is truncated.
	569	+ - The agent response is overlong.
	570	+
	571	+ """
507	572	del running_ssh_agent
508	573
509	574	passed_response_code = response_code
...	...	@@ -584,6 +649,15 @@ class TestAgentInteraction:
584	649	exc_type: type[Exception],
585	650	exc_pattern: str,
586	651	) -> None:
	652	+ """Fail on problems during signing.
	653	+
	654	+ Known problems:
	655	+
	656	+ - The key is not loaded into the agent.
	657	+ - The agent refuses, or otherwise indicates the operation
	658	+ failed.
	659	+
	660	+ """
587	661	del running_ssh_agent
588	662	passed_response_code = response_code
589	663
...	...	@@ -651,6 +725,15 @@ class TestAgentInteraction:
651	725	exc_type: type[Exception],
652	726	exc_pattern: str,
653	727	) -> None:
	728	+ """Fail on problems during signing.
	729	+
	730	+ Known problems:
	731	+
	732	+ - The key is not loaded into the agent.
	733	+ - The agent refuses, or otherwise indicates the operation
	734	+ failed.
	735	+
	736	+ """
654	737	del running_ssh_agent
655	738
656	739	# TODO(the-13th-letter): Rewrite using parenthesized
...	...	@@ -683,6 +766,7 @@ class TestAgentInteraction:
683	766	running_ssh_agent: tests.RunningSSHAgentInfo,
684	767	response_data: bytes,
685	768	) -> None:
	769	+ """Fail on malformed responses while querying extensions."""
686	770	del running_ssh_agent
687	771
688	772	def request(
...	...	@@ -738,17 +822,21 @@ class TestAgentInteraction:
738	822
739	823
740	824	class TestHypotheses:
	825	+ """Test properties via hypothesis."""
	826	+
741	827	@hypothesis.given(strategies.integers(min_value=0, max_value=0xFFFFFFFF))
742	828	# standard example value
743	829	@hypothesis.example(0xDEADBEEF)
744		- def test_210_uint32(self, num: int) -> None:
	830	+ def test_210a_uint32_from_number(self, num: int) -> None:
	831	+ """`uint32` encoding works, starting from numbers."""
745	832	uint32 = ssh_agent.SSHAgentClient.uint32
746	833	assert int.from_bytes(uint32(num), 'big', signed=False) == num
747	834
748	835	@hypothesis.given(strategies.binary(min_size=4, max_size=4))
749	836	# standard example value
750	837	@hypothesis.example(b'\xde\xad\xbe\xef')
751		- def test_210a_uint32(self, bytestring: bytes) -> None:
	838	+ def test_210b_uint32_from_bytestring(self, bytestring: bytes) -> None:
	839	+ """`uint32` encoding works, starting from length four byte strings."""
752	840	uint32 = ssh_agent.SSHAgentClient.uint32
753	841	assert (
754	842	uint32(int.from_bytes(bytestring, 'big', signed=False))
...	...	@@ -758,7 +846,8 @@ class TestHypotheses:
758	846	@hypothesis.given(strategies.binary(max_size=0x0001FFFF))
759	847	# example: highest order bit is set
760	848	@hypothesis.example(b'DEADBEEF' * 10000)
761		- def test_211_string(self, bytestring: bytes) -> None:
	849	+ def test_211a_string_from_bytestring(self, bytestring: bytes) -> None:
	850	+ """SSH string encoding works, starting from a byte string."""
762	851	res = ssh_agent.SSHAgentClient.string(bytestring)
763	852	assert res.startswith((b'\x00\x00', b'\x00\x01'))
764	853	assert int.from_bytes(res[:4], 'big', signed=False) == len(bytestring)
...	...	@@ -768,6 +857,7 @@ class TestHypotheses:
768	857	# example: check for double-deserialization
769	858	@hypothesis.example(b'\x00\x00\x00\x07ssh-rsa')
770	859	def test_212_string_unstring(self, bytestring: bytes) -> None:
	860	+ """SSH string decoding of encoded SSH strings works."""
771	861	string = ssh_agent.SSHAgentClient.string
772	862	unstring = ssh_agent.SSHAgentClient.unstring
773	863	unstring_prefix = ssh_agent.SSHAgentClient.unstring_prefix

...	...	@@ -24,9 +24,20 @@ Vault: TypeAlias = derivepassphrase.vault.Vault
24	24
25	25
26	26	class TestVault:
	27	+ """Test passphrase derivation with the "vault" scheme."""
	28	+
27	29	phrase = b'She cells C shells bye the sea shoars'
	30	+ """The standard passphrase from <i>vault</i>(1)'s test suite."""
28	31	google_phrase = rb': 4TVH#5:aZl8LueOT\{'
	32	+ """
	33	+ The standard derived passphrase for the "google" service, from
	34	+ <i>vault</i>(1)'s test suite.
	35	+ """
29	36	twitter_phrase = rb"[ (HN_N:lI&<ro=)3'g9"
	37	+ """
	38	+ The standard derived passphrase for the "twitter" service, from
	39	+ <i>vault</i>(1)'s test suite.
	40	+ """
30	41
31	42	@pytest.mark.parametrize(
32	43	['service', 'expected'],
...	...	@@ -38,30 +49,36 @@ class TestVault:
38	49	def test_200_basic_configuration(
39	50	self, service: bytes \| str, expected: bytes
40	51	) -> None:
	52	+ """Deriving a passphrase principally works."""
41	53	assert Vault(phrase=self.phrase).generate(service) == expected
42	54
43	55	def test_201_phrase_dependence(self) -> None:
	56	+ """The derived passphrase is dependent on the master passphrase."""
44	57	assert (
45	58	Vault(phrase=(self.phrase + b'X')).generate('google')
46	59	== b'n+oIz6sL>K*lTEWYRO%7'
47	60	)
48	61
49	62	def test_202_reproducibility_and_bytes_service_name(self) -> None:
	63	+ """Deriving a passphrase works equally for byte strings."""
50	64	assert Vault(phrase=self.phrase).generate(b'google') == Vault(
51	65	phrase=self.phrase
52	66	).generate('google')
53	67
54	68	def test_203_reproducibility_and_bytearray_service_name(self) -> None:
	69	+ """Deriving a passphrase works equally for byte arrays."""
55	70	assert Vault(phrase=self.phrase).generate(b'google') == Vault(
56	71	phrase=self.phrase
57	72	).generate(bytearray(b'google'))
58	73
59	74	def test_210_nonstandard_length(self) -> None:
	75	+ """Deriving a passphrase adheres to imposed length limits."""
60	76	assert (
61	77	Vault(phrase=self.phrase, length=4).generate('google') == b'xDFu'
62	78	)
63	79
64	80	def test_211_repetition_limit(self) -> None:
	81	+ """Deriving a passphrase adheres to imposed repetition limits."""
65	82	assert (
66	83	Vault(
67	84	phrase=b'', length=24, symbol=0, number=0, repeat=1
...	...	@@ -70,36 +87,44 @@ class TestVault:
70	87	)
71	88
72	89	def test_212_without_symbols(self) -> None:
	90	+ """Deriving a passphrase adheres to imposed limits on symbols."""
73	91	assert (
74	92	Vault(phrase=self.phrase, symbol=0).generate('google')
75	93	== b'XZ4wRe0bZCazbljCaMqR'
76	94	)
77	95
78	96	def test_213_no_numbers(self) -> None:
	97	+ """Deriving a passphrase adheres to imposed limits on numbers."""
79	98	assert (
80	99	Vault(phrase=self.phrase, number=0).generate('google')
81	100	== b'_*$TVH.%^aZl(LUeOT?>'
82	101	)
83	102
84	103	def test_214_no_lowercase_letters(self) -> None:
	104	+ """
	105	+ Deriving a passphrase adheres to imposed limits on lowercase letters.
	106	+ """
85	107	assert (
86	108	Vault(phrase=self.phrase, lower=0).generate('google')
87	109	== b':{?)+7~@OA:L]!0E$)(+'
88	110	)
89	111
90	112	def test_215_at_least_5_digits(self) -> None:
	113	+ """Deriving a passphrase adheres to imposed counts of numbers."""
91	114	assert (
92	115	Vault(phrase=self.phrase, length=8, number=5).generate('songkick')
93	116	== b'i0908.7['
94	117	)
95	118
96	119	def test_216_lots_of_spaces(self) -> None:
	120	+ """Deriving a passphrase adheres to imposed counts of spaces."""
97	121	assert (
98	122	Vault(phrase=self.phrase, space=12).generate('songkick')
99	123	== b' c 6 Bq % 5fR '
100	124	)
101	125
102	126	def test_217_all_character_classes(self) -> None:
	127	+ """Deriving a passphrase adheres to imposed counts of all types."""
103	128	assert (
104	129	Vault(
105	130	phrase=self.phrase,
...	...	@@ -114,6 +139,11 @@ class TestVault:
114	139	)
115	140
116	141	def test_218_only_numbers_and_very_high_repetition_limit(self) -> None:
	142	+ """Deriving a passphrase adheres to imposed repetition limits.
	143	+
	144	+ This example is checked explicitly against forbidden substrings.
	145	+
	146	+ """
117	147	generated = Vault(
118	148	phrase=b'',
119	149	length=40,
...	...	@@ -140,12 +170,14 @@ class TestVault:
140	170	assert substring not in generated
141	171
142	172	def test_219_very_limited_character_set(self) -> None:
	173	+ """Deriving a passphrase works even with limited character sets."""
143	174	generated = Vault(
144	175	phrase=b'', length=24, lower=0, upper=0, space=0, symbol=0
145	176	).generate('testing')
146	177	assert generated == b'763252593304946694588866'
147	178
148	179	def test_220_character_set_subtraction(self) -> None:
	180	+ """Removing allowed characters internally works."""
149	181	assert Vault._subtract(b'be', b'abcdef') == bytearray(b'acdf')
150	182
151	183	@pytest.mark.parametrize(
...	...	@@ -170,6 +202,7 @@ class TestVault:
170	202	def test_221_entropy(
171	203	self, length: int, settings: dict[str, int], entropy: int
172	204	) -> None:
	205	+ """Estimating the entropy and sufficient hash length works."""
173	206	v = Vault(length=length, **settings) # type: ignore[arg-type]
174	207	assert math.isclose(v._entropy(), entropy)
175	208	assert v._estimate_sufficient_hash_length() > 0
...	...	@@ -180,6 +213,9 @@ class TestVault:
180	213	assert v._estimate_sufficient_hash_length(8.0) >= entropy
181	214
182	215	def test_222_hash_length_estimation(self) -> None:
	216	+ """
	217	+ Estimating the entropy and hash length for degenerate cases works.
	218	+ """
183	219	v = Vault(
184	220	phrase=self.phrase,
185	221	lower=0,
...	...	@@ -205,6 +241,9 @@ class TestVault:
205	241	service: str \| bytes,
206	242	expected: bytes,
207	243	) -> None:
	244	+ """
	245	+ Estimating the entropy and hash length for the degenerate case works.
	246	+ """
208	247	v = Vault(phrase=self.phrase)
209	248	monkeypatch.setattr(
210	249	v,
...	...	@@ -226,6 +265,7 @@ class TestVault:
226	265	],
227	266	)
228	267	def test_224_binary_strings(self, s: str \| bytes \| bytearray) -> None:
	268	+ """Byte string conversion is idempotent."""
229	269	binstr = Vault._get_binary_string
230	270	if isinstance(s, str):
231	271	assert binstr(s) == s.encode('UTF-8')
...	...	@@ -235,12 +275,14 @@ class TestVault:
235	275	assert binstr(binstr(s)) == bytes(s)
236	276
237	277	def test_310_too_many_symbols(self) -> None:
	278	+ """Deriving short passphrases with large length constraints fails."""
238	279	with pytest.raises(
239	280	ValueError, match='requested passphrase length too short'
240	281	):
241	282	Vault(phrase=self.phrase, symbol=100)
242	283
243	284	def test_311_no_viable_characters(self) -> None:
	285	+ """Deriving passphrases without allowed characters fails."""
244	286	with pytest.raises(ValueError, match='no allowed characters left'):
245	287	Vault(
246	288	phrase=self.phrase,
...	...	@@ -253,12 +295,14 @@ class TestVault:
253	295	)
254	296
255	297	def test_320_character_set_subtraction_duplicate(self) -> None:
	298	+ """Character sets do not contain duplicate characters."""
256	299	with pytest.raises(ValueError, match='duplicate characters'):
257	300	Vault._subtract(b'abcdef', b'aabbccddeeff')
258	301	with pytest.raises(ValueError, match='duplicate characters'):
259	302	Vault._subtract(b'aabbccddeeff', b'abcdef')
260	303
261	304	def test_322_hash_length_estimation(self) -> None:
	305	+ """Hash length estimation rejects invalid safety factors."""
262	306	v = Vault(phrase=self.phrase)
263	307	with pytest.raises(ValueError, match='invalid safety factor'):
264	308	assert v._estimate_sufficient_hash_length(-1.0)
...	...	@@ -269,6 +313,8 @@ class TestVault:
269	313
270	314
271	315	class TestHypotheses:
	316	+ """Test properties via hypothesis."""
	317	+
272	318	@tests.hypothesis_settings_coverage_compatible
273	319	@hypothesis.given(
274	320	phrase=strategies.one_of(
...	...	@@ -328,6 +374,7 @@ class TestHypotheses:
328	374	config: dict[str, int],
329	375	service: str,
330	376	) -> None:
	377	+ """Derived passphrases obey character and occurrence restraints."""
331	378	try:
332	379	password = Vault(phrase=phrase, **config).generate(service)
333	380	except ValueError as exc:
...	...	@@ -386,6 +433,7 @@ class TestHypotheses:
386	433	length: int,
387	434	service: str,
388	435	) -> None:
	436	+ """Derived passphrases have the requested length."""
389	437	password = Vault(phrase=phrase, length=length).generate(service)
390	438	assert len(password) == length
391	439
...	...	@@ -412,6 +460,7 @@ class TestHypotheses:
412	460	repeat: int,
413	461	service: str,
414	462	) -> None:
	463	+ """Derived passphrases obey the given occurrence constraint."""
415	464	password = Vault(phrase=phrase, length=length, repeat=repeat).generate(
416	465	service
417	466	)

...	...	@@ -42,6 +42,7 @@ all_translatable_strings = [
42	42
43	43	@pytest.fixture(scope='class')
44	44	def use_debug_translations() -> Iterator[None]:
	45	+ """Force the use of debug translations (pytest class fixture)."""
45	46	with pytest.MonkeyPatch.context() as monkeypatch:
46	47	monkeypatch.setattr(msg, 'translation', msg.DebugTranslations())
47	48	yield
...	...	@@ -49,6 +50,7 @@ def use_debug_translations() -> Iterator[None]:
49	50
50	51	@contextlib.contextmanager
51	52	def monkeypatched_null_translations() -> Iterator[None]:
	53	+ """Force the use of no-op translations in this context."""
52	54	with pytest.MonkeyPatch.context() as monkeypatch:
53	55	monkeypatch.setattr(msg, 'translation', gettext.NullTranslations())
54	56	yield
...	...	@@ -56,21 +58,29 @@ def monkeypatched_null_translations() -> Iterator[None]:
56	58
57	59	@pytest.mark.usefixtures('use_debug_translations')
58	60	class TestL10nMachineryWithDebugTranslations:
	61	+ """Test the localization machinery together with debug translations."""
59	62	error_codes = tuple(
60	63	sorted(errno.errorcode, key=errno.errorcode.__getitem__)
61	64	)
	65	+ """A cache of the known error codes from the [`errno`][] module."""
62	66	known_fields_error_messages = tuple(
63	67	e
64	68	for e in sorted(msg.ErrMsgTemplate, key=str)
65	69	if e.value.fields() == ['error', 'filename']
66	70	)
	71	+ """
	72	+ A cache of known error messages that contain both `error` and
	73	+ `filename` replacement fields.
	74	+ """
67	75	no_fields_messages = tuple(
68	76	e for e in all_translatable_strings_enum_values if not e.value.fields()
69	77	)
	78	+ """A cache of known messages that don't contain replacement fields."""
70	79
71	80	@hypothesis.given(value=strategies.text(max_size=100))
72	81	@hypothesis.example('{')
73	82	def test_100_debug_translation_get_str(self, value: str) -> None:
	83	+ """Translating a raw string object does nothing."""
74	84	translated = msg.translation.gettext(value)
75	85	assert translated == value
76	86
...	...	@@ -79,6 +89,7 @@ class TestL10nMachineryWithDebugTranslations:
79	89	self,
80	90	value: msg.TranslatableString,
81	91	) -> None:
	92	+ """Translating a TranslatableString translates and interpolates."""
82	93	ts_name = str(all_translatable_strings_dict[value])
83	94	context = value.l10n_context
84	95	singular = value.singular
...	...	@@ -94,6 +105,7 @@ class TestL10nMachineryWithDebugTranslations:
94	105	self,
95	106	value: msg.MsgTemplate,
96	107	) -> None:
	108	+ """Translating a MsgTemplate operates on the enum value."""
97	109	ts_name = str(value)
98	110	inner_value = cast('msg.TranslatableString', value.value)
99	111	context = inner_value.l10n_context
...	...	@@ -106,6 +118,7 @@ class TestL10nMachineryWithDebugTranslations:
106	118	@hypothesis.given(value=strategies.text(max_size=100))
107	119	@hypothesis.example('{')
108	120	def test_100c_debug_translation_get_ts_str(self, value: str) -> None:
	121	+ """Translating a constant TranslatableString does nothing."""
109	122	translated = msg.TranslatedString.constant(value)
110	123	assert str(translated) == value
111	124
...	...	@@ -121,6 +134,7 @@ class TestL10nMachineryWithDebugTranslations:
121	134	self,
122	135	values: list[msg.MsgTemplate],
123	136	) -> None:
	137	+ """TranslatableStrings are hashable."""
124	138	assert len(values) == 2
125	139	ts0 = msg.TranslatedString(values[0])
126	140	ts1 = msg.TranslatedString(values[0])
...	...	@@ -148,6 +162,7 @@ class TestL10nMachineryWithDebugTranslations:
148	162	value: msg.ErrMsgTemplate,
149	163	errnos: list[int],
150	164	) -> None:
	165	+ """TranslatableStrings are hashable even with interpolations."""
151	166	assert len(errnos) == 2
152	167	error1, error2 = [os.strerror(c) for c in errnos]
153	168	ts1 = msg.TranslatedString(
...	...	@@ -169,6 +184,7 @@ class TestL10nMachineryWithDebugTranslations:
169	184	value: msg.ErrMsgTemplate,
170	185	errno_: int,
171	186	) -> None:
	187	+ """Interpolated TranslatableStrings with error/filename are hashable."""
172	188	error = os.strerror(errno_)
173	189	# The debug translations specifically do not differ in output
174	190	# when the filename is trimmed. So we need to request some
...	...	@@ -190,6 +206,13 @@ class TestL10nMachineryWithDebugTranslations:
190	206	self,
191	207	s: str,
192	208	) -> None:
	209	+ """TranslatableStrings require fixed replacement fields.
	210	+
	211	+ They reject attempts at stringification if unknown fields are
	212	+ passed, or if fields are missing, or if the format string is
	213	+ invalid.
	214	+
	215	+ """
193	216	with monkeypatched_null_translations():
194	217	ts1 = msg.TranslatedString(s)
195	218	with pytest.raises((KeyError, ValueError)) as excinfo:
...	...	@@ -223,6 +246,7 @@ class TestL10nMachineryWithDebugTranslations:
223	246	self,
224	247	s: str,
225	248	) -> None:
	249	+ """Constant TranslatedStrings don't interpolate fields."""
226	250	with monkeypatched_null_translations():
227	251	ts = msg.TranslatedString.constant(s)
228	252	try:
...	...	@@ -244,6 +268,7 @@ class TestL10nMachineryWithDebugTranslations:
244	268	self,
245	269	s: str,
246	270	) -> None:
	271	+ """Non-format TranslatedStrings don't interpolate fields."""
247	272	with monkeypatched_null_translations():
248	273	ts_inner = msg.TranslatableString(
249	274	'',
250	275