# Lighthouse Testing Guide

This guide explains how to test Lighthouse performance scores locally and achieve 100% scores across all categories.

## Prerequisites

1. Install dependencies:
   ```bash
   npm install
   # or
   pnpm install
   ```

2. Ensure Chrome/Chromium is installed (required for Lighthouse CLI)

## Running Lighthouse Tests

### Test Production Build (Recommended)

This is the most accurate way to test Lighthouse scores, as it tests the actual production-optimized bundle:

```bash
npm run lighthouse:build
```

This command will:
1. Build the production bundle (`next build`)
2. Start the production server (`next start`)
3. Run Lighthouse tests on multiple pages
4. Display scores and metrics
5. Stop the server automatically

### Test Dev Server (Less Accurate)

For quick testing during development (less accurate scores):

```bash
npm run lighthouse:dev
```

**Note:** Dev server scores are typically lower than production scores due to unoptimized code and development overhead.

## Understanding the Results

### Score Categories

Lighthouse tests four main categories, each scored 0-100:

- **Performance**: Measures page load speed and Core Web Vitals
- **Accessibility**: Checks for accessibility best practices
- **Best Practices**: Validates modern web development practices
- **SEO**: Evaluates search engine optimization

### Core Web Vitals

The script also reports these critical metrics:

- **FCP (First Contentful Paint)**: Time until first content appears (target: < 1.8s)
- **LCP (Largest Contentful Paint)**: Time until main content loads (target: < 2.5s)
- **CLS (Cumulative Layout Shift)**: Visual stability measure (target: < 0.1)
- **TBT (Total Blocking Time)**: Time page is blocked from interaction (target: < 200ms)
- **SI (Speed Index)**: How quickly content is visually displayed (target: < 3.4s)

### Target Scores

For 100% scores, all categories must achieve:
- Performance: 100/100
- Accessibility: 100/100
- Best Practices: 100/100
- SEO: 100/100

## Performance Optimizations Implemented

### Image Optimization

- Next.js Image optimization enabled (`unoptimized: false`)
- Automatic WebP/AVIF format conversion
- Responsive image sizes
- Proper width/height attributes to prevent layout shift
- Lazy loading for below-the-fold images

### Third-Party Scripts

- LeadConnector script loaded with `afterInteractive` strategy
- Resource hints (preconnect/dns-prefetch) for external domains
- Scripts don't block initial page render

### Caching Headers

- Static assets cached for 1 year
- Images cached with immutable flag
- Fonts cached for optimal performance

### Bundle Optimization

- Code splitting enabled
- Tree shaking for unused code
- Bundle analyzer available (`npm run analyze`)

## Troubleshooting

### Low Performance Scores

1. **Check image optimization**: Ensure images are using Next.js Image component
2. **Verify production build**: Always test production builds, not dev server
3. **Check bundle size**: Run `npm run analyze` to identify large dependencies
4. **Review third-party scripts**: Ensure they're loaded asynchronously

### Images Not Optimizing

If images aren't being optimized:
- Ensure `unoptimized: false` in `next.config.mjs`
- Check that images are using Next.js `Image` component, not `<img>` tags
- Verify image domains are in `remotePatterns` if using external images

### Layout Shift Issues

- Ensure all images have explicit `width` and `height` attributes
- Use `fill` prop with aspect-ratio containers for responsive images
- Avoid dynamic content that changes layout after load

## Continuous Integration

The `.lighthouserc.js` file is configured for Lighthouse CI. To use it:

1. Install Lighthouse CI:
   ```bash
   npm install -g @lhci/cli
   ```

2. Run CI tests:
   ```bash
   npm run lighthouse:ci
   ```

## Best Practices

1. **Always test production builds**: Dev server scores are not representative
2. **Test multiple pages**: Different pages may have different performance characteristics
3. **Monitor Core Web Vitals**: These directly impact user experience and SEO
4. **Regular testing**: Run Lighthouse tests before deploying major changes
5. **Bundle analysis**: Regularly check bundle size with `npm run analyze`

## Additional Resources

- [Lighthouse Documentation](https://developers.google.com/web/tools/lighthouse)
- [Next.js Image Optimization](https://nextjs.org/docs/app/api-reference/components/image)
- [Core Web Vitals](https://web.dev/vitals/)
- [Web Performance Best Practices](https://web.dev/performance/)