> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Test mode

> Run the Elements checkout with your real products and events, without an invoice or a payment.

Test mode runs the whole checkout in your page with your real products, prices, payment methods and design. The pay button says **Pay … · Test**. A click creates no invoice and charges nothing. Your page gets the same events as in live mode, so you can build and check your event handlers.

```html theme={"system"}
<div
  data-shoppex-element="checkout"
  data-shoppex-shop-id="YOUR_SHOP"
  data-shoppex-product-id="YOUR_PRODUCT_ID"
  data-shoppex-mode="test"
></div>
```

With `Shoppex.mount`, pass `mode: 'test'`.

## Where it runs

* On every site in your [allowed sites](/developers/elements/sites).
* On `http://localhost` and `http://127.0.0.1`, on any port, without a list entry.
* In the live preview on the dashboard's Elements tab.

Test mode needs a product: use `data-shoppex-product-id` or `items`. Product groups and invoices are live only.

## What happens on Pay

The block sends the events of a live purchase, in the same order:

1. `step` to `payment`, if the buyer was still on the details step
2. `invoice-created` with `{ invoiceId: 'test_…', test: true }`
3. `step` to `processing`
4. `success` with `{ invoiceId: 'test_…', test: true }`
5. `step` to `success`

The ID starts with `test_`. No invoice with that ID exists, so the Developer API and webhooks do not know it. Use the `test` flag to keep test purchases out of your own records.

## Simulate an error

The **Events** card on the Elements tab shows every message between the preview and the page. Pick an error code and click **Simulate Error**. The preview reloads, and the next **Pay … · Test** click sends that error instead of `success`:

* A payment error, like `payment_declined`, comes after `invoice-created`, and the block returns to the payment step, as a declined payment does live.
* A checkout error, like `out_of_stock`, comes before an invoice would exist.

You can simulate `payment_declined`, `payment_failed`, `authentication_failed`, `gateway_handoff_failed`, `amount_below_minimum`, `cart_rejected`, `out_of_stock`, `coupon_invalid`, `email_rejected`, `checkout_blocked` and `checkout_failed`. See [Error codes](/developers/elements/events#error-codes).

## Go live

Change the mode to `live`, or remove it, and publish on a site from your list. A live block takes real payments. Live mode on `localhost` needs `http://localhost:<port>` in the list.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.