Skip to content

test: cover the cart capability (cart.md) - #108

Open
vishkaty wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
vishkaty:test/cart-capability-conformance
Open

vishkaty wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
vishkaty:test/cart-capability-conformance

Conversation

@vishkaty

Copy link
Copy Markdown
Contributor

What

Adds cart_test.py, covering the cart capability. The suite has no cart
coverage today: the string dev.ucp.shopping.cart appears nowhere in the
repository, and the only occurrence of the word is one English usage in a
fulfillment_structure_test.py docstring. The reference server implements and
advertises the capability, so it is testable now.

Four assertions, each traced to a MUST, each verified on the wire:

assertion source
cart contents win over overlapping fields in the checkout payload cart.md:66
a second conversion of the same cart returns the existing incomplete checkout cart.md:72-74
cancel returns the cart state as it was before deletion cart.md:185
discount codes applied to a cart carry forward to the checkout discount.md:143

Line references are to release/2026-04-08, the version this suite targets.

Kept server agnostic

Issues #101 to #103 point out that assertions elsewhere encode the reference
merchant rather than the specification, so this module avoids that by
construction:

  • line items are compared as a bag of item id and quantity, never by
    server assigned identifiers
  • the conversion identity check compares checkout ids, not totals arithmetic
  • both 200 and 201 are accepted where the specification pins no status
  • the item and discount code come from fixture_ctx, so nothing is hardcoded
  • the discount assertion accepts any of the three wire signals a conformant
    business may use: the echoed code, an applied entry, or a negative
    discount total, because discount.md:145 lets a business drop a code that
    is no longer valid at checkout time

The module gates on the capability being advertised and skips honestly
otherwise, since cart is deliberately not in conformance_input.json
required_capabilities. The discount assertion additionally skips unless the
discount capability declares it extends cart, which discount.md:59 permits it
not to.

Deliberately not asserted

Two nearby rules look assertable and are not, which is worth stating so the
omission does not read as an oversight:

  • cart.md:176 ("full replacement") binds the platform, not the business.
    The business side sentence carries no RFC 2119 keyword, so this suite cannot
    hold a merchant to it.
  • cart.md:186 (subsequent operations return not_found) is a SHOULD, so
    the status after cancel is not asserted.

Testing

Against the reference server at the pinned ucp-sdk==0.4.6, run exactly as the
workflow runs it: 4 passed.

Each assertion was then shown to fail on its own, by mutating the reference
server and re-running. Each mutation failed exactly one assertion and nothing
else:

mutation fails
take line items from the request payload cart contents
disable the existing checkout lookup conversion identity
empty the cart before returning it from cancel cancel state
drop cart discounts on conversion discount carry forward

Removing cart from the advertised profile makes all four skip rather than fail.
ruff check and ruff format --check are clean.

Whole suite run for a control: unchanged. order_test.py fails two tests both
before and after this change, on a pristine tree with a fresh database and this
file absent, so those are pre-existing and unrelated.

Note on #107

This lands as a top level cart_test.py, which is what the current workflow
picks up (for test_file in *_test.py). #107 relocates every module into
shopping/<capability>/. Its diff has no cart content, so there is no overlap,
but if it merges first this file should move to shopping/cart/cart_test.py.
Happy to rebase it that way, or to hold this until #107 lands, whichever suits.

@damaz91 damaz91 added the status:needs-triage Signal that the PR is ready for human triage label Sep 11, 2026

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

LGTM — nice, well-isolated coverage of the normative dev.ucp.shopping.cart requirements, @vishkaty!

All four tests map directly to the Cart and Discount specifications:

  1. test_conversion_uses_cart_contents_over_payload: Cart line_items (quantity=2) taking precedence over conflicting checkout payload items (quantity=9) during cart_id conversion (_item_bag).
  2. test_second_conversion_returns_the_existing_checkout: Idempotent cart-to-checkout conversion returning the existing incomplete checkout session ID.
  3. test_cancel_returns_the_cart_state_before_deletion: POST /carts/{id}/cancel returning 200/201 with the pre-deletion cart id and _item_bag (while appropriately leaving the SHOULD post-cancel not_found check out of mandatory assertions).
  4. test_cart_discount_codes_carry_forward_to_checkout: Discount code from self.fixture_ctx.get_test_discount_code() carrying forward to the converted checkout (_discount_is_visible) when _discount_extends_cart() is true.

@damaz91 damaz91 added status:under-review and removed status:needs-triage Signal that the PR is ready for human triage labels Oct 30, 2026
@vishkaty
vishkaty force-pushed the test/cart-capability-conformance branch 2 times, most recently from 4bc872a to 8a1edf8 Compare November 10, 2026 17:33
@vishkaty

Copy link
Copy Markdown
Contributor Author

Rebased onto main at 79a0f40f and added cart_test to SUITE_REGISTRY.

#120 replaced the workflow loop over *_test.py with ucp-conformance --suite=all, which runs
only the modules the registry names. Before the entry, --suite=all on this branch resolved 78
cases and selected none of this module; with it, 82, of which four are its own. Removing the line
again returns both.

Run the way the workflow runs it, against the sample server booted from samples main 52319dff
with the flower shop data seeded: --suite=cart_test gives 4 passed, and --suite=all gives 82
passed with one skip elsewhere.

The Note on #107 above is superseded. #107 is closed and was replaced by #120, which has merged,
and #121 and #122, which are open. Once #121 lands this file moves under shopping/ and the
registry entry becomes a dotted path; #121 reports every test as a 100 percent rename, so that
move is mechanical.

@vishkaty

Copy link
Copy Markdown
Contributor Author

Rebased onto main at 1201fb78 now that #121 has landed, and relocated as the earlier note
said it would be.

The test content is unchanged. The file is now shopping/cart/cart_test.py in a new
shopping/cart/ package with the same __init__.py shape as the other domains, and
SUITE_REGISTRY gains shopping.cart.cart_test.

Measured on this head against the sample server from samples main: 4 passed. Without the
registry entry --suite=all resolves 78 and selects none of the four; with it, 82.

Four cases over cart conversion: conversion uses cart contents over the
payload, a second conversion returns the existing checkout, cancel returns the
cart state before deletion, and cart discount codes carry forward.

Placed as `shopping/cart/cart_test.py` in a new `shopping/cart/` package,
following the layout Universal-Commerce-Protocol#121 landed, and registered as `shopping.cart.cart_test`.

What makes the module execute: without the registry entry `--suite=all`
resolves 83 cases and selects none of these four, and with it 87.

Rebased onto main past Universal-Commerce-Protocol#122. The only conflict was the registry list, where
Universal-Commerce-Protocol#112 and Universal-Commerce-Protocol#122 had each added an entry. The cart entry sits at the head of the
shopping list, which keeps that list grouped by subpackage in alphabetical
order.

Obligations are cited by section name, in the module docstring and at each
case, rather than by line number. The line numbers the module carried were
correct when it was written and had since drifted, one of them onto an
unrelated paragraph, which is the hazard of citing a moving document by line.

Two cases were judging a conformant business wrongly, and both are corrected
here. The discount case used the presence of the code in the response as its
evidence that the code had applied, but a business may return a code it
received without applying it, as the reference does for an unknown code. With
a configured code that does not apply at the business under test, the case
therefore ran with nothing applied, and it failed a business that carried its
applied codes forward and dropped the unapplied one with a
`discount_code_invalid` warning, which discount.md allows. Application now
needs an applied entry naming the code or a discount in totals, so such a
code skips the case instead. Carry-forward is still satisfied by naming the
code, and a discount standing in for it must now be at least as large as the
one on the cart, so an unrelated discount no longer counts.

The contents comparison took line items as a bag of id and quantity pairs,
which failed a business expressing two units as two single-unit lines. It now
sums quantity per item id and leaves out lines naming a parent, which still
catches a business that takes its quantities from the request payload.

Verified against the flower shop reference: the module alone gives 4 passed
and 0 skipped; --suite=all gives 87 executed, 85 passed, 2 skipped, 0
failures; the pinned pre-commit, ruff, ruff format and cspell are clean. Nine
servers each breaking one obligation redden their own case and nothing else,
and the two corrections above are each held by a server that fails the old
code and passes the new one.
@vishkaty
vishkaty force-pushed the test/cart-capability-conformance branch from 22af7dc to 35e5556 Compare November 17, 2026 20:09
@vishkaty

Copy link
Copy Markdown
Contributor Author

Rebased onto main past #122. The only conflict was the registry list in
runner.py, where #112 and #122 had each added an entry. The cart entry sits
at the head of the shopping list, which keeps that list grouped by subpackage
in alphabetical order.

Two other things came out of re-running the cases, both corrected here.

The obligations were cited by line number. Those numbers were right when the
module was written and had since drifted, one of them onto an unrelated
paragraph about unavailable items, so they now name sections instead, in the
docstring and at each case.

The discount case used the presence of the code in the response as its
evidence that the code had applied. A business may return a code it received
without applying it, as the reference does for an unknown code: the cart
comes back carrying the code with no applied entry and no discount total.
With a configured code that does not apply at the business under test, the
case therefore ran with nothing applied, and it failed a business that
carried its applied codes forward and dropped the unapplied one with a
discount_code_invalid warning, which discount.md allows. Application now
needs an applied entry naming the code or a discount in totals, so such a
code skips the case. Carry-forward is still satisfied by naming the code, and
a discount standing in for it must be at least as large as the one on the
cart, so an unrelated discount no longer counts.

The contents comparison took line items as a bag of id and quantity pairs,
which failed a business expressing two units as two single-unit lines. It now
sums quantity per item id and leaves out lines naming a parent, which still
catches a business that takes its quantities from the request payload.

Verification on the rebased branch, against the flower shop reference:

  • shopping.cart.cart_test alone: 4 cases resolved, 4 passed, 0 skipped
  • uv run ucp-conformance --suite=all: 87 executed, 85 passed, 2 skipped,
    0 failures, exit 0
  • registry reachability: main resolves 83 cases, this branch 87, and removing
    the one registry line returns it to 83
  • pinned pre-commit run --all-files, ruff check, ruff format --check: clean
  • cspell with .cspell.json over the three changed files: 0 issues
  • nine servers each breaking one obligation redden their own case and nothing
    else, and the two corrections above are each held by a server that fails
    the old code and passes the new one

@kkrlstrm

Copy link
Copy Markdown

Hi, thanks for putting this together. I tested two related cart-to-checkout cases against the Python sample at 52319dff that might be useful alongside the sequential conversion test:

  1. Converting a cart with key A creates a checkout. A second conversion with key B returns that checkout, but B isnt stored. Reusing B with a different cart then creates a different checkout. In another run, canceling the original checkout and retrying B’s original request created a new checkout.
  2. When two conversions with different keys both finish the existing-checkout lookup before either creates a checkout, both return 201 and two active checkouts persist. I forced that overlap with a test-only barrier; sequential conversions returned the same checkout.

Would checks for these cases fit the conformance suite? The sample continued after my synthetic agent profile failed to resolve, so the results need confirmation with a reachable profile.

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants