# Hyva_CheckoutPayPal Playwright tests

End-to-end tests for PayPal Express in Hyvä Checkout. They reuse the page objects shipped
by `hyva-themes/magento2-hyva-checkout`, resolved through composer at runtime.

## Running

```bash
cd tests/playwright
npm install
npx playwright install chromium
cp .env.example .env      # then point PLAYWRIGHT_BASE_URL at your store
npm test                  # or: npm test tests/default/
```

Use `npm test` rather than `npx playwright test` directly. `run-tests.js` sets `NODE_PATH`
before Node starts so the checkout package's page objects resolve a single copy of
`@playwright/test`; `playwright.config.js` re-applies it via `Module._initPaths()` for the
cases where the runner is invoked some other way.

## Store prerequisites

- PayPal Express enabled with **sandbox API credentials**, and `paypal/wpp/sandbox_flag = 1`.
- Hyvä Theme + Hyvä Checkout active, Tailwind compiled, cache flushed.
- Luma sample data — the shared `SimpleProductPage` page object hardcodes
  `/strive-shoulder-pack.html`.
- If the checkout package has its own `node_modules`, remove it. `checkout-utils.js` fails
  loudly with instructions when it finds one, because two copies of the test runner break
  the shared page objects.

## What these tests do and do not cover

They drive the **real** PayPal sandbox — nothing is stubbed. PayPal's NVP API is called
server-side (`Nvp::call()` → `curl_exec()`), so unlike a browser-side SDK there is no
request for Playwright to intercept. What is observable is the outcome, and that is what
these assert: the shopper reaching paypal.com carrying an Express Checkout token, which
only a successful `SetExpressCheckout` can have produced.

They stop at the PayPal hand-off. Completing a purchase needs a sandbox buyer login, and
PayPal's own pages are not ours to assert against.

**Error-branch behaviour is not covered here.** PayPal will not emit codes like 10486 on
demand, so the recovery logic in `PaypalExpressPlaceOrderService::handleException()` is
covered by the unit tests instead:

```bash
vendor/bin/phpunit -c vendor/hyva-themes/magento2-hyva-checkout-paypal/phpunit.xml.dist
```

## Two things that will bite you

**Addresses must be real.** The `addressUS` fixture in the checkout package is deliberately
fictional (Unseen University, Ankh Morpork, Michigan 48413 — chosen to match sample-data
table rates). PayPal validates the shipping address and rejects it with
`#10736 Shipping Address Invalid City State Postal Code`, which core turns into a silent
redirect to the cart, so the test fails long before it reaches PayPal. Use
`fixtures/paypal-address.js`, and keep region and postcode genuinely consistent.

**They are slower and less predictable than same-origin specs.** Each redirect test makes a
live API call; they normally run in ~15s each, but a loaded or sluggish environment can
push the shared `goToNextStep()` Magewire wait past the 60s test timeout. If one fails on
`waiting for response "**/hyva-checkout-main"`, re-run before investigating — that message
means the checkout step never came back, not that PayPal misbehaved.

## Layout coverage

`tests/default/` and `tests/onepage/` mirror the checkout types. The layout is selected per
test via `HyvaCheckout.open(page, '<type>')`, so both directories run in a single pass
without switching store config.
