테스트 데이터 부재 해결 — API Fixture 자동화 설계와 실패 단계별 자동 트리아지

┌──────────────────┐   ┌────────────────┐   ┌────────────────┐   ┌──────────────┐   ┌────────────┐
│ 1. Pre-condition │ → │ 2. Fixture Call│ → │ 3. Context     │ → │ 4. E2E 실행   │ → │ 5. Clean-up│
│    추출           │   │  API로 상태 생성 │   │    Inject      │   │  UI 시나리오   │   │  정리·취소  │
│ TC 메타데이터의   │   │  주문·쿠폰·계정  │   │  생성된 ID·토큰 │   │  화면 조작과   │   │  생성한 것만 │
│ fixture_payload  │   │  (100% API)     │   │  을 테스트에 전달│   │  단언          │   │  되돌림      │
└──────────────────┘   └────────────────┘   └────────────────┘   └──────────────┘   └────────────┘
         │                      │                                       │
         │                      └─ 실패(4xx/5xx) → [환경 문제]            └─ 실패 → [셀렉터 오류] 또는 [실제 버그]

// fixtures/api-client.ts
import { APIRequestContext, APIResponse } from '@playwright/test';
 
export class FixtureApiError extends Error {
  constructor(
    readonly step: string,
    readonly status: number,
    readonly body: string,
  ) {
    super(`[fixture:${step}] HTTP ${status} — ${body.slice(0, 300)}`);
    this.name = 'FixtureApiError';
  }
}
 
async function ensureOk(step: string, res: APIResponse): Promise<APIResponse> {
  if (!res.ok()) throw new FixtureApiError(step, res.status(), await res.text());
  return res;
}
 
export interface CreateOrderPayload {
  productSku: string;
  quantity: number;
  status: 'PAID' | 'SHIPPING' | 'DELIVERED';
  couponCode?: string;
}
 
export interface CreatedOrder {
  orderId: string;
  orderNo: string;
  status: string;
}
 
export class FixtureApi {
  constructor(
    private readonly api: APIRequestContext,
    private readonly runTag: string,          // 멱등성·정리용 식별 접두사
  ) {}
 
  async createOrder(userId: string, payload: CreateOrderPayload): Promise<CreatedOrder> {
    const res = await ensureOk('createOrder', await this.api.post('/qa-fixtures/orders', {
      data: { userId, ...payload, externalRef: `${this.runTag}-order` },
      headers: { 'Idempotency-Key': `${this.runTag}-order` },
    }));
    return res.json();
  }
 
  async cancelOrder(orderId: string): Promise<void> {
    const res = await this.api.post(`/qa-fixtures/orders/${orderId}/cancel`);
    // 이미 정리된 경우(404·409)는 정리 성공으로 본다 — 정리는 멱등해야 한다
    if (!res.ok() && ![404, 409].includes(res.status())) {
      await ensureOk('cancelOrder', res);
    }
  }
 
  async cleanupByTag(): Promise<void> {
    // 테스트가 중간에 죽어 개별 정리를 못 했을 때를 위한 안전망
    await this.api.delete(`/qa-fixtures/resources?tagPrefix=${encodeURIComponent(this.runTag)}`);
  }
}

// fixtures/test.ts
import { test as base, expect, request as pwRequest, APIRequestContext } from '@playwright/test';
import { FixtureApi, CreatedOrder, CreateOrderPayload, FixtureApiError } from './api-client';
 
type FixturePayload = {
  user: 'buyer' | 'vip';
  order?: CreateOrderPayload;
};
 
type TestOptions = {
  fixturePayload: FixturePayload;     // 테스트마다 test.use() 로 지정 — TC 메타데이터에서 옴
};
 
type TestFixtures = {
  runTag: string;
  fixtureApi: FixtureApi;
  preparedOrder: CreatedOrder;
};
 
type WorkerFixtures = {
  serviceApi: APIRequestContext;      // 서비스별 API 토큰을 미리 주입한 컨텍스트
};
 
export const test = base.extend<TestOptions & TestFixtures, WorkerFixtures>({
  fixturePayload: [{ user: 'buyer' }, { option: true }],
 
  // 워커당 한 번: 서비스 API 토큰을 헤더에 주입 (로그인 UI 우회)
  serviceApi: [async ({}, use) => {
    const ctx = await pwRequest.newContext({
      baseURL: process.env.API_BASE_URL,
      extraHTTPHeaders: { Authorization: `Bearer ${process.env.QA_SERVICE_TOKEN}` },
    });
    await use(ctx);
    await ctx.dispose();
  }, { scope: 'worker' }],
 
  // 테스트마다 고유 식별 접두사 — 병렬 실행·재실행에서도 충돌하지 않게
  runTag: async ({}, use, testInfo) => {
    const runId = process.env.CI_RUN_ID ?? 'local';
    await use(`qa-e2e-${runId}-${testInfo.workerIndex}-${testInfo.testId}-r${testInfo.retry}`);
  },
 
  fixtureApi: async ({ serviceApi, runTag }, use) => {
    const api = new FixtureApi(serviceApi, runTag);
    await use(api);
    await api.cleanupByTag();          // 5) 안전망 정리
  },
 
  // 2) Fixture Call → 3) Context Inject → 5) Clean-up
  preparedOrder: async ({ fixtureApi, fixturePayload }, use, testInfo) => {
    if (!fixturePayload.order) throw new Error('fixture_payload.order 가 정의되지 않았습니다');
 
    testInfo.annotations.push({ type: 'phase', description: 'fixture' });
    const userId = testInfo.project.metadata?.users?.[fixturePayload.user] ?? fixturePayload.user;
    const order = await fixtureApi.createOrder(userId, fixturePayload.order);
 
    testInfo.annotations.push({ type: 'phase', description: 'ui' });
    await use(order);                  // 4) 테스트 본문 실행
 
    await fixtureApi.cancelOrder(order.orderId);
  },
});
 
export { expect, FixtureApiError };

// global-setup.ts — 사용자별 로그인 상태를 API 로 만든다 (로그인 UI 를 타지 않음)
import { request, FullConfig } from '@playwright/test';
 
export default async function globalSetup(config: FullConfig) {
  for (const user of ['buyer', 'vip'] as const) {
    const ctx = await request.newContext({ baseURL: process.env.API_BASE_URL });
    const res = await ctx.post('/auth/test-token', {
      data: { account: process.env[`QA_${user.toUpperCase()}_ACCOUNT`] },
      headers: { Authorization: `Bearer ${process.env.QA_SERVICE_TOKEN}` },
    });
    if (!res.ok()) throw new Error(`[fixture:auth] HTTP ${res.status()}`);
    await ctx.storageState({ path: `.auth/${user}.json` });   // 발급된 쿠키를 저장
    await ctx.dispose();
  }
}

// tests/order-shipping.spec.ts
import { test, expect } from '../fixtures/test';
 
test.use({
  storageState: '.auth/buyer.json',
  fixturePayload: {
    user: 'buyer',
    order: { productSku: 'SKU-QA-001', quantity: 2, status: 'SHIPPING' },
  },
});
 
test('배송 중 주문은 상세 화면에서 배송 조회 버튼이 보인다', async ({ page, preparedOrder }) => {
  await page.goto(`/orders/${preparedOrder.orderId}`);
  await expect(page.getByRole('heading', { name: preparedOrder.orderNo })).toBeVisible();
  await expect(page.getByRole('button', { name: '배송 조회' })).toBeVisible();
  await expect(page.getByRole('button', { name: '주문 취소' })).toBeHidden();
});

# testcases/order/TC-ORD-021.yaml
id: TC-ORD-021
title: 배송 중 주문은 상세 화면에서 배송 조회 버튼이 보인다
priority: high
automation:
  spec: tests/order-shipping.spec.ts
fixture_payload:
  user: buyer
  order:
    productSku: SKU-QA-001      # QA 전용 상품 — 재고 무제한, 가격 고정
    quantity: 2
    status: SHIPPING

// fixtures/load-payload.ts
import { readFileSync } from 'node:fs';
import { parse } from 'yaml';
 
export function fixturePayloadOf(tcId: string) {
  const [area] = tcId.replace('TC-', '').split('-');
  const doc = parse(readFileSync(`testcases/${area.toLowerCase()}/${tcId}.yaml`, 'utf8'));
  if (!doc.fixture_payload) throw new Error(`${tcId}: fixture_payload 없음`);
  return doc.fixture_payload;
}
 
// tests/order-shipping.spec.ts 에서
// test.use({ storageState: '.auth/buyer.json', fixturePayload: fixturePayloadOf('TC-ORD-021') });

qa-e2e-{CI 실행 ID}-{워커 번호}-{테스트 ID}-r{재시도 횟수}
예: qa-e2e-8812345-3-a1b2c3d4-r0

// reporters/triage-reporter.ts
import type { Reporter, TestCase, TestResult } from '@playwright/test/reporter';
 
type Triage = '환경 문제' | '셀렉터 오류' | '실제 버그' | '미분류';
 
export function classify(result: TestResult): Triage {
  const err = result.errors[0];
  const msg = `${err?.message ?? ''}\n${err?.stack ?? ''}`;
  const lastPhase = [...result.annotations].reverse().find((a) => a.type === 'phase')?.description;
 
  // 1) Fixture 단계 실패 — API 4xx/5xx 또는 fixture 단계에서 멈춤
  if (/FixtureApiError|\[fixture:/.test(msg) || lastPhase === 'fixture') return '환경 문제';
 
  // 2) UI 단계 — 요소를 찾지 못함
  if (/strict mode violation/.test(msg)) return '셀렉터 오류';
  if (/Timeout \d+ms exceeded/.test(msg) && /waiting for (locator|getBy)/.test(msg)) return '셀렉터 오류';
 
  // 3) UI 단계 — 요소는 있으나 기대와 다름
  if (/expect\(.*\)\.to|toHave|toBe|toContain/.test(msg)) return '실제 버그';
 
  return '미분류';
}
 
export default class TriageReporter implements Reporter {
  private rows: { title: string; triage: Triage; message: string }[] = [];
 
  onTestEnd(test: TestCase, result: TestResult) {
    if (result.status === 'passed' || result.status === 'skipped') return;
    this.rows.push({
      title: test.titlePath().join(' > '),
      triage: classify(result),
      message: (result.errors[0]?.message ?? '').split('\n')[0].slice(0, 200),
    });
  }
 
  async onEnd() {
    // 여기서 QMS·결함 추적 도구 API 로 전송하거나 파일로 저장한다
    // '실제 버그' 는 결함 "초안"으로만 만든다 — 등록은 사람이 확인한 뒤
    console.table(this.rows);
  }
}

// playwright.config.ts (발췌)
import { defineConfig } from '@playwright/test';
 
export default defineConfig({
  globalSetup: require.resolve('./global-setup'),
  reporter: [['html'], ['./reporters/triage-reporter.ts']],
  use: { baseURL: process.env.WEB_BASE_URL },
});