Skip to content

test: cover platform_reference lifecycle (ucp#413) - #118

Draft
gforgab wants to merge 3 commits into
Universal-Commerce-Protocol:mainfrom
gforgab:test/platform-reference
Draft

gforgab wants to merge 3 commits into
Universal-Commerce-Protocol:mainfrom
gforgab:test/platform-reference

Conversation

@gforgab

@gforgab gforgab commented Oct 26, 2026 •

Copy link
Copy Markdown

Adds platform_reference_test.py, the companion conformance module for the checkout platform_reference contract 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 Contract (Universal-Commerce-Protocol/ucp#839)
test_create_echoes_reference, test_get_checkout_returns_reference Echoed verbatim on every checkout response
test_update_without_field_retains_reference A full-replacement Update does not clear it
test_update_cannot_change_reference, test_update_resending_same_reference_keeps_it, test_update_cannot_add_reference A value received on Update is ignored and does not cause a rejection (200); the Create value is retained
test_complete_keeps_reference_and_ignores_new_value Same on Complete
test_cancel_echoes_reference Every checkout response, including Cancel
test_order_carries_reference Carried onto the order (Get Order)
test_order_created_event_carries_reference, test_order_update_events_carry_reference Included in every order event webhook
test_max_length_reference_round_trips maxLength 512 kept intact through to the order
test_distinct_references_stay_separate Verbatim per checkout and order; values are not conflated
test_absent_reference_is_not_synthesized Absent on checkout and order when Create did not carry one (never synthesized)
test_over_length_reference_is_rejected A Create with a value over 512 characters is rejected as an invalid request
test_cart_conversion_keeps_stored_reference When Create returns an existing checkout (idempotent cart conversion), the stored value is kept

All 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.checkout at or after _MIN_VERSION (currently 2026-12-08, to be updated when the release ships). Setting UCP_CONFORMANCE_PREVIEW=platform_reference runs 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 e7c9c12 with SDK v2026-04-08-6, the same setup as the CI workflow.

Server Result
samples as-is 10 passed, 6 failed: the 5 Order and webhook tests ("platform_reference not found", because the server builds the Order without the field) and the over-length test (no length check)
samples + a ~12-line local patch (Order carry + length check; not part of this PR) 16 / 16 passed

Each test was also checked against a deliberately broken server, to confirm it can fail:

Mutation Caught by
Create lowercases the value 11 tests, including echo, Get, Update, Complete, Cancel, Order and events
Update applies a resent value update_cannot_change, update_cannot_add
Update drops the stored value update_without_field, update_cannot_change, update_resending_same
Complete applies a new value complete_keeps_reference_and_ignores_new_value
Cancel drops the value cancel_echoes_reference
Order invents a value when none was sent absent_reference_is_not_synthesized
Order truncates to 100 characters max_length_reference_round_trips
Order uses one constant value distinct_references_stay_separate, plus the Order and event tests
No length check on Create over_length_reference_is_rejected
Cart reconversion replaces the stored value cart_conversion_keeps_stored_reference
Update rejects a resent value update_cannot_change, update_resending_same, update_cannot_add

ruff check, ruff format, pre-commit and cspell pass on the new file.

Updates

Not covered

  • Platform-side rules (no PII; opaque values scoped to one purchase flow), the SHOULD rules on permalinks and on Get Order for other platforms, and the empty string (rejected by the schema's minLength, while the prose tells the platform to omit the field).
  • Multi-Business fan-out: this is the documented scenario in feat: add platform_reference for platform-side order correlation ucp#839. It needs a second server under test and is left for a follow-up.

Part of Universal-Commerce-Protocol/ucp#413.

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.
@google-cla

google-cla Bot commented Oct 26, 2026

Copy link
Copy Markdown

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.

@gforgab
gforgab force-pushed the test/platform-reference branch from cc9aa35 to b11f3ca Compare October 26, 2026 15:20
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 damaz91 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. CLA Check: Please sign the Google CLA so the google-cla check can pass.
  2. Upstream Spec & Samples: As noted in the description, this should stay in draft until Universal-Commerce-Protocol/ucp#839 lands in a release (updating _MIN_VERSION if needed) and Universal-Commerce-Protocol/samples carries platform_reference onto Order and validates maxLength.
  3. Suite Layout (#107): Once #107 lands, this module can move under shopping/checkout/ and use the shared @requires_capability decorator from framework/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)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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})

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
@gforgab

gforgab commented Oct 30, 2026

Copy link
Copy Markdown
Author

Thanks for the review, @damaz91! Both suggestions are in 8a6d26f:

  • test_update_cannot_add_reference now also checks the immediate Update Checkout response.
  • test_order_update_events_carry_reference waits for the order-created delivery before simulating shipment.

On the CLA: cla/google passes on the latest commit. The bot's message was from before I switched the commit author to my corporate email.

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 shopping/checkout/ with @requires_capability once #107 lands.

@williammacarini

Copy link
Copy Markdown

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 platform_reference onto the Order. In the meantime I'll run the module against our own Business implementation (Mercado Pago's reference server) so there's a second, independent implementation exercising the contract before Universal-Commerce-Protocol/ucp#839 goes to the TC, and I'll rebase under shopping/checkout/ with @requires_capability once #107 lands.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants