Repository navigation
Conversation
Add platform_reference_test.py for the checkout platform_reference contract agreed on ucp#413 and specified in ucp#839: set on Create, echoed verbatim, immutable on Update and Complete, carried onto the order, Get Order, and every order event webhook. The module skips unless the checkout capability is advertised at or after the release that ships ucp#839; UCP_CONFORMANCE_PREVIEW= platform_reference runs it earlier against a server that implements it.
|
Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). View this failed invocation of the CLA check for more information. For the most up to date status, view the checks section at the bottom of the pull request. |
cc9aa35 to
b11f3ca
Compare
Track the review changes in ucp#839 (abfcfdf0): - Create rejects a value over 512 characters as an invalid request - Update and Complete must not be rejected for a resent value, so the immutability tests now require 200 - idempotent cart conversion keeps the stored value - absence on the order is normative (never synthesized)
damaz91
left a comment
There was a problem hiding this comment.
Thank you for putting together this thorough conformance suite for platform_reference (@gforgab and @williammacarini)!
The 16 test cases in platform_reference_test.py map cleanly to the contract in Universal-Commerce-Protocol/ucp#839 and Universal-Commerce-Protocol/ucp#413—covering verbatim echo across checkout operations, immutability on full-replacement PUT and POST /complete (ignoring resent values without rejecting the request), maxLength: 512 round-tripping and 513-character rejection, idempotent cart conversion retention, Get Order and webhook event propagation, and non-synthesis when omitted. ruff check and ruff format --check also pass cleanly.
Since this is currently a Draft PR waiting on upstream prerequisites, leaving a few notes for when it is ready to mark for review:
- CLA Check: Please sign the Google CLA so the
google-clacheck can pass. - Upstream Spec & Samples: As noted in the description, this should stay in draft until
Universal-Commerce-Protocol/ucp#839lands in a release (updating_MIN_VERSIONif needed) andUniversal-Commerce-Protocol/samplescarriesplatform_referenceontoOrderand validatesmaxLength. - Suite Layout (#107): Once #107 lands, this module can move under
shopping/checkout/and use the shared@requires_capabilitydecorator fromframework/decorators.py.
Left two small optional suggestions inline on test_update_cannot_add_reference and test_order_update_events_carry_reference.
| """A reference first sent on Update is ignored (it is Create-only).""" | ||
| checkout = self._create() | ||
| response = self._update(checkout, {_FIELD: _REF}) | ||
| self.assert_response_status(response, 200) |
There was a problem hiding this comment.
Optional: Consider also asserting self.assertNotIn(_FIELD, response.json(), ...) on the immediate Update Checkout response here (matching test_update_without_field_retains_reference, test_update_cannot_change_reference, and test_update_resending_same_reference_keeps_it above, which check both response.json() and self._get_checkout(checkout["id"])). That way a server that echoes the request field on the PUT response without persisting it is also caught.
| def test_order_update_events_carry_reference(self) -> None: | ||
| """Every order event, including updates, carries the reference.""" | ||
| self._require_order() | ||
| _, order_id = self._place_order({_FIELD: _REF}) |
There was a problem hiding this comment.
Optional: Consider waiting for the initial order-created delivery (self._wait_for_events(order_id, 1)) before calling /testing/simulate-shipping/{order_id} (similar to WebhookTest.test_webhook_event_stream in webhook_test.py). Against a server that dispatches webhooks asynchronously, observing the first delivery before triggering the shipping update avoids any race between order creation and shipment simulation.
- test_update_cannot_add_reference also asserts the immediate Update Checkout response does not echo a reference sent only on Update. - test_order_update_events_carry_reference waits for the order-created delivery before simulating shipment, avoiding a race with servers that dispatch webhooks asynchronously.
|
Thanks for the review, @damaz91! Both suggestions are in 8a6d26f:
On the CLA: Agreed on the rest: this stays in draft until ucp#839 ships and samples carries the field onto the Order, and I'll move it under |
|
Thanks @gforgab for drafting this from the Universal-Commerce-Protocol/ucp#413 test plan, and @damaz91 for the review. I'm back and taking it over from here. Status is unchanged: it stays in draft until Universal-Commerce-Protocol/ucp#839 lands in a release and samples carries |
Adds
platform_reference_test.py, the companion conformance module for the checkoutplatform_referencecontract agreed on Universal-Commerce-Protocol/ucp#413 and specified in Universal-Commerce-Protocol/ucp#839. It is based on @williammacarini's Universal-Commerce-Protocol/ucp#413 test plan; I'm covering while he's away and will hand it back when he returns.Opened as a draft: it should be marked ready only after Universal-Commerce-Protocol/ucp#839 merges and ships in a release, and after samples carries the field onto the Order (@vishkaty, per Universal-Commerce-Protocol/ucp#413).
What it covers (single Business, as agreed on Universal-Commerce-Protocol/ucp#413)
test_create_echoes_reference,test_get_checkout_returns_referencetest_update_without_field_retains_referencetest_update_cannot_change_reference,test_update_resending_same_reference_keeps_it,test_update_cannot_add_referencetest_complete_keeps_reference_and_ignores_new_valuetest_cancel_echoes_referencetest_order_carries_referencetest_order_created_event_carries_reference,test_order_update_events_carry_referencetest_max_length_reference_round_tripsmaxLength512 kept intact through to the ordertest_distinct_references_stay_separatetest_absent_reference_is_not_synthesizedtest_over_length_reference_is_rejectedtest_cart_conversion_keeps_stored_referenceAll requests are raw JSON, because the pinned SDK models don't declare the field. No changes to shared helpers.
Gating
The field is new in the release that ships Universal-Commerce-Protocol/ucp#839. The module therefore skips unless discovery advertises
dev.ucp.shopping.checkoutat or after_MIN_VERSION(currently2026-12-08, to be updated when the release ships). SettingUCP_CONFORMANCE_PREVIEW=platform_referenceruns it earlier against a server that implements the field.Happy to switch to whatever mechanism maintainers prefer, for example the
requires_capability(name, min_version)helper proposed in #107.Local evidence
I ran this locally against samples
e7c9c12with SDKv2026-04-08-6, the same setup as the CI workflow.platform_referencenot found", because the server builds the Order without the field) and the over-length test (no length check)Each test was also checked against a deliberately broken server, to confirm it can fail:
update_cannot_change,update_cannot_addupdate_without_field,update_cannot_change,update_resending_samecomplete_keeps_reference_and_ignores_new_valuecancel_echoes_referenceabsent_reference_is_not_synthesizedmax_length_reference_round_tripsdistinct_references_stay_separate, plus the Order and event testsover_length_reference_is_rejectedcart_conversion_keeps_stored_referenceupdate_cannot_change,update_resending_same,update_cannot_addruff check,ruff format,pre-commitandcspellpass on the new file.Updates
Not covered
minLength, while the prose tells the platform to omit the field).Part of Universal-Commerce-Protocol/ucp#413.