Template Site Component Audit & Testing Plan

Context

Why this change is needed:

The Template site is the foundation for all production sites in the monorepo. The last session (2026-02-14) established comprehensive testing infrastructure (SEO tests, Lighthouse CI, Vitest coverage, 7-project CI matrix), but focused primarily on infrastructure setup rather than exhaustive component testing.

Current state:

• 72+ Astro components exist across categories (UI, layout, blocks, brand, showcase)
• Only ~17% of components are fully tested
• 72% of components (48+) have zero dedicated tests
• Major gaps in interaction testing, visual regression, and state management
• 5 fixme tests exist (accessibility/color contrast issues)

Intended outcome:

• Complete audit of all 72+ components with comprehensive test coverage
• Resolve all 5 fixme tests
• Establish systematic testing approach for Template site components
• Create reusable test patterns for production sites

---

Phase 1: Infrastructure Completion

1.1 Resolve Fixme Tests (5 tests currently skipped)

Files to modify:

• sites/Template/tests/dark-mode.spec.ts - Re-enable accessibility test after fixes
• sites/Template/tests/accessibility.spec.ts - Re-enable WCAG/contrast tests after fixes
• sites/Template/src/layouts/BaseLayout.astro - Add missing title/lang attributes
• Design token files - Adjust color pairs to meet 4.5:1 contrast ratio

Actions:

1. Fix missing title tags and lang attributes in layout templates
2. Run axe-core scan to identify specific WCAG violations
3. Adjust design token color pairs to meet WCAG AA contrast (4.5:1)
4. Remove .fixme from all 5 tests
5. Verify all accessibility tests pass across 7 projects

1.2 Test Organization Structure

Create new test organization:

sites/Template/tests/
├── components/              # NEW: Component-specific tests
│   ├── ui/                 # UI component tests
│   │   ├── button.spec.ts
│   │   ├── form-fields.spec.ts
│   │   ├── modal.spec.ts
│   │   ├── cards.spec.ts
│   │   └── badges-alerts.spec.ts
│   ├── blocks/             # Block component tests
│   │   ├── forms.spec.ts
│   │   ├── content-blocks.spec.ts
│   │   └── testimonials.spec.ts
│   ├── layout/             # Layout component tests
│   │   └── navigation.spec.ts
│   └── brand/              # Brand component tests
│       └── branding.spec.ts
├── interaction/            # NEW: Interaction-focused tests
│   ├── keyboard-nav.spec.ts
│   ├── focus-management.spec.ts
│   └── state-changes.spec.ts
├── visual/                 # NEW: Visual regression tests (expand existing)
│   ├── components-light.spec.ts
│   ├── components-dark.spec.ts
│   └── variants.spec.ts
├── utils/                  # NEW: Shared test utilities
│   ├── interactions.ts     # Click, type, hover, focus helpers
│   ├── visual.ts          # Screenshot comparison utilities
│   ├── accessibility.ts    # Axe-core scan helpers
│   └── fixtures.ts        # Test data/constants
├── [existing files]        # Keep all 11 existing spec files
└── ...

Files to create:

• sites/Template/tests/utils/interactions.ts - Reusable interaction helpers
• sites/Template/tests/utils/visual.ts - Screenshot/visual regression utilities
• sites/Template/tests/utils/accessibility.ts - Axe-core scan helpers
• sites/Template/tests/utils/fixtures.ts - Test data and constants

1.3 Test Configuration Updates

File to modify: sites/Template/playwright.config.ts

Add:

• Separate timeout for visual regression tests (may need longer)
• Screenshot comparison threshold configuration
• Retry logic for flaky visual tests
• Reporter configuration for better test output organization

---

Phase 2: Priority 1 Component Testing (Week 1)

2.1 Form Component Suite

File to create: sites/Template/tests/components/ui/form-fields.spec.ts

Test scenarios:

• Input: Focus, blur, validation, error state, disabled state
• Checkbox: Click toggle, keyboard spacebar toggle, checked/unchecked states, disabled
• RadioGroup: Click selection, arrow key navigation, selection state, disabled
• Select: Click to open, arrow key navigation, option selection, keyboard Enter, disabled
• Textarea: Multi-line input, character limit (if exists), resize behavior

Coverage: Input.astro, Checkbox.astro, RadioGroup.astro, Select.astro, Textarea.astro (5 components)

2.2 Button Component Variants

File to create: sites/Template/tests/components/ui/button.spec.ts

Test scenarios:

• All button variants: default, primary, secondary, outline, ghost, destructive
• All button sizes: sm, md, lg
• Button states: default, hover, focus, active, disabled
• Icon buttons (if exist)
• Loading state (if exists)
• Visual regression screenshots for all variants

Coverage: Button.astro (1 component, 18+ variant combinations)

2.3 Modal/Dialog Interactions

File to create: sites/Template/tests/components/ui/modal.spec.ts

Test scenarios:

• Open modal via button click
• Close modal with Esc key
• Close modal by clicking backdrop
• Focus trap (Tab cycles only within modal)
• Initial focus on first interactive element
• Scroll lock when modal open
• Aria attributes (aria-modal, aria-labelledby, aria-describedby)

Coverage: Modal.astro (1 component)

2.4 Navigation & Header

File to create: sites/Template/tests/components/layout/navigation.spec.ts

Test scenarios:

• Mobile menu: Hamburger appears below 50rem breakpoint
• Mobile menu: Opens on hamburger click
• Mobile menu: Closes on item click
• Mobile menu: Closes on outside click
• Desktop menu: Navigation visible above 50rem
• Active link highlighting
• Search button integration (already tested in search.spec.ts, verify integration)

Coverage: Header.astro (1 component)

Deliverables (Week 1):

• 4 new test files created
• 8 components fully tested
• 30+ test scenarios added
• All tests passing across 7 projects

---

Phase 3: Priority 2 Component Testing (Week 2)

3.1 Content Block Components

File to create: sites/Template/tests/components/blocks/content-blocks.spec.ts

Test scenarios:

• FAQ/Accordion: Expand/collapse individual items, only one open at a time
• Testimonials: Render correctly, no layout breaks
• TestimonialsCarousel: Navigate with arrows, auto-advance (if exists), dots pagination
• Stats: Numbers display correctly, animation on viewport entry (if exists)
• Timeline: Timeline markers visible, proper spacing, content aligned
• TableOfContents: Generates correctly, links scroll to sections, active section highlighting
• ShareButtons: Social sharing buttons visible, click handlers work

Coverage: ContentFAQ.astro, Testimonials.astro, TestimonialFeatured.astro, TestimonialsCarousel.astro, Stats.astro, ContentTimeline.astro, TableOfContents.astro, ShareButtons.astro (8 components)

3.2 Advanced Form Components

File to create: sites/Template/tests/components/blocks/forms.spec.ts

Test scenarios:

• Newsletter form: Email validation (already tested), success message, error message
• Contact form: Multi-field validation, required fields, email format, success flow, error flow
• LeadMagnet form: Form submission, validation
• MultiStep form: Step navigation, step validation, progress indicator, back/forward navigation
• Calculator form: Input validation, calculation accuracy, result display

Coverage: NewsletterForm.astro, ContactForm.astro, LeadMagnetForm.astro, MultiStepForm.astro, CalculatorForm.astro (5 components)

3.3 Dark Mode Comprehensive

File to create: sites/Template/tests/visual/components-dark.spec.ts

Test scenarios:

• All major UI components in dark mode: Button, Card, Alert, Badge, Form fields
• All layout components in dark mode: Header, Footer, Container, Section
• Image visibility in dark mode
• Color contrast validation in dark mode (WCAG AA)
• Theme switcher visual state
• Logo/brand elements in dark mode

Coverage: Visual regression for 20+ components in dark mode

3.4 Cards, Badges, Alerts

File to create: sites/Template/tests/components/ui/cards.spec.ts

Test scenarios:

• Card component: Default, with header, with footer, with image, hover states
• Badge component: All variants (default, primary, secondary, outline, destructive)
• Alert component: All variants (info, success, warning, error), dismissible vs permanent
• Banner component: Position (above-header, below-header), dismissible, variants

Coverage: Card.astro, Badge.astro, Alert.astro, Banner.astro (4 components)

Deliverables (Week 2):

• 4 new test files created
• 17+ components fully tested
• 40+ test scenarios added
• Visual regression coverage expanded to 20+ components in dark mode

---

Phase 4: Priority 3 Component Testing (Week 3)

4.1 Advanced Interactions

File to create: sites/Template/tests/interaction/keyboard-nav.spec.ts

Test scenarios:

• Dropdown menu: Keyboard navigation (arrow keys, Enter to select, Esc to close)
• Tab component: Arrow key navigation between tabs
• Accordion: Arrow key navigation, keyboard expand/collapse
• Select dropdown: Arrow keys, type-ahead search (if exists)
• Form fields: Tab order validation across complex forms

Coverage: DropdownMenu.astro, Tabs.astro, Accordion.astro, Select.astro (4 components)

4.2 Brand Components

File to create: sites/Template/tests/components/brand/branding.spec.ts

Test scenarios:

• Logo.astro: Renders correctly, links to homepage, proper alt text
• SmartDebt.astro: Entity name displays, proper styling
• SmartDebtEntity.astro: Full entity display with logo+text
• BrandLogo.astro: Switches between SD/TS based on brand prop
• TSLogo.astro: Already tested (keep existing)
• ThemeSwitcher/ThemeSwitcherEnhanced: Toggle functionality, persistence, visual states

Coverage: Logo.astro, SmartDebt.astro, SmartDebtEntity.astro, BrandLogo.astro, ThemeSwitcher.astro (5 components)

4.3 Remaining Content Blocks

File to create: sites/Template/tests/components/blocks/misc-blocks.spec.ts

Test scenarios:

• ContentSimple: Text rendering, proper spacing
• ContentTwoColumn: Columns display correctly, responsive stacking
• ContentWithSidebar: Sidebar visible on desktop, stacks on mobile
• ContentPricing: Pricing cards render, CTA buttons work
• ReviewsAggregate: Review data displays, star ratings visible
• RelatedContent: Links render, navigation works
• LogoCloud: Logos display in grid, proper spacing
• ScrollProgress: Progress bar visible on scroll, updates correctly
• LoadingState: Loading spinner/skeleton displays

Coverage: ContentSimple.astro, ContentTwoColumn.astro, ContentWithSidebar.astro, ContentPricing.astro, ReviewsAggregate.astro, RelatedContent.astro, LogoCloud.astro, ScrollProgress.astro, LoadingState.astro (9 components)

4.4 Visual Regression Expansion

File to create: sites/Template/tests/visual/variants.spec.ts

Test scenarios:

• Button variants: All 6+ variants in light and dark mode
• Form components: Empty, filled, error, focused states
• Cards: Default, hover, with image, without image
• Badges and Alerts: All variants visual comparison
• Dropdown menu: Open and closed states
• Modal: Backdrop + modal content

Coverage: Visual regression for 30+ component state combinations

Deliverables (Week 3):

• 4 new test files created
• 18+ components fully tested
• 35+ test scenarios added
• Visual regression library expanded to 50+ screenshots

---

Phase 5: Advanced Testing & Polish (Week 4+)

5.1 Accessibility Deep Dive

File to create: sites/Template/tests/interaction/focus-management.spec.ts

Test scenarios:

• Focus trap in modals
• Tab order validation across all pages
• Focus indicator visibility on all interactive elements
• Skip to content link functionality
• ARIA attributes validation per component
• Screen reader text validation (sr-only classes)

Coverage: Cross-component accessibility validation

5.2 Responsive Edge Cases

File to update: sites/Template/tests/responsive.spec.ts

Add scenarios:

• Breakpoint boundaries (49.9rem, 50rem, 50.1rem)
• Mobile landscape orientation (swap width/height)
• Component overlap detection on narrow screens
• Image aspect ratio preservation across viewports
• Text overflow handling (long words, long content)

5.3 Utility Components

File to create: sites/Template/tests/components/ui/utility.spec.ts

Test scenarios:

• Separator: Horizontal and vertical variants render
• Label: Associates with form fields correctly
• Form wrapper: Proper structure and validation
• Typewriter: Animation completes, displays final text
• More.astro: Dropdown/expansion functionality

Coverage: Separator.astro, Label.astro, Form.astro, Typewriter.astro, More.astro (5 components)

5.4 Performance Baseline

File to create: sites/Template/tests/performance/lighthouse.spec.ts

Test scenarios:

• Lighthouse scores: Performance ≥85, Accessibility ≥90, Best Practices ≥90, SEO ≥85
• Core Web Vitals: LCP ≤3s, FID ≤100ms, CLS ≤0.1
• Asset load times: Critical CSS, fonts, images
• JavaScript bundle size monitoring

Note: Lighthouse tests already configured in .github/workflows/test.yml but not in Playwright suite

Deliverables (Week 4+):

• 3 new test files created
• 5+ components fully tested
• 25+ test scenarios added
• Performance baseline established

---

Test Execution Strategy

Incremental Testing Approach

For each component:

1. Render test - Component renders without errors
2. Visual regression - Screenshot in light and dark mode
3. Interaction test - User interactions work (click, type, keyboard)
4. Accessibility test - axe-core scan passes, keyboard accessible
5. Responsive test - Works on mobile, tablet, desktop
6. State test - All component states tested (default, hover, focus, disabled, error)

Test Writing Pattern

sites/Template/tests/components/ui/button.spec.ts

import { test, expect } from '@playwright/test';

test.describe('Button Component', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/components');
  });

  test('renders all button variants', async ({ page }) => {
    const buttonShowcase = page.locator('[data-testid="buttons-showcase"]');
    await expect(buttonShowcase.locator('button.btn-default')).toBeVisible();
    await expect(buttonShowcase.locator('button.btn-primary')).toBeVisible();
    await expect(buttonShowcase.locator('button.btn-secondary')).toBeVisible();
    await expect(buttonShowcase.locator('button.btn-outline')).toBeVisible();
    await expect(buttonShowcase.locator('button.btn-ghost')).toBeVisible();
    await expect(buttonShowcase.locator('button.btn-destructive')).toBeVisible();
  });

  test('visual regression - all button variants', async ({ page }) => {
    const buttonShowcase = page.locator('[data-testid="buttons-showcase"]');
    await expect(buttonShowcase).toHaveScreenshot('buttons-all-variants.png');
  });

  test('button hover states work', async ({ page }) => {
    const primaryButton = page.locator('button.btn-primary').first();
    await primaryButton.hover();
    await expect(primaryButton).toHaveScreenshot('button-primary-hover.png');
  });

  test('disabled button not clickable', async ({ page }) => {
    const disabledButton = page.locator('button:disabled').first();
    await expect(disabledButton).toBeDisabled();
    let clicked = false;
    await disabledButton.click({ force: true }).catch(() => clicked = false);
    expect(clicked).toBe(false);
  });
});

Test Data Fixtures

Create: sites/Template/tests/utils/fixtures.ts

export const validationCases = {
  email: {
    valid: ['test@example.com', 'user+tag@domain.co.uk'],
    invalid: ['invalid', 'test@', '@example.com', 'test @example.com'],
  },
  phone: {
    valid: ['555-1234', '(555) 123-4567', '555.123.4567'],
    invalid: ['abc', '123', 'phone'],
  },
  longText: 'Lorem ipsum '.repeat(100), // 1200+ chars
  specialChars: '<script>alert("xss")</script>',
};

export const buttonVariants = [
  'default', 'primary', 'secondary', 'outline', 'ghost', 'destructive'
];

export const buttonSizes = ['sm', 'md', 'lg'];

Interaction Helpers

Create: sites/Template/tests/utils/interactions.ts

import { Page, Locator } from '@playwright/test';

export async function clickAndWait(locator: Locator, waitMs = 300) {
  await locator.click();
  await new Promise(resolve => setTimeout(resolve, waitMs));
}

export async function typeSlowly(locator: Locator, text: string, delayMs = 50) {
  await locator.clear();
  for (const char of text) {
    await locator.type(char, { delay: delayMs });
  }
}

export async function hoverAndScreenshot(locator: Locator, filename: string) {
  await locator.hover();
  await new Promise(resolve => setTimeout(resolve, 200)); // Wait for hover state
  return await locator.screenshot({ path: filename });
}

export async function tabThroughElements(page: Page, expectedElements: string[]) {
  for (const selector of expectedElements) {
    await page.keyboard.press('Tab');
    const focused = await page.locator(selector).evaluate(el => el === document.activeElement);
    if (!focused) throw new Error(`Expected ${selector} to be focused`);
  }
}

---

Verification Plan

End-to-End Verification

After completing all phases:

1. Run full test suite locally:

   cd sites/Template
   pnpm test:e2e

   • Expected: 200+ tests passing across 7 projects
   • Zero fixme tests remaining
   • Zero flaky tests

2. Run test coverage report:

   cd /home/ta/projects/monorepo
   pnpm test:coverage

   • Expected: 95%+ coverage maintained on design-tokens

3. Check TypeScript validation:

   cd sites/Template
   pnpm test

   • Expected: 0 errors, 0 warnings

4. Verify Lighthouse CI (in GitHub Actions):

   • Push to main branch
   • Check .github/workflows/test.yml Lighthouse job passes
   • Performance ≥85, Accessibility ≥90, Best Practices ≥90, SEO ≥85

5. Visual regression validation:

   • Review all screenshot diffs
   • Update baselines if intentional changes
   • Investigate any unexpected visual changes

Success Metrics

• ✅ 100% of 72+ components have dedicated tests
• ✅ Zero fixme/skipped tests
• ✅ All 7 Playwright projects passing
• ✅ 200+ test scenarios covering interactions, visual, a11y, responsive
• ✅ Component test coverage map documented
• ✅ Reusable test patterns established
• ✅ Lighthouse CI passing on main branch

---

Critical Files Summary

Files to Create (17 new test files):

1. sites/Template/tests/components/ui/form-fields.spec.ts
2. sites/Template/tests/components/ui/button.spec.ts
3. sites/Template/tests/components/ui/modal.spec.ts
4. sites/Template/tests/components/ui/cards.spec.ts
5. sites/Template/tests/components/ui/utility.spec.ts
6. sites/Template/tests/components/layout/navigation.spec.ts
7. sites/Template/tests/components/blocks/content-blocks.spec.ts
8. sites/Template/tests/components/blocks/forms.spec.ts
9. sites/Template/tests/components/blocks/misc-blocks.spec.ts
10. sites/Template/tests/components/brand/branding.spec.ts
11. sites/Template/tests/visual/components-dark.spec.ts
12. sites/Template/tests/visual/variants.spec.ts
13. sites/Template/tests/interaction/keyboard-nav.spec.ts
14. sites/Template/tests/interaction/focus-management.spec.ts
15. sites/Template/tests/utils/interactions.ts
16. sites/Template/tests/utils/visual.ts
17. sites/Template/tests/utils/fixtures.ts

Files to Modify:

1. sites/Template/src/layouts/BaseLayout.astro - Fix missing title/lang attributes
2. sites/Template/tests/dark-mode.spec.ts - Remove fixme from accessibility test
3. sites/Template/tests/accessibility.spec.ts - Remove fixme from WCAG/contrast tests
4. sites/Template/tests/responsive.spec.ts - Add breakpoint edge case tests
5. sites/Template/playwright.config.ts - Add visual regression config
6. Design token color files (if needed for contrast fixes)

Component Coverage Tracking

Priority 1 (Week 1) - 8 components:

• Input, Checkbox, RadioGroup, Select, Textarea (5)
• Button (1)
• Modal (1)
• Header (1)

Priority 2 (Week 2) - 17 components:

• ContentFAQ, Testimonials, TestimonialFeatured, TestimonialsCarousel, Stats, ContentTimeline, TableOfContents, ShareButtons (8)
• Newsletter, Contact, LeadMagnet, MultiStep, Calculator forms (5)
• Card, Badge, Alert, Banner (4)

Priority 3 (Week 3) - 18 components:

• DropdownMenu, Tabs, Accordion, Select (4)
• Logo, SmartDebt, SmartDebtEntity, BrandLogo, ThemeSwitcher (5)
• ContentSimple, ContentTwoColumn, ContentWithSidebar, ContentPricing, ReviewsAggregate, RelatedContent, LogoCloud, ScrollProgress, LoadingState (9)

Priority 4 (Week 4+) - 5 components:

• Separator, Label, Form, Typewriter, More (5)

Total: 48 components (covers all previously untested components)

---

Risk Mitigation

Potential Issues:

1. Visual regression flakiness

   • Mitigation: Disable animations in tests, wait for network idle, use consistent viewport sizes
   • Fallback: Increase pixel diff threshold if needed

2. Test execution time

   • Mitigation: Run tests in parallel, use sharding for 7 projects
   • Fallback: Split into separate CI jobs if total time exceeds 30 minutes

3. Component changes during testing

   • Mitigation: Test one category at a time, commit after each phase
   • Fallback: Update tests alongside component changes

4. Accessibility fixes may require design changes

   • Mitigation: Document color contrast issues, propose design token adjustments
   • Fallback: Add aria-label overrides if design can’t change immediately

5. Missing test data for complex components

   • Mitigation: Create fixtures.ts early with realistic test data
   • Fallback: Use placeholder data, document TODOs for real data

---

Timeline Estimate

• Phase 1 (Infrastructure): 2 days
• Phase 2 (Priority 1): 5 days
• Phase 3 (Priority 2): 5 days
• Phase 4 (Priority 3): 5 days
• Phase 5 (Advanced): 3 days
• Verification & Polish: 2 days

Total: ~22 working days (4-5 weeks)

Parallelization opportunities:

• Test file creation can happen concurrently
• Visual regression and interaction tests can be written independently
• Each component category can be tested by different team members (if applicable)

---

Implementation Approach

Given full autonomous permissions, I will:

1. Execute incrementally with testing at each step

   • Create test files one phase at a time
   • Run tests after each file to ensure they pass
   • Commit working tests before moving to next phase

2. Verify end-to-end functionality

   • Not just check syntax, but run actual Playwright tests
   • Verify visual regression screenshots generate correctly
   • Ensure all 7 projects pass (chromium, firefox, webkit, mobile devices)

3. Fix issues as discovered

   • If tests reveal component bugs, fix them
   • If accessibility issues found, resolve them
   • Update design tokens if color contrast fails

4. Document as I go

   • Update test coverage tracking
   • Document any deviations from plan
   • Note any new issues discovered

---

Plan Status: Approved - Ready for autonomous implementation Expected Duration: 4-5 weeks Next Action: Begin Phase 1 - Infrastructure Completion