Functions
	_isolate (tmp_path, monkeypatch)
	client ()
	_create (client, headers, name="Baseline", config=None)
	_share (client, doc_id, emails, *, headers=A, params=None)
	_take (client, doc_id, headers=A, params=None)
	_find (client, headers, doc_id)
	test_create_lists_and_isolates_until_shared (client)
	test_rename (client)
	test_delete_is_gone (client)
	test_autosave_load_and_history (client)
	test_history_needs_a_share (client)
	test_history_readable_once_shared (client)
	test_release_is_immutable_and_listed (client)
	test_restore_returns_older_state (client)
	test_share_grants_edit_and_writes_into_the_owners_folder (client, tmp_path)
	test_share_replaces_the_whole_list_and_drops_the_owner (client)
	test_any_editor_may_reshare (client)
	test_leave_removes_only_yourself (client)
	test_owner_cannot_leave_their_own_config (client)
	test_legacy_records_without_sharedwith_still_work (client, tmp_path)
	test_browse_groups_by_owner_and_hides_what_you_can_edit (client)
	test_copy_is_independent_and_needs_no_share (client)
	test_copy_of_a_missing_config_is_404 (client)
	_call (client, name, doc_id, headers, params)
	test_every_doc_scoped_route_is_listed ()
	test_doc_scoped_route_forbids_an_unshared_owner (client, name)
	test_doc_scoped_route_404s_a_foreign_id_without_owner (client, tmp_path, name)
	test_owner_param_cannot_escape_the_root (client, tmp_path, owner)
	test_microversion_history_is_in_write_order (client, tmp_path)
	test_ui_is_stored_and_returned_alongside_the_config (client)
	test_a_design_stored_before_ui_existed_still_loads (client, tmp_path)
	test_ui_round_trips_through_a_release (client)
	test_ui_round_trips_through_a_microversion (client)

Variables
	reason
	app = FastAPI()
dict	A = {"X-Auth-Email": "alice@berkeley.edu"}
dict	B = {"X-Auth-Email": "bob@berkeley.edu"}
dict	OWNER_A = {"owner": A["X-Auth-Email"]}
str	BASE = "/api/engine/documents"
dict	_DOC_SCOPED
dict	_UNSCOPED

Detailed Description

Per-user engine designs: working copy + microversions + releases.

The versioned-document API (/api/engine/documents) mirrors the pid-designer
model: an autosaved working copy, throttled microversions, and immutable named
releases. Identity is X-Auth-Email with a `local` dev fallback.

Designs are shared: one lives in its creator's folder but is editable by anyone
on its `sharedWith` list, and readable/copyable by anyone at all. So the
invariant under test is no longer "users cannot see each other" -- it is that
`?owner=` grants exactly the access the share list says it does. The 403/404
matrix below walks the router's own route table, so an endpoint added without
going through `_resolve_doc` fails here rather than shipping a hole.

Function Documentation

◆ _call()

test_documents._call	(	client,
		name,
		doc_id,
		headers,
		params )

protected

Definition at line 364 of file test_documents.py.

Referenced by test_doc_scoped_route_404s_a_foreign_id_without_owner(), and test_doc_scoped_route_forbids_an_unshared_owner().

◆ _create()

test_documents._create	(	client,
		headers,
		name = "Baseline",
		config = None )

protected

Definition at line 61 of file test_documents.py.

Referenced by test_a_design_stored_before_ui_existed_still_loads(), test_any_editor_may_reshare(), test_autosave_load_and_history(), test_browse_groups_by_owner_and_hides_what_you_can_edit(), test_copy_is_independent_and_needs_no_share(), test_create_lists_and_isolates_until_shared(), test_delete_is_gone(), test_doc_scoped_route_404s_a_foreign_id_without_owner(), test_doc_scoped_route_forbids_an_unshared_owner(), test_history_needs_a_share(), test_history_readable_once_shared(), test_leave_removes_only_yourself(), test_microversion_history_is_in_write_order(), test_owner_cannot_leave_their_own_config(), test_owner_param_cannot_escape_the_root(), test_release_is_immutable_and_listed(), test_rename(), test_restore_returns_older_state(), test_share_grants_edit_and_writes_into_the_owners_folder(), test_share_replaces_the_whole_list_and_drops_the_owner(), test_ui_is_stored_and_returned_alongside_the_config(), test_ui_round_trips_through_a_microversion(), and test_ui_round_trips_through_a_release().

◆ _find()

test_documents._find	(	client,
		headers,
		doc_id )

protected

Definition at line 84 of file test_documents.py.

Referenced by test_copy_is_independent_and_needs_no_share(), and test_leave_removes_only_yourself().

◆ _isolate()

test_documents._isolate	(		tmp_path,
			monkeypatch )

protected

Fresh data root per test; force a microversion on every autosave (no
throttle) and clear the in-process throttle clock so tests don't interfere.

Definition at line 42 of file test_documents.py.

◆ _share()

test_documents._share	(		client,
			doc_id,
			emails,
		*	,
			headers = A,
			params = None )

protected

Definition at line 68 of file test_documents.py.

Referenced by test_any_editor_may_reshare(), test_browse_groups_by_owner_and_hides_what_you_can_edit(), test_create_lists_and_isolates_until_shared(), test_history_readable_once_shared(), test_leave_removes_only_yourself(), test_share_grants_edit_and_writes_into_the_owners_folder(), and test_share_replaces_the_whole_list_and_drops_the_owner().

◆ _take()

test_documents._take	(	client,
		doc_id,
		headers = A,
		params = None )

protected

Content writes need the checkout now. Explicit in every test that saves,
rather than hidden in a fixture -- taking it is part of the API contract.

Definition at line 75 of file test_documents.py.

Referenced by test_a_design_stored_before_ui_existed_still_loads(), test_autosave_load_and_history(), test_copy_is_independent_and_needs_no_share(), test_history_readable_once_shared(), test_microversion_history_is_in_write_order(), test_release_is_immutable_and_listed(), test_restore_returns_older_state(), test_share_grants_edit_and_writes_into_the_owners_folder(), test_ui_is_stored_and_returned_alongside_the_config(), test_ui_round_trips_through_a_microversion(), and test_ui_round_trips_through_a_release().

◆ client()

test_documents.client ( )

Definition at line 51 of file test_documents.py.

◆ test_a_design_stored_before_ui_existed_still_loads()

test_documents.test_a_design_stored_before_ui_existed_still_loads	(		client,
			tmp_path )

Every design saved before this change is a bare `{"config": ...}`, and
they must keep opening -- the client defaults the missing half to {}.

Definition at line 460 of file test_documents.py.

References _create(), and _take().

◆ test_any_editor_may_reshare()

test_documents.test_any_editor_may_reshare ( client )

No owner/editor distinction: a shared editor can change the share list,
including removing people. Revocation is housekeeping, not a boundary.

Definition at line 253 of file test_documents.py.

References _create(), and _share().

◆ test_autosave_load_and_history()

test_documents.test_autosave_load_and_history ( client )

Definition at line 135 of file test_documents.py.

References _create(), and _take().

◆ test_browse_groups_by_owner_and_hides_what_you_can_edit()

test_documents.test_browse_groups_by_owner_and_hides_what_you_can_edit ( client )

Definition at line 297 of file test_documents.py.

References _create(), and _share().

◆ test_copy_is_independent_and_needs_no_share()

test_documents.test_copy_is_independent_and_needs_no_share ( client )

Definition at line 310 of file test_documents.py.

References _create(), _find(), and _take().

◆ test_copy_of_a_missing_config_is_404()

test_documents.test_copy_of_a_missing_config_is_404 ( client )

Definition at line 328 of file test_documents.py.

◆ test_create_lists_and_isolates_until_shared()

test_documents.test_create_lists_and_isolates_until_shared ( client )

Definition at line 91 of file test_documents.py.

References _create(), and _share().

◆ test_delete_is_gone()

test_documents.test_delete_is_gone ( client )

Configs are never deleted -- shared configs made it too easy to destroy
someone else's work. Cleanup is an admin operation on the volume.

`/{id}/share/me` is the one DELETE that survives, and it drops a share
grant, not a config.

Definition at line 114 of file test_documents.py.

References _create().

◆ test_doc_scoped_route_404s_a_foreign_id_without_owner()

test_documents.test_doc_scoped_route_404s_a_foreign_id_without_owner	(	client,
		tmp_path,
		name )

Dropping `?owner=` must 404, never silently create an orphan working copy
in the caller's own folder -- a failure `/flush` (a sendBeacon) could not
even report.

Definition at line 385 of file test_documents.py.

References _call(), and _create().

◆ test_doc_scoped_route_forbids_an_unshared_owner()

test_documents.test_doc_scoped_route_forbids_an_unshared_owner	(		client,
			name )

Definition at line 379 of file test_documents.py.

References _call(), and _create().

◆ test_every_doc_scoped_route_is_listed()

test_documents.test_every_doc_scoped_route_is_listed ( )

Pins the matrix to the real route table. Add an endpoint and this fails
until you say which side of the access boundary it sits on.

Definition at line 370 of file test_documents.py.

◆ test_history_needs_a_share()

test_documents.test_history_needs_a_share ( client )

Bob naming Alice's config gets 404 without ?owner= (no such config of his
own) and 403 with it (hers, not shared) -- never her data.

Definition at line 153 of file test_documents.py.

References _create().

◆ test_history_readable_once_shared()

test_documents.test_history_readable_once_shared ( client )

Definition at line 164 of file test_documents.py.

References _create(), _share(), and _take().

◆ test_leave_removes_only_yourself()

test_documents.test_leave_removes_only_yourself ( client )

Definition at line 263 of file test_documents.py.

References _create(), _find(), and _share().

◆ test_legacy_records_without_sharedwith_still_work()

test_documents.test_legacy_records_without_sharedwith_still_work	(		client,
			tmp_path )

Every config created before sharing existed lacks the key. A missing
`sharedWith` is an empty list, never an error.

Definition at line 277 of file test_documents.py.

◆ test_microversion_history_is_in_write_order()

test_documents.test_microversion_history_is_in_write_order	(		client,
			tmp_path )

History order has to survive coarse filesystem timestamps.

Microversions are the only recovery path now that delete is gone, so
"restore the previous version" handing back the wrong snapshot is data loss.
Two snapshots written back-to-back can share an mtime tick, and ordering
must not degrade to arbitrary when they do.

Rather than race the filesystem and hope, this forces the condition: every
version file is stamped with the *same* mtime, so the order can only come
from the ids themselves. With random ids this fails every run; it is the
nanosecond prefix in `snapshot_micro` that makes it pass.

Definition at line 405 of file test_documents.py.

References _create(), and _take().

◆ test_owner_cannot_leave_their_own_config()

test_documents.test_owner_cannot_leave_their_own_config ( client )

Otherwise the config ends up in nobody's editable list.

Definition at line 271 of file test_documents.py.

References _create().

◆ test_owner_param_cannot_escape_the_root()

test_documents.test_owner_param_cannot_escape_the_root	(	client,
		tmp_path,
		owner )

Definition at line 396 of file test_documents.py.

References _create().

◆ test_release_is_immutable_and_listed()

test_documents.test_release_is_immutable_and_listed ( client )

Definition at line 178 of file test_documents.py.

References _create(), and _take().

◆ test_rename()

test_documents.test_rename ( client )

Definition at line 107 of file test_documents.py.

References _create().

◆ test_restore_returns_older_state()

test_documents.test_restore_returns_older_state ( client )

The safety net: an autosaved mistake is recoverable from an earlier
microversion.

Definition at line 197 of file test_documents.py.

References _create(), and _take().

◆ test_share_grants_edit_and_writes_into_the_owners_folder()

test_documents.test_share_grants_edit_and_writes_into_the_owners_folder	(		client,
			tmp_path )

A shared editor edits the *same* config, not a copy -- so the bytes must
land in Alice's folder and Alice must see the change.

Definition at line 219 of file test_documents.py.

References _create(), _share(), and _take().

◆ test_share_replaces_the_whole_list_and_drops_the_owner()

test_documents.test_share_replaces_the_whole_list_and_drops_the_owner ( client )

Definition at line 240 of file test_documents.py.

References _create(), and _share().

◆ test_ui_is_stored_and_returned_alongside_the_config()

test_documents.test_ui_is_stored_and_returned_alongside_the_config ( client )

Definition at line 447 of file test_documents.py.

References _create(), and _take().

◆ test_ui_round_trips_through_a_microversion()

test_documents.test_ui_round_trips_through_a_microversion ( client )

Definition at line 486 of file test_documents.py.

References _create(), and _take().

◆ test_ui_round_trips_through_a_release()

test_documents.test_ui_round_trips_through_a_release ( client )

Definition at line 473 of file test_documents.py.

References _create(), and _take().

Variable Documentation

◆ _DOC_SCOPED

dict test_documents._DOC_SCOPED

protected

Initial value:

=  {
    "rename_document": ("PATCH", "", {"name": "x"}),
    "share_document": ("PUT", "/share", {"sharedWith": []}),
    "leave_document": ("DELETE", "/share/me", None),
    "take_checkout": ("POST", "/checkout", None),
    "release_checkout": ("DELETE", "/checkout", None),
    "release_checkout_beacon": ("POST", "/checkout/release", None),
    "beat_checkout": ("POST", "/checkout/beat", None),
    "get_checkout": ("GET", "/checkout", None),
    "load_document": ("GET", "/load", None),
    "autosave_document": ("POST", "/autosave", {"config": {"x": 1}}),
    "flush_document": ("POST", "/flush", {"config": {"x": 1}}),
    "get_history": ("GET", "/history", None),
    "get_version": ("GET", "/version/deadbeef", None),
    "create_release": ("POST", "/release", {"label": "0.1"}),
    "list_releases": ("GET", "/releases", None),
    "get_release": ("GET", "/release/0.1", None),
}

Definition at line 338 of file test_documents.py.

◆ _UNSCOPED

dict test_documents._UNSCOPED

protected

Initial value:

1= {"list_documents", "browse_documents", "create_document", "copy_document",

2 "rescue_document"}

Definition at line 360 of file test_documents.py.

◆ A

dict test_documents.A = {"X-Auth-Email": "alice@berkeley.edu"}

Definition at line 37 of file test_documents.py.

◆ app

test_documents.app = FastAPI()

Definition at line 34 of file test_documents.py.

◆ B

dict test_documents.B = {"X-Auth-Email": "bob@berkeley.edu"}

Definition at line 38 of file test_documents.py.

◆ BASE

str test_documents.BASE = "/api/engine/documents"

Definition at line 58 of file test_documents.py.

◆ OWNER_A

dict test_documents.OWNER_A = {"owner": A["X-Auth-Email"]}

Definition at line 56 of file test_documents.py.

◆ reason

test_documents.reason

Definition at line 23 of file test_documents.py.

Functions

Variables

Detailed Description

Function Documentation

◆ _call()

◆ _create()

◆ _find()

◆ _isolate()

◆ _share()

◆ _take()

◆ client()

◆ test_a_design_stored_before_ui_existed_still_loads()

◆ test_any_editor_may_reshare()

◆ test_autosave_load_and_history()

◆ test_browse_groups_by_owner_and_hides_what_you_can_edit()

◆ test_copy_is_independent_and_needs_no_share()

◆ test_copy_of_a_missing_config_is_404()

◆ test_create_lists_and_isolates_until_shared()

◆ test_delete_is_gone()

◆ test_doc_scoped_route_404s_a_foreign_id_without_owner()

◆ test_doc_scoped_route_forbids_an_unshared_owner()

◆ test_every_doc_scoped_route_is_listed()

◆ test_history_needs_a_share()

◆ test_history_readable_once_shared()

◆ test_leave_removes_only_yourself()

◆ test_legacy_records_without_sharedwith_still_work()

◆ test_microversion_history_is_in_write_order()

◆ test_owner_cannot_leave_their_own_config()

◆ test_owner_param_cannot_escape_the_root()

◆ test_release_is_immutable_and_listed()

◆ test_rename()

◆ test_restore_returns_older_state()

◆ test_share_grants_edit_and_writes_into_the_owners_folder()

◆ test_share_replaces_the_whole_list_and_drops_the_owner()

◆ test_ui_is_stored_and_returned_alongside_the_config()

◆ test_ui_round_trips_through_a_microversion()

◆ test_ui_round_trips_through_a_release()

Variable Documentation

◆ _DOC_SCOPED

◆ _UNSCOPED

◆ A

◆ app

◆ B

◆ BASE

◆ OWNER_A

◆ reason