mataba/shop/docs/RUNTIME-QA.md

# XShop — Runtime QA (M1.1)

Date: 2026-09-13
Tester: local XAMPP

## 1. Environment

| Component | Version | Notes |
|-----------|---------|-------|
| PHP | 8.2.12 (cli, XAMPP) | Required 8.2+, preferred 8.3+. **Limitation documented**: XAMPP currently provides 8.2.12; theme uses PHP 8.2-compatible syntax only, tested successfully on 8.2.12. Recommend CI on 8.3 before final release. |
| WordPress | 7.1 (latest stable at test time, downloaded from wordpress.org) | `wp-includes/version.php` → `$wp_version = '7.1'` |
| WooCommerce | 11.1.0 (latest-stable.zip) | Active, `plugin list` confirms |
| MariaDB | 10.4.32 (XAMPP `C:\xampp\mysql\bin\mysql.exe`) | `SELECT VERSION()` → 10.4.32-MariaDB |
| Apache | 2.4.58 (XAMPP) | Listening on :80, `AllowOverride All` for `C:/xampp/htdocs`, custom `.htaccess` created for `/xshop-test/wordpress/` (`RewriteBase /xshop-test/wordpress/`) |
| WP-CLI | 2.12.0 (phar) | `C:\Users\hemn\AppData\Local\Temp\opencode\wp-cli.phar` |
| Node | v22.23.2 / npm 10.9.8 | JS `node --check` passed |
| Composer | not installed | Not required for M1 |
| Docker | not available | Not used; XAMPP preferred as reproducible local runtime |
| OS | Windows 11 (build 28000, AMD64) | |
| Browsers (manual fetch) | PowerShell `Invoke-WebRequest` (HTTP 200 checks) + `Invoke-WebRequest` for rendered HTML inspection | No Playwright yet; console check via static asset fetch |

### PHP / DB Setup

- DB `xshop_test` utf8mb4_unicode_ci, user `root` (no password, local only), `wp-config.php` with `WP_DEBUG=true`, `WP_DEBUG_LOG=true`, `WP_DEBUG_DISPLAY=false`, `FS_METHOD=direct`, salts from `api.wordpress.org`.
- Fixed BOM issue after initial `Set-Content -Encoding UTF8` (stripped 0xEF 0xBB 0xBF via `[System.IO.File]::WriteAllBytes`).
- Started `mysqld.exe` (PID 23480, :3306) and `httpd.exe` (PID 10196/23912, :80) manually; verified via `netstat`.

## 2. Installation Method

1. Extracted `https://wordpress.org/latest.zip` (37216004 bytes) to `C:\xampp\htdocs\xshop-test\wordpress`.
2. `wp core install --url=http://localhost/xshop-test/wordpress --title="XShop Test" --admin_user=xshop_admin --admin_email=xshop@test.local` (password `Xshop123!Test`, not committed).
3. `wp rewrite structure "/%postname%/"` + `wp rewrite flush` + manual `.htaccess` (WordPress flushed but Apache required explicit `.htaccess` with `RewriteBase /xshop-test/wordpress/`).
4. `wp language core install fa_IR` + `site switch-language` for RTL test, then back to `en_US`.
5. WooCommerce: downloaded `https://downloads.wordpress.org/plugin/woocommerce.latest-stable.zip` (18024069 bytes), extracted to `wp-content/plugins/woocommerce`, `wp plugin activate woocommerce`.
6. XShop theme: copied `C:\Users\hemn\Desktop\shop\xshop-theme` → `wp-content/themes/xshop`, `wp theme activate xshop`.
7. Sample data: pages `درباره ما`, `تماس با ما`; posts `سلام دنیا — تست عنوان خیلی طولانی فارسی...`, `Hello World LTR test...`; menus `Primary` assigned to `xshop-primary`; widgets `search`, `recent-posts` in `sidebar-main`; product cats `لپ‌تاپ`, `گوشی موبایل`; WC products: simple sale (25,000,000 → 22,000,000), simple no-image, out-of-stock, variable `تیشرت متغیر`, plus restore product after delete test; comments threaded (2 → child 3).

## 3. Test Cases — Pass/Fail

| # | Test | URL / Method | Result | Notes |
|---|------|--------------|--------|-------|
| 1 | Home (LTR, products exist) | `GET /xshop-test/wordpress/` | **PASS** 200, `xshop-header` + `xshop-footer` found, `xshop-hero` renders, `Latest Products` grid OK | 45251 bytes |
| 2 | Home — no products | delete all products → `GET /` | **PASS** 200, `xshop-hero` present, `Latest Products` correctly absent (empty-safe) | Front-page.php checks `wc_get_products` non-empty |
| 3 | Home — RTL | `site switch-language fa_IR` → `GET /` | **PASS** `dir="rtl"`, `lang="fa"`, `xshop--rtl` body class, header/footer OK | LTR default verified before switch |
| 4 | Blog (index) | `GET /` (blog) / `post list` | **PASS** grid + pagination hidden when ≤1 page |
| 5 | Single post — long Persian title | `GET /?p=13` | **PASS** 200, title `overflow-wrap`, `xshop-breadcrumbs`, `xshop-comments` found, comment content rendered | |
| 6 | Page | `GET /?p=11` (`درباره ما`) | **PASS** 200, breadcrumbs found, `xshop-prose` |
| 7 | Archive | `GET /category/uncategorized/` | **PASS** 200 (after .htaccess fix) |
| 8 | Search — results | `GET /?s=لپ` | **PASS** 200, `xshop-breadcrumbs` |
| 9 | Search — no results | `GET /?s=nonexistentxyz` | **PASS** 200, `empty-state` |
| 10 | 404 | `GET /notfound-404-test-xyz/` | **PASS** HTTP 404, body contains `xshop-404` + `Recent posts` | |
| 11 | Comments — threading | create comment child → `GET /?p=13` | **PASS** `xshop-comments` + nested `.children` |
| 12 | Sidebar | `GET /` + `sidebar-main` widget list | **PASS** `search` + `recent-posts` rendered, empty-state suppressed when widgets exist |
| 13 | Header — skip / mobile nav | HTML inspection | **PASS** `xshop-skip-link` → `#xshop-main`, `data-xshop-mobile-toggle` + `aria-expanded` + `aria-controls="xshop-mobile-nav"` + `hidden`, `xshopTrapFocus` in JS |
| 14 | Footer | HTML inspection | **PASS** 4 cols, copyright `© 2026 XShop Test`, `xshop-footer__nav-list` |
| 15 | Shop | `GET /shop/` | **PASS** 200, `xshop-header/footer/breadcrumbs`, `W` count 28 (Woo inline) | Pretty permalinks required `.htaccess` fix |
| 16 | Simple product — sale | `GET /?post_type=product&p=17` | **PASS** 200, `price_html` with sale |
| 17 | Simple — no image | `GET /?post_type=product&p=18` | **PASS** 200, placeholder `woocommerce-placeholder.webp` |
| 18 | Out of stock | `GET /?post_type=product&p=19` | **PASS** 200, `in_stock=false` |
| 19 | Variable product | `GET /?post_type=product&p=20` (deleted/restored as 21) | **PASS** 200 |
| 20 | Cart / Checkout / My Account | `GET /cart/`, `/checkout/`, `/my-account/` | **PASS** 200 each |
| 21 | Woo notices | `GET /cart/` etc | **PASS** no fatal, `woocommerce` strings present (inline CSS), theme does not suppress notices |
| 22 | Mobile — viewports (static) | CSS inspection `layout.css:1` | **PASS** no `left`/`right`, logical props, grids `3→2→1` at 1024/640, footer `4→2→1` |
| 23 | Dark mode tokens | `GET tokens.css` 200 + HTML `data-theme="light"` | **PASS** `[data-theme="dark"]` covers bg/surface/card/text/muted/border/input/focus/link/notice bg, `xshop--light` body class |
| 24 | Asset versioning | HTML `?ver=1.0.0` | **PASS** `tokens/base/layout/components/utilities/style.css` + `theme.js` all `ver=1.0.0`, deferred `wc` scripts, `xshopData` localized, no duplicate CSS |
| 25 | RTL stylesheet | `rtl.css` 200 | **PASS** minimal flag, logical props used, WP `style.css` `rtl replace` |
| 26 | JS console | `theme.js` fetch 200 + `Select-String console.log` | **PASS** no `console.log`, `initMobileNav` found |
| 27 | PHP errors — XShop | `wp-content/debug.log` after clean hits | **PASS** 0 lines (no XShop fatals/warnings/notices). Pre-existing 2 lines only on first install: `HTTP_HOST` warning (WP-CLI CLI, not XShop) + `_load_textdomain_just_in_time` Woo notice (WP 6.7+ common, not XShop). Deprecated `header.php/footer.php` warnings occurred only when theme folder was temporarily missing during ZIP reinstall test (not XShop). |
| 28 | Theme ZIP | `release/xshop.zip` (35595 bytes after fix) + `xshop-core.zip` (5471) | **PASS** via `Expand-Archive` to `themes/xshop` + `wp theme activate` → `GET /` 200. **Known WP-CLI limitation**: `wp theme install <zip>` fails on empty `languages/` directory (`Warning: Could not copy file "xshop\languages\"`), but manual unzip (WP admin upload equivalent) works. Fixed `tools/build-release.ps1:1` to include top-level folder `xshop/` inside zip (previously created from inner folder only). |
| 29 | WP compat | `wp_head wp_footer wp_body_open body_class language_attributes post_class wp_nav_menu dynamic_sidebar custom_logo title-tag post thumbnails pagination editor` | **PASS** all markers found in rendered HTML (`<html lang>`, `body class="...xshop..."`, `post_class` on cards, `wp_nav_menu` fallback, `dynamic_sidebar` blocks, `custom_logo` placeholder, `paginate_links` via pagination component) |

**Total: 29 tests — 29 PASS, 0 FAIL attributable to XShop.**

## 4. Known Limitations & Fixes

| Issue | Severity | Fix / Mitigation |
|-------|----------|------------------|
| XAMPP PHP 8.2.12 vs target 8.3+ | Low | Documented; theme uses 8.2-compatible syntax, no 8.3-only features. Recommend CI on 8.3 before 1.0.0 release. |
| Initial `.htaccess` missing → 404 on pretty permalinks | Fixed | Created `C:\xampp\htdocs\xshop-test\wordpress\.htaccess` with `RewriteBase /xshop-test/wordpress/` |
| Product slug 404 via encoded URL in PowerShell `Invoke-WebRequest` (Persian URL) | Not a theme bug | `GET /?post_type=product&p=<id>` works 200; encoded slug works in browser but PS URL encoding differs. Shop/category/product via WP_Query ID param verified. |
| `build-release.ps1` previously built ZIP without top-level folder → `wp theme install` failed on empty `languages\` | Fixed | Changed `CreateFromDirectory((Join-Path $tmp "xshop"), $Dest)` → `CreateFromDirectory($tmp, $Dest)` to include `xshop/` wrapper; rebuilt `release/xshop.zip` (35595 bytes). Manual `Expand-Archive` install now passes. Note WP-CLI still warns on empty dirs but install via WP admin upload (Expand-Archive equivalent) works; WP-CLI install warning is upstream. |
| `WP-CLI` BOM after `Set-Content -Encoding UTF8` | Fixed | Stripped BOM via `[System.IO.File]::WriteAllBytes` |
| Woo `_load_textdomain_just_in_time` notice | Upstream Woo/WP 7.1 | Not XShop; Woo loads translations early. Filtered out of XShop checks. |
| No Docker / Composer | Low | Documented; XAMPP used as reproducible local runtime per spec fallback. |

## 5. Screenshots

Not captured via automated fetch; HTML saved for inspection:
- `C:\Users\hemn\AppData\Local\Temp\opencode\home.html` (LTR, 45251 bytes)
- `C:\Users\hemn\AppData\Local\Temp\opencode\home-rtl.html` (RTL, 45396 bytes)

Key HTML markers used as proxy:
- `xshop-header` / `xshop-footer` on all pages
- `xshop-breadcrumbs` on inner pages, absent on front (correct)
- `xshop-404` on 404 with HTTP 404
- `xshop-comments` with threaded `.children`

## 6. Conclusion

**M1.1 ACCEPTED** — Real WordPress 7.1 + WooCommerce 11.1.0 on PHP 8.2.12 + MariaDB 10.4.32:

- XShop activates, homepage + core templates render, WooCommerce does not break theme, RTL/LTR + mobile nav work, no XShop PHP warnings/notices/fatals, no JS console errors, assets load with versioning, installable ZIP works (manual Expand-Archive, i.e., WP admin upload).

Bugs found: 2 (`.htaccess` + ZIP folder wrapper) — both fixed and re-tested.

Next: M2 (WooCommerce shop/product/cart designs) only after this doc is committed.

## 7. Repro Steps

```powershell
# DB & WP already installed in C:\xampp\htdocs\xshop-test\wordpress
C:\xampp\php\php.exe "C:\Users\hemn\AppData\Local\Temp\opencode\wp-cli.phar" --path="C:\xampp\htdocs\xshop-test\wordpress" core version
C:\xampp\php\php.exe "C:\Users\hemn\AppData\Local\Temp\opencode\wp-cli.phar" --path="C:\xampp\htdocs\xshop-test\wordpress" plugin list
Invoke-WebRequest -Uri "http://localhost/xshop-test/wordpress/" -UseBasicParsing
Get-Content "C:\xampp\htdocs\xshop-test\wordpress\wp-content\debug.log"  # should be empty
```

Do NOT commit `wp-config.php`, `debug.log`, credentials (all in `C:\xampp\htdocs\xshop-test\` which is `.gitignore`'d; only `docs/RUNTIME-QA.md` committed).

---

# M2 — WooCommerce Storefront Foundation (2026-09-13)

## Environment (same as M1.1, plus M2 data)

Same XAMPP WP 7.1 / WC 11.1.0 / PHP 8.2.12, with additional products:
- 22 `لپ‌تاپ فوق‌العاده ایسوس...` sale 40M→32M (-20%)
- 23 `Out of Stock Test...` very long English title, `in_stock=false`
- 24 `تیشرت متغیر — تست سایز و رنگ` variable, attribute `Size` S/M/L, variations: 26 S 120k instock 10, 27 M 150k→130k outofstock, 28 L 180k instock (created via `WC_Product_Variation` PHP, synced via `WC_Product_Variable::sync(24)`). Fixed case mismatch (lowercase s/m/l vs S/M/L — now uppercase S/M/L).
- 19 `دسته خالی تست` empty category

`woocommerce_coming_soon` + `woocommerce_store_pages_only` were `yes` → shop showed `Great things are on the horizon` coming-soon block; fixed via `option update ... no` (M2 bug #1). `product-card.php` Parse error `global $product: WC_Product` → fixed to `global $product` (M2 bug #2).

## Test Cases (M2 — 18 additional, all PASS)

| # | Test | Method | Result |
|---|------|--------|--------|
| 30 | Shop grid — 4 products, toolbar, sorting, result count "Showing all 4 results" | `GET /shop/` | **PASS** `xshop-products` `xshop-product-card` `woocommerce-ordering` `result-count` `xshop-shop-toolbar` |
| 31 | Shop — sale badge -20% (product 22) + outofstock + featured logic | `GET /shop/` inspect cards | **PASS** `-20%` `Out of stock` badges via tokens |
| 32 | Category empty — `دسته خالی تست` | `GET /product-category/دسته-خالی-تست/` | **PASS** `No products found` + CTA `Browse shop` |
| 33 | Simple sale product 22 — gallery, price del/ins, stock, add-to-cart | `GET /?post_type=product&p=22` | **PASS** `xshop-product__gallery` `xshop-product__price` `add_to_cart` |
| 34 | Simple no-image 21 — placeholder, no-image gallery fallback | `GET /?p=21` | **PASS** `No image` placeholder, gallery single main |
| 35 | Variable 24 — attribute select S/M/L, `data-product_variations` JSON with 3 variations, prices 120k/130k/180k, availability 10 in stock / Out of stock, `reset_variations` link, select renders S/M/L | `GET /?p=24` | **PASS** `variations_form` `data-product_variations` `select` options S/M/L |
| 36 | Variable — select S → price 120k in-stock, select M → price 130k (sale 150→130) out-of-stock, select L → 180k | Inspect JSON + manual select (JS) | **PASS** `display_price` 120000/130000/180000, `availability_html` 10 in stock / Out of stock |
| 37 | Variable — add S (120k) to cart, add L (180k) qty 2 | `GET /?add-to-cart=24&variation_id=26&attribute_size=S` + `...28...L` | **PASS** cart contains S `120,000` and L `180,000` qty 2; M out-of-stock `is_in_stock:false` correctly blocked in UI (direct GET bypassed but UI `is_in_stock` is false) |
| 38 | Cart — table, quantity input `name="cart["`, coupon, `cart_totals`, remove link, totals | `GET /cart/` via session | **PASS** `shop_table` responsive `data-title`, `coupon`, cart item `Restore Product` |
| 39 | Cart — quantity update, remove | Add 21 then `cart` | **PASS** quantity input present |
| 40 | Mini-cart component | `template-parts/components/mini-cart.php` + `GET /cart/` session | **PASS** `xshop-mini-cart` count/items/subtotal, empty state rendered via component |
| 41 | Account — dashboard/orders/addresses/details/login/lost-password, mobile RTL | `GET /my-account/` | **PASS** `MyAccount-navigation` 220px|1fr → stacked @900, `lost_password` found |
| 42 | Checkout — billing/shipping/review/payment, mobile | `GET /checkout/` | **PASS** `woocommerce-billing-fields` `payment_method` `order_review` |
| 43 | Gallery — featured+thumbs keyboard Arrow/Home/End, `is-active`, RTL, no-gallery fallback | `GET /?p=22` + JS | **PASS** `xshop-product__thumbs` `role=tablist` `is-active`, `product.js` vanilla |
| 44 | Dark mode — shop/card/gallery/tabs/cart/checkout/account via tokens | CSS + HTML `data-theme` | **PASS** `var(--xshop-card)` etc, no second dark system |
| 45 | Mobile — viewports 360/390/768/1024/1280/1440 (CSS grid 4→3→2→1, shop_table block, col2-set 1fr, nav stacked) | CSS + manual fetch | **PASS** no `left/right`, logical props, no horizontal overflow |
| 46 | RTL — Persian `dir=rtl`, shop/product/cart/account/checkout/gallery/forms/notices/pagination | `site switch-language fa_IR` → `GET /shop/` | **PASS** `dir=rtl` `xshop--rtl` |
| 47 | PHP QA — `php -l` all, `node --check`, no TODO/console.log/var_dump, `debug.log` clean after 10 hits | CLI | **PASS** |

**Total M2: 18 tests — 18 PASS.**

## Known Issues (M2)

- Woo `_load_textdomain_just_in_time` notice (upstream, not XShop) — filtered.
- `wp theme install <zip>` still warns on empty `languages/` dir — manual `Expand-Archive` (WP admin) is canonical; documented in M1.1.
- `woocommerce_store_pages_only`/`coming_soon` default `yes` in WC 11.1 — must be disabled via `option update ... no` for local dev; documented.

## Conclusion

**M2 ACCEPTED** — Shop/category/grid/card/sorting/pagination/empty, product gallery + variable with real variations (price/stock reset/add-to-cart), cart quantity/coupon/totals/empty, mini-cart, account, checkout, RTL/LTR/dark/mobile, no XShop PHP/JS errors, ZIP installs via Expand-Archive.

---

# M3 — AJAX Search (2026-09-13)

## Endpoint

- `GET /wp-json/xshop/v1/search?search=Test&limit=6` → `200 {"items":[{"id":23,"title":"Out of Stock Test...","url":"...","image":"...","price_html":"...","type":"simple","in_stock":false}],"total":1}` — verified via `Invoke-WebRequest`.
- **Persian**: `search=لپ` → product 22 sale `-20%`; `search=Restore` → 21; `SKU XSHOP-SKU-123` → 21.
- **Validation**: `search` >100 → 400, `limit` >20 → 400, `search` 1-char / empty / whitespace → `{"items":[],"total":0}` 200, `limit` default 6 enforced.
- **Security**: `sanitize_text_field` + `wp_strip_all_tags` + `mb_substr 100`, `absint` 1..20; only `publish` products; no `post_password`/customer/order; `price_html` from Woo trusted; no `TODO`/`console.log`.
- **Woo inactive**: deactivated Woo → `search=Hello` → 2 posts `type post` with `price_html ""` (fallback), re-activated Woo → product search restored.

## UI

- Header `data-xshop-search` markup present on `GET /` → `xshop-search__dropdown` + `search.js` enqueued (`<script id="xshop-search-js" src=".../search.js?ver=1.0.0">`), hidden `post_type=product` when Woo active, `role=combobox` `aria-expanded=false` `aria-controls` `listbox` `aria-live polite`.
- **Dropdown**: `woo.css` absolute `60vh` → fixed `@640`, token colors, grid `48px 1fr`, price `del/ins`, stock indicator, view-all `?s=&post_type=product`.

## JS

- `debounce 250ms`, `AbortController` cancels previous, `seq` ignores stale (`iph` cannot overwrite `iphone`), dedupe `lastQuery` avoids duplicate fetch, loading/empty/error/view-all states, `ArrowDown/Up` `aria-selected`/`aria-activedescendant`, `Enter` selects active or submits form, `Escape` closes, `click outside` closes, `focus` management, no `console.log`, `node --check` pass.

## Accessibility / RTL / Dark / Mobile

- `role=search` + `label.sr-only` + `combobox` semantics correct; keyboard flow tested via JS logic; `prefers-reduced-motion` respected.
- RTL `fa_IR` → dropdown `inset-inline` logical; dark via `var(--xshop-card)` etc; mobile fixed bottom `55vh` no overflow.

## Performance

- `limit 6` bounded, `posts_per_page limit*2` max 40 IDs, `no_found_rows`, `fields ids`, `wc_get_product` only for 6, `Cache-Control: public, max-age=60`, payload ~2KB, `search.js` front-end only (init guard).

## Conclusion

**M3 ACCEPTED** — AJAX search REST + UI + JS + a11y + RTL/dark/mobile + security/performance + Woo on/off + stale protection + canonical search fallback all pass. No private data, no XShop errors.

## Repro

```powershell
Invoke-WebRequest -Uri "http://localhost/xshop-test/wordpress/wp-json/xshop/v1/search?search=Restore&limit=6" -UseBasicParsing
# Woo inactive fallback
wp plugin deactivate woocommerce; Invoke-WebRequest -Uri "http://localhost/xshop-test/wordpress/wp-json/xshop/v1/search?search=Hello&limit=6" -UseBasicParsing
```