Ui4 Convert Tests

UI4 Convert Tests

Overview

After completing UI changes, this skill systematically identifies and fixes affected e2e tests. It analyzes the diff to understand what kind of changes were made (not just which files), then finds tests that need updates.

When to Use

• UI changes are finalized and ready for test fixes
• CI is failing on tests due to your UI changes
• Before opening a PR to ensure tests pass

Process

Step 1: Analyze What Changed

Goal: Understand the nature of your changes to predict test impact.

# Get changed UI files
git diff main --name-only -- 'packages/ui/src/**/*.tsx' 'packages/ui/src/**/*.css'

For each changed file, categorize the changes:

A. Selector Changes (IDs, classes)

git diff main -- <file> | grep -E '^\-.*className|^\-.*id=|^\+.*className|^\+.*id='

B. Structural Changes (elements moved)

Look for components being:

• Moved INTO a popup, drawer, or dropdown
• Wrapped in new parent elements
• Made conditional

git diff main -- <file> | grep -E 'Popup|PopupList|Drawer|Dropdown'

C. Text/Label Changes

# Translation keys
git diff main -- <file> | grep -E "t\('|i18n\.t\("

# Hardcoded text
git diff main -- <file> | grep -E 'placeholder=|aria-label='

Build a change summary:

Step 2: Find Affected Tests

Search strategy: Cast a wide net, then narrow down.

# Search for component name references (not just selectors)
grep -rn "QueryPreset\|query-preset\|preset" test/**/*.ts --include="*.spec.ts" --include="*.ts"

# Search for specific selectors from Step 1
grep -rn "\.list-header\|Create New\|#create-new" test/**/*.ts

Key test locations:

Don't just search for exact selectors! Also search for:

• Component names (e.g., QueryPreset, ListHeader)
• Feature names (e.g., preset, filter, search)
• Text content that changed (e.g., "Create New", "Search by")

Step 3: Analyze Test Dependencies

Before fixing, understand the test:

1. Read the full test - Understand what it's actually testing
2. Check for helpers - Is there a shared helper that handles this selector?
3. Look for patterns - Are multiple tests doing the same thing?

If multiple tests use the same selector, create/update a helper:

// test/<feature>/helpers/togglePreset.ts
export async function openCreatePreset(page: Page) {
  await page.click('#select-preset') // Open popup first
  await page.click('#create-new-preset')
}

This centralizes the fix and prevents future duplication.

Step 4: Categorize Fixes Needed

Step 5: Run Affected Tests

Run tests BEFORE making fixes to confirm they actually fail:

# Use isolated port to avoid conflicts
PORT=3150 pnpm test:e2e <suite> --max-failures=1

# Run specific test by name
PORT=3150 pnpm test:e2e <suite> -g "test name" --max-failures=1

Document failure patterns:

• Timeout waiting for locator('.old-selector') → Selector changed
• locator resolved to 0 elements → Element moved or removed
• expected "New Text" received "Old Text" → Text content changed

Step 6: Apply Fixes

Priority: Fix helpers first, then individual tests.

Pattern 1: Selector Renamed

// Before
await page.click('.list-header .btn:has-text("Create")')

// After - prefer IDs when available
await page.click('#create-new-doc')

Pattern 2: Element Moved Into Popup

// Before - direct click
await page.click('#edit-preset')

// After - open popup first
await page.click('#select-preset') // Opens the popup
await page.click('#edit-preset') // Now visible in popup

Pattern 3: Text Content Simplified

// Before - specific placeholder text
await expect(input).toHaveAttribute('placeholder', /(Search by ID)/)

// After - simplified text
await expect(input).toHaveAttribute('placeholder', 'Search')

Pattern 4: Create Reusable Helper

When the same interaction is needed in multiple tests:

// test/<feature>/helpers/interactions.ts
export async function openEditPreset(page: Page) {
  await page.click('#select-preset')
  await page.click('#edit-preset')
}

// In tests - import and use
import { openEditPreset } from './helpers/interactions.js'
await openEditPreset(page)

Step 7: Verify Fixes

# Run same tests that failed
PORT=3150 pnpm test:e2e <suite> --max-failures=1

Only commit after tests pass.

Common Patterns (Real Examples)

Pattern: Buttons Moved Into Popup Menu

Symptom: Test times out waiting for button that used to be directly visible.

Detection: Check if buttons were wrapped in <Popup> or <PopupList>:

git diff main -- <file> | grep -E 'PopupList|Popup'

Fix: Add popup trigger click before clicking the button:

// Before: Button was directly in toolbar
await page.click('#edit-preset')

// After: Button is now inside a popup
await page.click('#select-preset') // Opens popup
await page.click('#edit-preset') // Now visible

Bonus: If multiple tests need this, create a helper function.

Pattern: Class-Based Selector → ID Selector

Symptom: .some-class or :has-text("Button Text") no longer finds element.

Detection: Component added id= attribute:

git diff main -- <file> | grep -E '^\+.*id='

Fix: Use the more stable ID:

// Before: Fragile class + text selector
await page.click('.list-header .btn:has-text("Create New")')

// After: Stable ID selector
await page.click('#create-new-doc')

Pattern: Placeholder/Label Text Simplified

Symptom: Assertion fails with expected "New Text" received "Old Text".

Detection: Translation key or hardcoded text changed:

git diff main -- <file> | grep -E 'placeholder=|t\('

Fix: Update assertion to match new text:

// Before: Verbose placeholder
await expect(input).toHaveAttribute('placeholder', /(Search by ID, Title)/)

// After: Simplified
await expect(input).toHaveAttribute('placeholder', 'Search')

Pattern: Same Fix Needed Across Multiple Tests

Symptom: Several tests in different suites fail with similar selector issues.

Detection:

# Find all tests using the old selector
grep -rn "old-selector\|.old-class" test/**/*.ts

Fix:

1. Check if a helper already exists in test/<feature>/helpers/
2. If yes, fix the helper (fixes all tests at once)
3. If no, create one and refactor tests to use it