UCP SDK Integration Tests

This directory contains integration tests that run against a running UCP Merchant Server instance. These tests are language-agnostic regarding the server implementation (Python, Node.js, etc.) and verify adherence to the UCP specification.

Prerequisites

The tests assume a UCP Merchant Server is running and accessible via HTTP. The server must be started with databases initialized using data from test_data/flower_shop directory. Instructions to start the servers follow.

NOTE: These instructions assume the commands are executed from the directory containing this README.

Updating dependencies

uv sync

uv sync --directory ../samples/rest/python/server/

uv sync --directory ../sdk/python/

Initializing the database

DATABASE_PATH=/tmp/ucp_test

rm -rf ${DATABASE_PATH}
mkdir ${DATABASE_PATH}

uv run --directory ../samples/rest/python/server import_csv.py \
    --products_db_path=${DATABASE_PATH}/products.db \
    --transactions_db_path=${DATABASE_PATH}/transactions.db \
    --data_dir=../../../../conformance/test_data/flower_shop

Starting the server:

SIMULATION_SECRET=super-secret-sim-key
MERCHANT_SERVER_PORT=8182

uv run --directory ../samples/rest/python/server server.py \
    --products_db_path=${DATABASE_PATH}/products.db \
    --transactions_db_path=${DATABASE_PATH}/transactions.db \
    --port=${MERCHANT_SERVER_PORT} \
    --simulation_secret=${SIMULATION_SECRET} &
MERCHANT_SERVER_PID=$!

Running the Tests

for test_file in *_test.py; do
uv run ${test_file} \
    --server_url=http://localhost:${MERCHANT_SERVER_PORT} \
    --simulation_secret=${SIMULATION_SECRET} \
    --conformance_input=test_data/flower_shop/conformance_input.json \
    --fixture_config=test_data/flower_shop/test_fixtures.json
done

# Or, if you prefer:
SERVER_URL=http://localhost:${MERCHANT_SERVER_PORT} SIMULATION_SECRET=${SIMULATION_SECRET} uv run pytest

Customizing Test Fixtures

You can customize the test fixtures (SKU, expected pricing, discount codes, shipping destinations) by editing test_fixtures.json or passing a custom configuration file using the --fixture_config flag.

Conformance input

conformance_input.json carries the merchant-specific values the tests assert against, so the suite is not hardwired to the Flower Shop sample:

• ucp_version — the spec release the merchant targets; protocol_test asserts the discovery profile and shopping service declare exactly this version. When omitted, only the universal structural rule (date-based YYYY-MM-DD version) is enforced.
• required_capabilities — capability names this merchant is expected to declare in discovery. Capability sets are negotiated per merchant, so list the ones your implementation ships; capability names are always validated against the reverse-DNS convention regardless.

Version negotiation uses the version the server advertises in discovery as the compatible header value (with an obviously-future literal for the incompatible case), so it stays correct across spec releases.

Cleaning Up

Terminate the server using:

kill ${MERCHANT_SERVER_PID}

Examining the database state

After running tests, one can examine the database state using the dump_transactions and dump_log tools:

uv run --directory ../samples/rest/python/server dump_transactions.py \
    --transactions_db_path=${DATABASE_PATH}/transactions.db

uv run --directory ../samples/rest/python/server dump_log.py \
    --transactions_db_path=${DATABASE_PATH}/transactions.db