fix(e2e): make product navigation resilient to sold-out inventory

navigateToFirstProduct was brittle — it clicked the first product link
on the page regardless of stock status. When a test store's first
product happened to be sold out, addToCart() would fail with a
misleading timeout looking for a nonexistent "Add to cart" button.

Introduce navigateToInStockProduct which tries product links
sequentially, checking for an "Add to cart" button before settling.
Sold-out products are skipped. Tests only fail when every product on
the page is unavailable.

Addresses reviewer feedback from Gray, Kara, and John:
- Renamed method to match its actual behavior (navigateToInStockProduct)
- Extracted shared "Add to cart" button locator (getAddToCartButton)
  to eliminate duplication with addToCart()
- Switched from has-text CSS selector to getByRole for consistency
  with project E2E guidelines
- Replaced goBack() with goto(originalUrl) for reliable navigation
- Replaced networkidle waits with visible-element assertions
- Added max-attempts cap (10) to bound failure time
- Named the timeout constant with explanatory context

A deprecated navigateToFirstProduct alias is kept to avoid breaking
any external callers, but all internal call sites are updated.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: kdaviduik

e2e/CLAUDE.md

@@ -56,7 +56,7 @@ Per [Playwright best practices](https://playwright.dev/docs/best-practices#make-
 test.describe('Quantity Management', () => {
   test.beforeEach(async ({storefront}) => {
     await storefront.goto('/');
-    await storefront.navigateToFirstProduct();
+    await storefront.navigateToInStockProduct();
     await storefront.addToCart();
   });
 
@@ -70,7 +70,7 @@ test.describe('Quantity Management', () => {
 // ACCEPTABLE: Duplicate simple 1-2 line setups when it improves clarity
 test('adds item to empty cart', async ({storefront}) => {
   await storefront.goto('/');
-  await storefront.navigateToFirstProduct();
+  await storefront.navigateToInStockProduct();
   await storefront.addToCart();
 
   await expect(storefront.getCartLineItems()).toHaveCount(1);
@@ -79,7 +79,7 @@ test('adds item to empty cart', async ({storefront}) => {
 // AVOID: Repeating 3+ lines in every test
 test('increases quantity', async ({storefront}) => {
   await storefront.goto('/'); // Repeated
-  await storefront.navigateToFirstProduct(); // Repeated
+  await storefront.navigateToInStockProduct(); // Repeated
   await storefront.addToCart(); // Repeated
   // Use beforeEach instead
 });

e2e/fixtures/storefront.ts

@@ -460,22 +460,63 @@ export class StorefrontPage {
   }
 
   /**
-   * Navigate to the first product on the page
-   */
+   * Navigate to an in-stock product by trying product links sequentially.
+   * Skips sold-out products (no "Add to cart" button) so that tests only
+   * fail when every product on the page is unavailable.
+   */
+  async navigateToInStockProduct() {
+    const listingUrl = this.page.url();
+    const productLinks = this.page.locator('a[href*="/products/"]');
+    const linkCount = await productLinks.count();
+    expect(linkCount, 'At least one product link should exist').toBeGreaterThan(
+      0,
+    );
+
+    // Cap attempts to avoid slow failure on pages with many products
+    const MAX_PRODUCT_ATTEMPTS = 10;
+    const attemptsToMake = Math.min(linkCount, MAX_PRODUCT_ATTEMPTS);
+    // Shorter timeout than addToCart — just checking presence, not waiting
+    // for a slow action. Long enough for SSR pages to render the button.
+    const IN_STOCK_CHECK_TIMEOUT_MS = 5000;
+
+    for (let i = 0; i < attemptsToMake; i++) {
+      const link = productLinks.nth(i);
+      if (!(await link.isVisible())) continue;
+
+      await link.click();
+
+      const isInStock = await this.getAddToCartButton()
+        .isVisible({timeout: IN_STOCK_CHECK_TIMEOUT_MS})
+        .catch(() => false);
+
+      if (isInStock) return;
+
+      // Product is sold out — return to listing and try the next one
+      await this.page.goto(listingUrl);
+      await expect(productLinks.first()).toBeVisible();
+    }
+
+    throw new Error(
+      `No in-stock products found at ${listingUrl} ` +
+        `(checked ${attemptsToMake} of ${linkCount} product links). ` +
+        'All products appear to be sold out.',
+    );
+  }
+
+  /** @deprecated Use {@link navigateToInStockProduct} instead */
   async navigateToFirstProduct() {
-    const productLink = this.page.locator('a[href*="/products/"]').first();
-    await expect(productLink).toBeVisible();
-    await productLink.click();
-    await this.page.waitForLoadState('networkidle');
+    return this.navigateToInStockProduct();
+  }
+
+  private getAddToCartButton() {
+    return this.page.getByRole('button', {name: /add to cart/i});
   }
 
   /**
    * Click the "Add to cart" button and wait for cart drawer with checkout URL
    */
   async addToCart() {
-    const addToCartButton = this.page.locator(
-      'button:has-text("Add to cart"), button:has-text("Add to Cart")',
-    );
+    const addToCartButton = this.getAddToCartButton();
     await expect(addToCartButton).toBeVisible({timeout: 10000});
     await addToCartButton.click();
 

e2e/specs/new-cookies/consent-tracking-accept.spec.ts

@@ -84,7 +84,7 @@ test.describe('Consent Tracking - Auto-Allowed (Consent Allowed by Default)', ()
     await storefront.finalizePerfKitMetrics();
 
     // 7. Navigate to a product (triggers perf-kit to send metrics)
-    await storefront.navigateToFirstProduct();
+    await storefront.navigateToInStockProduct();
 
     // Wait for perf-kit to send metrics after visibility change
     await storefront.page.waitForTimeout(500);

e2e/specs/new-cookies/consent-tracking-decline.spec.ts

@@ -53,7 +53,7 @@ test.describe('Consent Tracking - No Banner (Declined by Default)', () => {
     storefront.expectNoMonorailRequests();
 
     // 10. Navigate to first product and add to cart
-    await storefront.navigateToFirstProduct();
+    await storefront.navigateToInStockProduct();
     await storefront.addToCart();
 
     // 11. Check server-timing from cart mutation - should be mock values

e2e/specs/new-cookies/privacy-banner-accept.spec.ts

@@ -115,7 +115,7 @@ test.describe('Privacy Banner - Accept Flow', () => {
     await storefront.finalizePerfKitMetrics();
 
     // 10. Navigate to a product (this triggers perf-kit to send metrics via visibility change)
-    await storefront.navigateToFirstProduct();
+    await storefront.navigateToInStockProduct();
 
     // 11. Verify perf-kit payload contains correct tracking values
     // Wait a moment for perf-kit to send its metrics after visibility change

e2e/specs/new-cookies/privacy-banner-consent-change.spec.ts

@@ -83,7 +83,7 @@ test.describe('Privacy Banner - Consent Change', () => {
       storefront.expectNoMonorailRequests();
 
       // 11. Navigate to a product page to verify no tracking on navigation
-      await storefront.navigateToFirstProduct();
+      await storefront.navigateToInStockProduct();
 
       // Still no analytics requests after navigation
       storefront.expectNoMonorailRequests();
@@ -198,7 +198,7 @@ test.describe('Privacy Banner - Consent Change', () => {
 
       // 11. Navigate to a product page
       await storefront.finalizePerfKitMetrics();
-      await storefront.navigateToFirstProduct();
+      await storefront.navigateToInStockProduct();
 
       // Note: We skip perf-kit request verification here because it captures Y/S values
       // only when its script is first downloaded so it won't update the values after changing

e2e/specs/new-cookies/privacy-banner-decline.spec.ts

@@ -56,7 +56,7 @@ test.describe('Privacy Banner - Decline Flow', () => {
     storefront.expectNoMonorailRequests();
 
     // 11. Navigate to first product and add to cart to verify server-timing mock values
-    await storefront.navigateToFirstProduct();
+    await storefront.navigateToInStockProduct();
 
     // Add item to cart
     await storefront.addToCart();

e2e/specs/old-cookies/consent-tracking-accept.spec.ts

@@ -64,7 +64,7 @@ test.describe('Consent Tracking - Auto-Allowed (Consent Allowed by Default)', ()
     await storefront.finalizePerfKitMetrics();
 
     // 7. Navigate to a product (triggers perf-kit to send metrics)
-    await storefront.navigateToFirstProduct();
+    await storefront.navigateToInStockProduct();
 
     // Wait for perf-kit to send metrics after visibility change
     await storefront.page.waitForTimeout(500);

e2e/specs/old-cookies/consent-tracking-decline.spec.ts

@@ -53,7 +53,7 @@ test.describe('Consent Tracking - No Banner (Declined by Default)', () => {
     storefront.expectNoMonorailRequests();
 
     // 10. Navigate to first product and add to cart
-    await storefront.navigateToFirstProduct();
+    await storefront.navigateToInStockProduct();
     await storefront.addToCart();
 
     // 11. Check server-timing from cart mutation - should be mock values

e2e/specs/old-cookies/privacy-banner-accept.spec.ts

@@ -96,7 +96,7 @@ test.describe('Privacy Banner - Accept Flow', () => {
     await storefront.finalizePerfKitMetrics();
 
     // 10. Navigate to a product (this triggers perf-kit to send metrics via visibility change)
-    await storefront.navigateToFirstProduct();
+    await storefront.navigateToInStockProduct();
 
     // 11. Verify perf-kit payload contains correct tracking values
     // Wait a moment for perf-kit to send its metrics after visibility change