본문으로 건너뛰기

QA 규약

이 문서는 개발자와 QA 엔지니어가 QA Agent를 사용할 때 알아야 할 공통적인 규약을 설명합니다.

1. QA Agent 설계 원칙​

1.1 엔드포인트 구조​

  • 리소스는 복수형 명사를 사용합니다 (예: /tests, /reports)
  • 다중 단어는 케밥 케이스로 작성합니다 (예: /test-results)
  • 계층 구조는 경로로 표현합니다 (예: /tests/{testId}/results)

1.2 테스트 유형​

  • unit: 단위 테스트
  • integration: 통합 테스트
  • e2e: End-to-End 테스트
  • performance: 성능 테스트
  • security: 보안 테스트

1.3 테스트 상태​

  • pending: 대기 중
  • running: 실행 중
  • passed: 성공
  • failed: 실패
  • skipped: 건너뜀
  • error: 에러 발생
  • timeout: 시간 초과

2. MCP Tools 사용 규약​

2.1 Tool 호출 형식​

모든 MCP Tool 호출은 다음 형식을 따릅니다:

{
  "tool": "tool-name",
  "arguments": {
    "param1": "value1",
    "param2": "value2"
  }
}
QA 엔지니어 참고사항

MCP Tool 호출 시 항상 필수 파라미터를 확인하고, 올바른 형식으로 전달해야 합니다. 잘못된 파라미터는 도구 실행 실패로 이어집니다.

2.2 Tool 응답 형식​

모든 MCP Tool은 표준화된 응답 형식을 따릅니다:

{
  "content": [
    {
      "type": "text",
      "text": "결과 내용"
    }
  ],
  "isError": false
}
에러 처리

isError가 true인 경우, text 필드에 에러 메시지가 포함됩니다. 이를 활용하여 적절한 에러 처리를 구현하세요.

2.3 MCP Tools 상세 가이드​

각 MCP Tool의 구체적인 사용법과 파라미터에 대한 상세 정보는 다음 문서를 참조하세요:

3. 테스트 실행 규약​

3.1 테스트 실행 요청​

테스트 실행 요청은 다음 정보를 포함해야 합니다:

{
  "testType": "e2e",
  "environment": "dev",
  "testSuite": "user-flow",
  "configuration": {
    "parallel": true,
    "maxRetries": 2,
    "timeout": 300000
  }
}

3.2 테스트 결과 형식​

테스트 결과는 다음 형식으로 반환됩니다:

{
  "testRunId": "run-123",
  "status": "completed",
  "summary": {
    "total": 50,
    "passed": 45,
    "failed": 3,
    "skipped": 2,
    "duration": 120000
  },
  "results": [
    {
      "testId": "test-001",
      "name": "User login test",
      "status": "passed",
      "duration": 2500,
      "logs": []
    }
  ]
}

4. 모니터링 및 로깅​

4.1 로그 레벨​

  • DEBUG: 상세 디버깅 정보
  • INFO: 일반 정보성 메시지
  • WARNING: 경고 메시지
  • ERROR: 에러 메시지
  • CRITICAL: 심각한 에러

4.2 로그 형식​

모든 로그는 구조화된 JSON 형식을 따릅니다:

{
  "timestamp": 1679471431000,
  "level": "ERROR",
  "service": "qa-agent",
  "component": "test-executor",
  "message": "Test execution failed",
  "metadata": {
    "testId": "test-001",
    "error": "Timeout exceeded"
  }
}
로깅 모범 사례
  • 충분한 컨텍스트 정보를 포함하세요
  • 민감한 정보는 로그에 포함하지 마세요
  • 구조화된 로그를 사용하여 검색과 분석을 용이하게 하세요

5. 성능 최적화​

5.1 병렬 실행​

  • 테스트는 가능한 한 병렬로 실행하여 전체 실행 시간을 단축합니다
  • 리소스 경합이 발생하지 않도록 적절한 동시 실행 수를 설정합니다
병렬 실행 가이드라인
  • CPU 코어 수의 2배를 초과하지 않는 것이 좋습니다
  • 메모리 집약적인 테스트는 동시 실행 수를 줄이세요
  • 데이터베이스 접근이 많은 테스트는 순차 실행을 고려하세요

5.2 캐싱 전략​

  • 자주 사용되는 테스트 데이터는 캐싱하여 성능을 향상시킵니다
  • 테스트 환경 설정은 재사용 가능하도록 구성합니다

6. 보안 고려사항​

6.1 인증 및 권한​

  • 모든 QA Agent API는 적절한 인증이 필요합니다
  • 테스트 실행 권한은 역할 기반으로 관리됩니다

6.2 민감 데이터 처리​

  • 테스트 데이터에 실제 사용자 정보를 포함하지 마세요
  • 로그에 비밀번호나 토큰을 기록하지 마세요
  • 테스트 완료 후 생성된 데이터는 정리하세요
보안 주의사항

프로덕션 데이터를 테스트 환경에서 사용할 때는 반드시 마스킹이나 익명화 처리를 해야 합니다.

QA 엔지니어를 위한 모범 사례​

  1. 테스트 격리: 각 테스트는 독립적으로 실행 가능해야 합니다
  2. 재현 가능성: 테스트 결과는 일관되고 재현 가능해야 합니다
  3. 명확한 명명: 테스트 이름은 테스트 목적을 명확히 나타내야 합니다
  4. 적절한 대기: 비동기 작업에 대해 적절한 대기 시간을 설정하세요
  5. 에러 처리: 예상되는 에러와 예상치 못한 에러를 구분하여 처리하세요
  6. 문서화: 복잡한 테스트 시나리오는 충분히 문서화하세요