416 lines
13 KiB
YAML
416 lines
13 KiB
YAML
# Error Pattern Recovery Database
|
|
# Maps common error patterns to diagnosis and recovery steps
|
|
|
|
# This file is used for:
|
|
# 1. Pre-flight health checks - detect errors before running full test suite
|
|
# 2. Test failure analysis - provide actionable fixes when tests fail
|
|
# 3. User guidance - self-service troubleshooting
|
|
|
|
# ========== CSS & STYLING ERRORS ==========
|
|
css_errors:
|
|
tailwind_v4_syntax_mismatch:
|
|
pattern: "Cannot apply unknown utility class"
|
|
alternative_patterns:
|
|
- "Utilities must be known at build time"
|
|
- "Unknown utility class"
|
|
|
|
diagnosis: "Tailwind CSS v4 detected but v3 syntax used in CSS file"
|
|
|
|
severity: "critical"
|
|
category: "configuration"
|
|
|
|
root_cause: |
|
|
Tailwind CSS v4 changed from @tailwind directives to @import syntax.
|
|
Your CSS file likely still uses the old @tailwind directives.
|
|
|
|
detection_method: "console_error"
|
|
|
|
recovery_steps:
|
|
- step: "Identify your main CSS file"
|
|
details: "Usually src/index.css, src/App.css, or src/globals.css"
|
|
|
|
- step: "Update CSS directives"
|
|
from: |
|
|
@tailwind base;
|
|
@tailwind components;
|
|
@tailwind utilities;
|
|
to: |
|
|
@import "tailwindcss";
|
|
files_to_check:
|
|
- "src/index.css"
|
|
- "src/App.css"
|
|
- "src/globals.css"
|
|
- "src/styles/globals.css"
|
|
|
|
- step: "Update PostCSS configuration"
|
|
from: |
|
|
plugins: {
|
|
tailwindcss: {},
|
|
autoprefixer: {},
|
|
}
|
|
to: |
|
|
plugins: {
|
|
'@tailwindcss/postcss': {},
|
|
autoprefixer: {},
|
|
}
|
|
files_to_check:
|
|
- "postcss.config.js"
|
|
- "postcss.config.cjs"
|
|
- "postcss.config.mjs"
|
|
|
|
- step: "Restart dev server"
|
|
command: "npm run dev"
|
|
reason: "CSS changes require server restart"
|
|
|
|
- step: "Clear browser cache and reload"
|
|
details: "Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)"
|
|
|
|
prevention: |
|
|
The skill now detects Tailwind version and uses appropriate templates.
|
|
This error should not occur in new setups.
|
|
|
|
documentation: "https://tailwindcss.com/docs/upgrade-guide"
|
|
|
|
related_errors:
|
|
- "postcss_plugin_not_found"
|
|
|
|
postcss_plugin_not_found:
|
|
pattern: "Plugin tailwindcss not found"
|
|
alternative_patterns:
|
|
- "Cannot find module 'tailwindcss'"
|
|
- "postcss plugin tailwindcss not found"
|
|
|
|
diagnosis: "PostCSS configuration uses old Tailwind v3 plugin name with Tailwind v4"
|
|
|
|
severity: "critical"
|
|
category: "configuration"
|
|
|
|
root_cause: |
|
|
Tailwind CSS v4 renamed its PostCSS plugin from 'tailwindcss' to '@tailwindcss/postcss'.
|
|
Your postcss.config.js still references the old plugin name.
|
|
|
|
recovery_steps:
|
|
- step: "Update postcss.config.js"
|
|
from: |
|
|
export default {
|
|
plugins: {
|
|
tailwindcss: {},
|
|
autoprefixer: {},
|
|
},
|
|
};
|
|
to: |
|
|
export default {
|
|
plugins: {
|
|
'@tailwindcss/postcss': {},
|
|
autoprefixer: {},
|
|
},
|
|
};
|
|
file: "postcss.config.js"
|
|
|
|
- step: "Verify @tailwindcss/postcss is installed"
|
|
command: "npm list @tailwindcss/postcss"
|
|
if_not_installed: "npm install -D @tailwindcss/postcss"
|
|
|
|
- step: "Restart dev server"
|
|
command: "npm run dev"
|
|
|
|
documentation: "https://tailwindcss.com/docs/upgrade-guide#migrating-from-v3"
|
|
|
|
# ========== ACCESSIBILITY ERRORS ==========
|
|
accessibility_errors:
|
|
heading_hierarchy_violation:
|
|
pattern: "heading-order - Heading levels should only increase by one"
|
|
alternative_patterns:
|
|
- "Heading levels should increase by one"
|
|
- "heading-order violation"
|
|
|
|
diagnosis: "WCAG heading hierarchy violation - skipped heading levels"
|
|
|
|
severity: "moderate"
|
|
category: "accessibility"
|
|
|
|
root_cause: |
|
|
HTML heading elements (h1-h6) must follow logical order without skipping levels.
|
|
For example: h1 → h2 → h3 is correct, but h1 → h3 (skipping h2) is incorrect.
|
|
|
|
recovery_steps:
|
|
- step: "Locate the problematic heading in test output"
|
|
details: "Playwright accessibility tests will show file and line number"
|
|
|
|
- step: "Check heading hierarchy in that component"
|
|
example: |
|
|
❌ Bad:
|
|
<h1>Page Title</h1>
|
|
<h3>Section</h3> <!-- Skips h2 -->
|
|
|
|
✅ Good:
|
|
<h1>Page Title</h1>
|
|
<h2>Section</h2>
|
|
|
|
- step: "Fix heading levels to follow order"
|
|
details: "Ensure each heading is only one level deeper than its parent"
|
|
|
|
- step: "Re-run accessibility tests"
|
|
command: "npm run test:e2e -- accessibility.spec.ts"
|
|
|
|
prevention: |
|
|
Always outline content structure before implementing:
|
|
- Page title: h1 (only one per page)
|
|
- Main sections: h2
|
|
- Subsections: h3
|
|
- Sub-subsections: h4
|
|
|
|
documentation: "https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html"
|
|
|
|
missing_form_labels:
|
|
pattern: "Form elements must have labels"
|
|
alternative_patterns:
|
|
- "label - Form elements must have labels"
|
|
- "Inputs must have associated labels"
|
|
|
|
diagnosis: "Form input missing associated label element"
|
|
|
|
severity: "high"
|
|
category: "accessibility"
|
|
|
|
root_cause: |
|
|
Every form input must have an associated <label> element for screen reader users.
|
|
Placeholder text alone is NOT sufficient.
|
|
|
|
recovery_steps:
|
|
- step: "Add label element to input"
|
|
from: |
|
|
<input type="email" placeholder="Email" />
|
|
to: |
|
|
<label htmlFor="email">Email Address</label>
|
|
<input id="email" type="email" placeholder="Email" />
|
|
|
|
- step: "Alternative: Use aria-label if visual label not desired"
|
|
example: |
|
|
<input
|
|
type="search"
|
|
aria-label="Search"
|
|
placeholder="Search..."
|
|
/>
|
|
|
|
- step: "Ensure label and input are properly associated"
|
|
details: "Use 'htmlFor' attribute matching input 'id'"
|
|
|
|
- step: "Re-run accessibility tests"
|
|
command: "npm run test:e2e -- accessibility.spec.ts"
|
|
|
|
documentation: "https://www.w3.org/WAI/tutorials/forms/labels/"
|
|
|
|
insufficient_color_contrast:
|
|
pattern: "color-contrast - Elements must meet minimum color contrast ratio"
|
|
alternative_patterns:
|
|
- "color contrast ratio"
|
|
- "contrast ratio"
|
|
|
|
diagnosis: "Text or UI element has insufficient color contrast (WCAG 2.1 AA violation)"
|
|
|
|
severity: "high"
|
|
category: "accessibility"
|
|
|
|
root_cause: |
|
|
WCAG 2.1 AA requires:
|
|
- Normal text: 4.5:1 contrast ratio
|
|
- Large text (18pt+ or 14pt+ bold): 3:1 contrast ratio
|
|
- UI components: 3:1 contrast ratio
|
|
|
|
recovery_steps:
|
|
- step: "Identify low-contrast element from test output"
|
|
details: "Test results show which element and current ratio"
|
|
|
|
- step: "Use WebAIM contrast checker"
|
|
url: "https://webaim.org/resources/contrastchecker/"
|
|
details: "Test current colors and find compliant alternatives"
|
|
|
|
- step: "Update color values"
|
|
example: |
|
|
❌ Bad: #AAAAAA on #FFFFFF (2.6:1 ratio)
|
|
✅ Good: #595959 on #FFFFFF (7:1 ratio)
|
|
|
|
For Tailwind:
|
|
❌ text-gray-400 → ✅ text-gray-700
|
|
|
|
- step: "Re-run accessibility tests"
|
|
command: "npm run test:e2e -- accessibility.spec.ts"
|
|
|
|
prevention: |
|
|
Use established color palettes with pre-tested contrast ratios.
|
|
Tailwind's default palette (500+ for text) generally meets WCAG AA.
|
|
|
|
documentation: "https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html"
|
|
|
|
# ========== BUILD & CONFIGURATION ERRORS ==========
|
|
build_errors:
|
|
vite_port_in_use:
|
|
pattern: "Port 5173 is in use"
|
|
alternative_patterns:
|
|
- "EADDRINUSE"
|
|
- "address already in use"
|
|
|
|
diagnosis: "Vite dev server port already in use by another process"
|
|
|
|
severity: "moderate"
|
|
category: "environment"
|
|
|
|
recovery_steps:
|
|
- step: "Find process using port 5173"
|
|
command: "lsof -i :5173"
|
|
platforms: ["mac", "linux"]
|
|
|
|
- step: "Kill the process"
|
|
command: "kill -9 <PID>"
|
|
details: "Replace <PID> with process ID from previous command"
|
|
|
|
- step: "Alternative: Use different port"
|
|
details: "Add to vite.config.ts:"
|
|
config: |
|
|
server: {
|
|
port: 3000
|
|
}
|
|
|
|
- step: "Restart dev server"
|
|
command: "npm run dev"
|
|
|
|
playwright_browsers_not_installed:
|
|
pattern: "Executable doesn't exist"
|
|
alternative_patterns:
|
|
- "browserType.launch: Executable doesn't exist"
|
|
- "Browser not found"
|
|
|
|
diagnosis: "Playwright browser binaries not installed"
|
|
|
|
severity: "critical"
|
|
category: "installation"
|
|
|
|
recovery_steps:
|
|
- step: "Install Playwright browsers"
|
|
command: "npx playwright install"
|
|
details: "Downloads Chromium, Firefox, and WebKit"
|
|
|
|
- step: "Install system dependencies (Linux only)"
|
|
command: "npx playwright install-deps"
|
|
platforms: ["linux"]
|
|
|
|
- step: "Verify installation"
|
|
command: "npx playwright test --list"
|
|
expected: "Should list available tests without errors"
|
|
|
|
typescript_strict_errors:
|
|
pattern: "TypeScript strict mode errors"
|
|
alternative_patterns:
|
|
- "TS2345"
|
|
- "TS2322"
|
|
- "Type 'any' is not assignable"
|
|
|
|
diagnosis: "TypeScript strict mode violations in generated code"
|
|
|
|
severity: "moderate"
|
|
category: "type_safety"
|
|
|
|
recovery_steps:
|
|
- step: "Review TypeScript errors in output"
|
|
details: "Each error shows file, line, and type issue"
|
|
|
|
- step: "Add explicit type annotations"
|
|
example: |
|
|
❌ const data = await fetch(url);
|
|
✅ const data: Response = await fetch(url);
|
|
|
|
- step: "Use type assertions cautiously"
|
|
example: |
|
|
const element = page.locator('#id') as Locator;
|
|
|
|
- step: "Fix null/undefined handling"
|
|
example: |
|
|
❌ const text = element.textContent();
|
|
✅ const text = await element.textContent() ?? '';
|
|
|
|
# ========== RESPONSIVE & LAYOUT ERRORS ==========
|
|
layout_errors:
|
|
horizontal_scroll_mobile:
|
|
pattern: "Horizontal scroll detected on mobile viewport"
|
|
|
|
diagnosis: "Content wider than viewport on mobile, causing horizontal scroll"
|
|
|
|
severity: "moderate"
|
|
category: "responsive"
|
|
|
|
root_cause: |
|
|
Fixed-width elements or overflow content exceeds mobile viewport width.
|
|
Common causes: large images, wide tables, fixed px widths.
|
|
|
|
recovery_steps:
|
|
- step: "Identify overflowing element"
|
|
details: "Use browser DevTools → Elements → Computed → scroll width"
|
|
|
|
- step: "Make element responsive"
|
|
example: |
|
|
❌ width: 800px;
|
|
✅ max-width: 100%;
|
|
|
|
❌ className="w-[800px]"
|
|
✅ className="w-full max-w-screen-lg"
|
|
|
|
- step: "Add overflow handling"
|
|
example: |
|
|
className="overflow-x-auto" // For tables
|
|
className="overflow-hidden" // For containers
|
|
|
|
- step: "Test on mobile viewport"
|
|
command: "npm run test:e2e -- --project=mobile-chrome"
|
|
|
|
# ========== RECOVERY STRATEGIES ==========
|
|
recovery_strategies:
|
|
incremental_fix:
|
|
description: "Fix errors one at a time, test after each fix"
|
|
when_to_use: "Multiple related errors"
|
|
steps:
|
|
- "Fix highest severity error first"
|
|
- "Run tests to verify fix"
|
|
- "Move to next error"
|
|
- "Repeat until all errors resolved"
|
|
|
|
clean_slate:
|
|
description: "Remove generated files and regenerate"
|
|
when_to_use: "Configuration completely broken"
|
|
steps:
|
|
- "Delete generated playwright.config.ts"
|
|
- "Delete tests/ directory"
|
|
- "Clear node_modules/.cache/"
|
|
- "Re-run skill"
|
|
|
|
version_rollback:
|
|
description: "Downgrade to last working version"
|
|
when_to_use: "Breaking change in newly installed package"
|
|
steps:
|
|
- "Check package.json for recently updated packages"
|
|
- "Install previous version: npm install package@previous-version"
|
|
- "Lock version in package.json"
|
|
- "Test to confirm working"
|
|
|
|
# ========== ERROR SEVERITY LEVELS ==========
|
|
severity_definitions:
|
|
critical:
|
|
impact: "App won't build or run"
|
|
response_time: "Fix immediately"
|
|
examples: ["Syntax errors", "Missing dependencies", "Config errors"]
|
|
|
|
high:
|
|
impact: "Major functionality broken"
|
|
response_time: "Fix within hours"
|
|
examples: ["Accessibility violations", "Failed test cases", "Type errors"]
|
|
|
|
moderate:
|
|
impact: "Reduced usability or performance"
|
|
response_time: "Fix within days"
|
|
examples: ["Layout issues", "Minor accessibility", "Warnings"]
|
|
|
|
low:
|
|
impact: "Cosmetic or minor issues"
|
|
response_time: "Fix when convenient"
|
|
examples: ["Code style", "Documentation", "Minor visual bugs"]
|