CSS 디버깅과 시각적 회귀 테스트

CSS는 선언적 언어라서 오류가 있어도 브라우저가 조용히 무시합니다. 잘못된 값은 그냥 건너뛰고, z-index 충돌은 런타임 예외를 던지지 않습니다. 그 결과 문제를 재현하기 어렵고, 고쳤다고 생각했는데 다른 곳이 망가지는 일이 반복됩니다. 이 레슨에서는 "느낌으로 고치는" 방식에서 벗어나 도구와 자동화로 스타일 문제를 측정하고, 진단하고, 검증하는 방법론을 다룹니다.

입문편에서 CSS 속성의 사용법을 배웠다면, 이제는 그 스타일이 왜 적용되지 않는지, 어떤 조건에서 레이아웃이 무너지는지, 배포 후 UI가 달라졌는지를 체계적으로 추적하는 역량이 필요합니다.

학습 목표

• DevTools의 레이아웃·계산된 스타일·캐스케이드 패널을 심화 활용하여 스타일 충돌을 추적한다.
• 리플로우·페인트 플래싱과 Performance 패널로 렌더링 병목을 정량적으로 진단한다.
• 쌓임 맥락(stacking context) 트리를 해석하여 z-index 문제를 구조적으로 해결한다.
• Playwright + Percy 기반 시각적 회귀 테스트를 CI에 도입하여 UI 변경을 자동 감지한다.
• stylelint와 미사용 스타일 탐지 도구로 코드베이스를 정적 분석한다.

DevTools 레이아웃·계산된 스타일·캐스케이드 패널 심화

계산된 스타일(Computed) 패널

Elements 패널 오른쪽의 Computed 탭은 브라우저가 캐스케이드를 모두 처리한 후 최종적으로 적용한 값을 보여줍니다. 여기서 "상속", "초기값", "사용자 에이전트 스타일시트" 여부까지 확인할 수 있습니다.

특히 margin, padding, width 같은 박스 모델 값이 기대와 다를 때 Computed 탭을 먼저 봐야 합니다. 속성 옆의 삼각형을 펼치면 어떤 규칙이 해당 값을 결정했는지 소스 위치까지 표시됩니다.

💡 TIP "Show all" 체크박스를 켜면 명시적으로 설정하지 않은 속성(상속·초기값)도 모두 나타납니다. 이를 통해 font-size가 어디서 내려왔는지 상속 체인을 빠르게 추적할 수 있습니다.

Styles 패널의 캐스케이드 읽기

Styles 탭에서 취소선이 그어진 규칙은 더 높은 우선순위 규칙에 의해 덮어쓰인 것입니다. 그러나 왜 덮어쓰였는지 이해하려면 명시도(specificity) 숫자를 직접 계산해야 합니다. Chrome DevTools는 각 선택자 옆에 명시도 힌트를 제공합니다. 선택자 위에 마우스를 올리면 (0, 2, 1) 형태로 표시됩니다.

/* ❌ 왜 이 규칙이 무시되는지 찾기 어려운 경우 */
.card .title {
  color: red; /* (0,2,0) — 취소선 표시 */
}

/* ✅ 이 규칙이 이긴다 */
#app .card .title {
  color: blue; /* (1,2,0) — id 가중치 때문에 우선순위가 높음 */
}

캐스케이드 레이어(@layer)를 사용하는 프로젝트라면 Styles 탭에서 레이어 이름이 규칙 앞에 표시됩니다. 레이어 순서와 명시도를 함께 고려해야 합니다.

레이아웃 패널 — Flexbox·Grid 오버레이

Elements 패널에서 flex 또는 grid 컨테이너를 선택하면 Styles 탭 왼쪽에 작은 뱃지가 나타납니다. 이 뱃지를 클릭하면 뷰포트에 정렬 가이드라인 오버레이가 그려집니다. 각 셀과 트랙의 크기, gap, 아이템이 어디에 배치됐는지를 시각적으로 확인할 수 있어, 레이아웃이 의도대로 계산됐는지 바로 판단할 수 있습니다.

⚠️ 주의 Grid의 auto 트랙 크기가 예상과 다를 때는 오버레이에서 실제 px 값을 확인하는 것이 가장 빠릅니다. Computed 탭의 grid-template-rows/grid-template-columns는 계산 후 값을 보여줍니다.

리플로우·페인트 플래싱과 Performance 패널로 병목 진단

렌더링 플래그 켜기

Chrome DevTools의 Rendering 탭(세 점 메뉴 → More tools → Rendering)에서 다음 두 옵션을 활성화하면 렌더링 비용을 시각적으로 파악할 수 있습니다.

화면 전체가 녹색으로 번쩍이면 스크롤할 때마다 전체 재페인트가 일어나고 있다는 신호입니다. position: fixed 요소나 background-attachment: fixed가 원인인 경우가 많습니다.

Performance 패널로 리플로우 추적

Performance 탭에서 녹화를 시작하고 문제가 되는 인터랙션을 수행하면 타임라인에 Recalculate Style, Layout, Paint, Composite 단계가 나타납니다.

• Layout 블록이 크다면 강제 동기 레이아웃(forced synchronous layout)이 발생하고 있을 가능성이 높습니다.
• 하단 Summary 탭에서 각 단계에 소요된 시간을 밀리초로 확인합니다.

// ❌ 강제 동기 레이아웃 — 읽기와 쓰기가 번갈아 일어남
elements.forEach(el => {
  const h = el.offsetHeight;  // 읽기 → 브라우저가 강제로 Layout 실행
  el.style.height = h + 10 + 'px'; // 쓰기
});

// ✅ 읽기를 먼저 모은 뒤 쓰기를 일괄 처리
const heights = elements.map(el => el.offsetHeight); // 읽기 일괄
elements.forEach((el, i) => {
  el.style.height = heights[i] + 10 + 'px'; // 쓰기 일괄
});

💡 TIP will-change: transform을 선택적으로 적용하면 해당 요소를 별도의 컴포지터 레이어로 분리해 Paint 비용을 줄일 수 있지만, 과도하게 적용하면 메모리를 낭비합니다. Performance 패널에서 Layers 뷰를 열어 레이어 수를 모니터링하세요.

쌓임 맥락(Stacking Context) 디버깅과 z-index 문제 추적

왜 z-index가 말을 안 듣는가

z-index가 높은 숫자임에도 불구하고 다른 요소 뒤에 숨는 원인은 거의 항상 쌓임 맥락의 격리 때문입니다. 쌓임 맥락을 새로 만드는 조건은 생각보다 많습니다.

/* ❌ .modal이 .parent 뒤에 숨는 이유 */
.parent {
  transform: translateX(0); /* 쌓임 맥락 생성! */
  /* .modal은 이 맥락 안에 갇힘 */
}

.modal {
  position: fixed;
  z-index: 9999; /* 소용없음 — 부모 맥락 안에서만 경쟁 */
}

/* ✅ 해결: .modal을 쌓임 맥락 바깥으로 이동 */
/* React Portal이나 <Teleport>(Vue)로 document.body 직계 자식으로 렌더링 */

DevTools로 쌓임 맥락 트리 파악하기

Chrome DevTools Elements 패널에서 요소를 선택한 뒤 Computed 탭에서 z-index 값을 확인합니다. 하지만 어떤 조상이 새로운 맥락을 만드는지 파악하기 위해서는 조상 요소를 하나씩 올라가며 위의 표에 해당하는 속성이 적용됐는지 확인해야 합니다.

브라우저 확장 CSS Stacking Context Inspector를 설치하면 페이지 전체의 쌓임 맥락 트리를 시각화해서 볼 수 있습니다. 복잡한 컴포넌트 계층 구조에서 z-index 충돌을 빠르게 추적하는 데 유용합니다.

⚠️ 주의 isolation: isolate를 의도적으로 사용하면 컴포넌트 내부의 z-index 경쟁을 외부와 격리할 수 있습니다. 디자인 시스템에서 Modal, Tooltip 같은 오버레이 컴포넌트의 z-index 범위를 관리할 때 유용한 패턴입니다.

/* ✅ 컴포넌트 내부 z-index를 외부와 격리 */
.card {
  isolation: isolate;
}

.card__badge {
  position: absolute;
  z-index: 1; /* 카드 내부에서만 경쟁, 외부 Modal 등에 영향 없음 */
}

시각적 회귀 테스트(Playwright + Percy) 도입

왜 스냅샷 비교인가

단위 테스트와 통합 테스트는 로직을 검증하지만, 스타일 변경이 UI를 의도치 않게 바꿨는지는 감지하지 못합니다. 시각적 회귀 테스트는 렌더링된 화면을 픽셀 또는 퍼셉션 수준에서 기준 스냅샷과 비교하여 차이를 자동으로 발견합니다.

Percy는 스냅샷을 클라우드에 저장하고 PR마다 시각적 diff를 생성하는 서비스입니다. Playwright와 함께 사용하면 실제 브라우저에서 렌더링한 결과를 비교합니다.

설치 및 기본 설정

npm install --save-dev @playwright/test @percy/cli @percy/playwright
npx playwright install chromium

// playwright.config.js
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  use: {
    baseURL: 'http://localhost:3000',
    headless: true,
  },
});

// tests/visual.spec.js
import { test } from '@playwright/test';
import percySnapshot from '@percy/playwright';

test('홈 페이지 시각적 회귀', async ({ page }) => {
  await page.goto('/');
  // 동적 요소가 로드될 때까지 대기
  await page.waitForSelector('.hero-banner', { state: 'visible' });
  await percySnapshot(page, 'Home Page');
});

test('카드 컴포넌트 — 호버 상태', async ({ page }) => {
  await page.goto('/components/card');
  const card = page.locator('.card').first();
  await card.hover();
  await percySnapshot(page, 'Card - Hover State');
});

# CI에서 실행 (PERCY_TOKEN 환경 변수 필요)
PERCY_TOKEN=<token> npx percy exec -- playwright test

기준 스냅샷 관리 전략

처음 실행 시 Percy는 현재 렌더링을 기준(baseline)으로 저장합니다. 이후 PR에서 변경이 감지되면 팀원이 시각적 diff를 리뷰하고 승인 또는 거절합니다. 의도한 변경은 승인(approve)하면 새로운 기준이 됩니다.

💡 TIP 애니메이션이 있는 요소는 스냅샷 직전에 CSS 애니메이션을 비활성화해야 안정적인 비교가 가능합니다.

// 스냅샷 전 모든 애니메이션 정지
test.beforeEach(async ({ page }) => {
  await page.addStyleTag({
    content: `
      *, *::before, *::after {
        animation-duration: 0s !important;
        transition-duration: 0s !important;
      }
    `,
  });
});

Playwright 자체의 toHaveScreenshot() API를 사용하면 Percy 없이도 로컬 파일 기반의 스냅샷 비교가 가능합니다. Percy는 CI 통합과 팀 리뷰 워크플로우가 필요할 때 추가합니다.

// Percy 없이 Playwright 기본 스냅샷 비교
test('버튼 컴포넌트 스냅샷', async ({ page }) => {
  await page.goto('/components/button');
  await expect(page.locator('.btn-primary')).toHaveScreenshot('btn-primary.png');
});

CSS 린팅(stylelint)과 사용하지 않는 스타일 탐지

stylelint 설정

stylelint는 CSS(및 SCSS, Less, CSS-in-JS)의 정적 분석 도구입니다. 팀 컨벤션을 강제하고, 유효하지 않은 값이나 위험한 패턴을 미리 잡습니다.

npm install --save-dev stylelint stylelint-config-standard

// .stylelintrc.json
{
  "extends": ["stylelint-config-standard"],
  "rules": {
    "color-no-invalid-hex": true,
    "declaration-block-no-duplicate-properties": true,
    "selector-max-id": 0,
    "declaration-no-important": true,
    "unit-allowed-list": ["px", "rem", "em", "%", "vw", "vh", "svh", "dvh", "fr", "deg", "s", "ms"],
    "custom-property-pattern": "^([a-z][a-z0-9]*)(-[a-z0-9]+)*$",
    "alpha-value-notation": "percentage"
  }
}

# 단일 파일 린팅
npx stylelint "src/**/*.css"

# 자동 수정 가능한 항목 수정
npx stylelint "src/**/*.css" --fix

주요 규칙을 팀 상황에 맞게 조정하는 것이 중요합니다. 예를 들어 declaration-no-important는 서드파티 스타일을 오버라이드해야 하는 경우에는 특정 파일에서 비활성화할 수 있습니다.

/* stylelint-disable declaration-no-important */
.override-third-party {
  margin: 0 !important;
}
/* stylelint-enable declaration-no-important */

사용하지 않는 스타일 탐지

빌드가 거듭될수록 실제로 사용되지 않는 CSS가 누적됩니다. PurgeCSS는 HTML·JS 파일을 분석하여 사용된 선택자만 남기고 나머지를 제거합니다.

npm install --save-dev purgecss

// purgecss.config.js
export default {
  content: ['./src/**/*.{html,js,jsx,ts,tsx,vue}'],
  css: ['./dist/styles.css'],
  output: './dist/purged/',
  safelist: [
    // 동적으로 생성되는 클래스는 안전 목록에 추가
    /^is-/,
    /^has-/,
    'active',
    'open',
  ],
};

npx purgecss --config purgecss.config.js

⚠️ 주의 PurgeCSS는 정적 분석이라서 JavaScript에서 동적으로 생성하는 클래스명(예: `btn-${color}`)을 감지하지 못합니다. 이런 클래스는 반드시 safelist에 패턴으로 등록해야 합니다.

Chrome DevTools의 Coverage 탭을 활용하면 로컬에서 어떤 CSS 규칙이 사용됐는지 실시간으로 확인할 수 있습니다. 세 점 메뉴 → More tools → Coverage에서 녹화 후 페이지를 탐색하면, 각 파일별로 사용된 규칙의 비율이 표시됩니다.

크로스 브라우저 차이 진단과 폴백 검증

@supports를 이용한 폴백 구조

새로운 CSS 기능을 사용할 때는 지원하지 않는 브라우저를 위한 폴백을 함께 제공해야 합니다. @supports는 브라우저가 특정 속성·값을 지원하는지를 런타임에 확인하는 조건문입니다.

/* ✅ container queries 폴백 예시 */
.card-grid {
  /* 폴백: 미디어 쿼리 기반 */
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
}

@supports (container-type: inline-size) {
  .card-wrapper {
    container-type: inline-size;
    container-name: card;
  }

  @container card (min-width: 400px) {
    .card {
      grid-template-columns: 160px 1fr;
    }
  }
}

BrowserStack / Playwright 멀티 브라우저 테스트

Playwright는 Chromium, Firefox, WebKit을 동시에 테스트하는 기능을 기본으로 제공합니다. 이를 활용하면 CSS 동작 차이를 CI에서 조기에 발견할 수 있습니다.

// playwright.config.js
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox',  use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit',   use: { ...devices['Desktop Safari'] } },
    { name: 'mobile',   use: { ...devices['iPhone 14'] } },
  ],
});

// tests/cross-browser.spec.js
import { test, expect } from '@playwright/test';

test('그리드 레이아웃이 모든 브라우저에서 동일하게 렌더링된다', async ({ page, browserName }) => {
  await page.goto('/layout-demo');
  const grid = page.locator('.main-grid');

  // 각 브라우저별로 스냅샷을 별도 파일로 저장
  await expect(grid).toHaveScreenshot(`grid-${browserName}.png`);
});

Can I Use와 MDN 호환성 데이터 활용

stylelint 플러그인 stylelint-no-unsupported-browser-features는 Browserslist와 caniuse 데이터를 연동하여, 프로젝트의 지원 대상 브라우저에서 사용할 수 없는 속성을 경고합니다.

npm install --save-dev stylelint-no-unsupported-browser-features

// .stylelintrc.json
{
  "plugins": ["stylelint-no-unsupported-browser-features"],
  "rules": {
    "plugin/no-unsupported-browser-features": [
      true,
      {
        "severity": "warning",
        "ignore": ["css-transitions", "css-animations"]
      }
    ]
  }
}

// .browserslistrc
last 2 Chrome versions
last 2 Firefox versions
last 2 Safari versions
last 2 Edge versions

💡 TIP Browserslist를 package.json의 "browserslist" 필드에 정의하면 stylelint, Autoprefixer, PurgeCSS가 공통 설정을 공유합니다. 브라우저 지원 범위를 한 곳에서 관리할 수 있습니다.

요약

• DevTools의 Computed 탭과 캐스케이드 읽기로 스타일이 어디서 결정됐는지 정확하게 추적한다. Styles 탭의 취소선과 명시도 힌트를 적극 활용한다.
• Paint flashing과 Performance 패널의 타임라인으로 리플로우·페인트 병목을 정량적으로 측정하고, 읽기·쓰기 분리 패턴으로 강제 동기 레이아웃을 제거한다.
• 쌓임 맥락은 transform, opacity, filter 등 다양한 속성이 생성하며, z-index 문제는 조상 요소의 맥락 트리를 파악해야 근본적으로 해결된다.
• Playwright + Percy로 UI 변경 시 시각적 회귀를 자동 감지하고, CI 파이프라인에 통합해 릴리즈 전에 확인한다.
• stylelint로 정적 분석을 자동화하고, PurgeCSS와 Coverage 탭으로 사용하지 않는 CSS를 탐지·제거한다.
• **@supports**로 점진적 향상 폴백을 구조화하고, Playwright의 멀티 브라우저 프로젝트 설정으로 크로스 브라우저 차이를 CI에서 조기에 발견한다.

연습문제

1. 다음 상황에서 .tooltip이 .modal 위에 표시되지 않는 원인을 진단하고 수정하세요. .modal은 position: fixed; z-index: 100이고, .tooltip은 position: absolute; z-index: 9999입니다. .tooltip의 부모 .modal-body에는 transform: translateY(-10px)이 적용되어 있습니다.

   힌트 쌓임 맥락을 생성하는 CSS 속성 표를 다시 확인하세요.

2. Performance 패널에서 스크롤 시 Layout 단계가 매 프레임마다 실행되는 것을 발견했습니다. 아래 코드를 강제 동기 레이아웃이 발생하지 않도록 리팩터링하세요.

   const items = document.querySelectorAll('.item');
   items.forEach(item => {
     const width = item.offsetWidth;
     item.style.width = width * 1.2 + 'px';
   });
   

   JavaScript▶ 실행

   힌트 읽기 작업과 쓰기 작업을 분리하세요.

3. Playwright로 .hero-section 컴포넌트의 시각적 회귀 테스트를 작성하세요. 단, 애니메이션이 있어 스냅샷이 불안정하므로 캡처 전에 모든 트랜지션과 애니메이션을 비활성화해야 합니다.

   힌트 page.addStyleTag()로 테스트 전용 CSS를 주입할 수 있습니다.

4. 아래 stylelint 설정이 경고를 발생시키지 않도록 문제가 있는 CSS를 수정하세요.

   {
     "rules": {
       "declaration-no-important": true,
       "selector-max-id": 0,
       "color-no-invalid-hex": true
     }
   }
   

   #main-header {
     background-color: #gghhii;
     font-size: 16px !important;
   }
   

   힌트 ID 선택자 대신 클래스를 사용하고, 잘못된 hex 값과 !important를 제거하세요.