웹이 실제로 붙는 API

이 문서는 Try it out용이 아닙니다. 웹이 작성 데이터를 보내고, 테스트케이스를 저장할 때 쓰는 계약입니다. 우리는 DB를 조회하지 않습니다.

베이스 URL

운영: https://quttack.onrender.com

로컬: http://localhost:3000

연동 Swagger: /docs/swagger · OpenAPI: /api/docs/web

한 줄 계약

웹은 Project / RuleGroup / Rule / Scene / SceneConnection을 그대로 보냅니다. 저장은 응답 authoring.testCases만 씁니다.

testCases, qaAnalysis, agents는 표시·분석용입니다. DB 저장 컬럼으로 쓰지 마세요.

프로필

profileId는 body에 넣습니다. body가 query보다 우선합니다. 빼면 testtrace-l2를 씁니다.

testtrace-l1

qwen2.5:7b. 빠른 초안. 규칙 누락이 날 수 있습니다.

testtrace-l2 · 권장

qwen2.5:14b. 일상 생성. 성공/실패/흐름이 가장 고릅니다.

testtrace-l3

qwen2.5:32b. 주어진 규칙에 맞춰 적게 짓습니다.

저장 필드

응답	웹 DB
`authoring.testCases[].title`	TestCase.title
`authoring.testCases[].description`	TestCase.description
`authoring.testCases[].displayOrder`	TestCase.displayOrder
`authoring.testCases[].type`	기능/성능 등 유형
`authoring.testCases[].priority`	우선순위
`authoring.testCases[].preconditions`	사전 조건
`authoring.testCases[].references`	참조
`steps[].title`	TestCaseStep.title
`steps[].descriptionHTML`	TestCaseStep.descriptionHTML
`steps[].expectedResult`	TestCaseStep 기대 결과
`steps[].sceneId`	TestCaseStep.sceneId
`steps[].status`	READY
`steps[].displayOrder`	TestCaseStep.displayOrder

요청에 scenes[].id를 넣으면 step의 sceneHint와 화면 title을 맞춰 sceneId를 채웁니다.

웹 apply는 type, priority, preconditions, references, steps[].expectedResult까지 저장해야 합니다. title/description/steps만 넣으면 유형·우선순위·사전 조건이 비어 저장됩니다. version과 platform은 추측하지 않으므로 비워 둡니다.

POST/api/ai/generate-testcases

웹이 쓰는 생성 API입니다. mode 기본값은 pipeline입니다.

요청

{
  "profileId": "testtrace-l2",
  "mode": "pipeline",
  "project": {
    "id": "proj_tw_qa_01",
    "title": "TravelWallet QA",
    "description": "사용자가 Google OAuth로 로그인한 뒤 새 프로젝트를 생성한다."
  },
  "ruleGroups": [
    {
      "id": "rg_login_01",
      "title": "로그인",
      "rules": [
        {
          "id": "rule_login_fail_01",
          "ruleGroupId": "rg_login_01",
          "description": "로그인 실패 시 사용자에게 명확한 에러 메시지를 보여준다."
        }
      ]
    }
  ],
  "scenes": [
    {
      "id": "scene_login_01",
      "title": "로그인",
      "description": "Google 로그인 버튼이 있는 진입 화면"
    },
    {
      "id": "scene_project_create_01",
      "title": "프로젝트 생성",
      "description": "프로젝트명 입력과 생성 CTA가 있는 화면"
    }
  ],
  "sceneConnections": [
    {
      "sourceSceneId": "scene_login_01",
      "targetSceneId": "scene_project_create_01"
    }
  ]
}

응답에서 저장할 값

{
  "testCases": [
    {
      "title": "로그인 성공 후 프로젝트 생성",
      "description": "유효한 Google 계정으로 로그인한 뒤 프로젝트를 만든다.",
      "displayOrder": 0,
      "type": "functional",
      "priority": "high",
      "status": "draft",
      "labels": [
        "AI"
      ],
      "preconditions": "사용자는 유효한 Google 계정을 가지고 있다.",
      "steps": [
        {
          "title": "로그인 화면에서 Google 로그인 버튼을 클릭한다.",
          "descriptionHTML": "<p>로그인에 성공하고 프로젝트 생성 화면으로 이동한다.</p>",
          "expectedResult": "로그인에 성공하고 프로젝트 생성 화면으로 이동한다.",
          "sceneId": "scene_login_01",
          "status": "READY",
          "displayOrder": 1
        },
        {
          "title": "프로젝트명을 입력하고 생성 CTA를 클릭한다.",
          "descriptionHTML": "<p>새 프로젝트가 생성된다.</p>",
          "expectedResult": "새 프로젝트가 생성된다.",
          "sceneId": "scene_project_create_01",
          "status": "READY",
          "displayOrder": 2
        }
      ]
    },
    {
      "title": "로그인 실패 시 에러 메시지 확인",
      "description": "잘못된 계정 또는 실패한 OAuth 응답이다.",
      "displayOrder": 1,
      "type": "functional",
      "priority": "high",
      "status": "draft",
      "labels": [
        "AI"
      ],
      "preconditions": "로그인 화면에서 실패한 인증을 재현할 수 있다.",
      "steps": [
        {
          "title": "로그인 화면에서 Google 로그인 버튼을 클릭한다.",
          "descriptionHTML": "<p>로그인 실패 시 사용자에게 명확한 에러 메시지가 보인다.</p>",
          "expectedResult": "로그인 실패 시 사용자에게 명확한 에러 메시지가 보인다.",
          "sceneId": "scene_login_01",
          "status": "READY",
          "displayOrder": 1
        }
      ]
    }
  ]
}

전체 응답 예시는 연동 Swagger의 200 예시를 보면 됩니다. usedProfileId가 요청과 다르면 내장 작성기로 빠진 것입니다. warning이 있으면 JSON이 깨져 요약 draft로 대체된 경우입니다.

GET/api/ai/profiles

프로필 목록입니다. 생성 전에 한 번 읽고, 선택지는 L1/L2/L3만 보여도 됩니다.

GET /api/ai/profiles

POST/api/ai/map-scenes

생성 응답에 sceneId가 이미 있으면 호출하지 않아도 됩니다. 기존 TC에 화면을 다시 붙일 때만 씁니다.

{
  "profileId": "testtrace-l2",
  "testCases": [
    {
      "title": "로그인 성공 후 프로젝트 생성",
      "description": "유효한 Google 계정으로 로그인한 뒤 프로젝트를 만든다.",
      "displayOrder": 0,
      "type": "functional",
      "priority": "high",
      "status": "draft",
      "labels": [
        "AI"
      ],
      "preconditions": "사용자는 유효한 Google 계정을 가지고 있다.",
      "steps": [
        {
          "title": "로그인 화면에서 Google 로그인 버튼을 클릭한다.",
          "descriptionHTML": "<p>로그인에 성공하고 프로젝트 생성 화면으로 이동한다.</p>",
          "expectedResult": "로그인에 성공하고 프로젝트 생성 화면으로 이동한다.",
          "sceneId": "scene_login_01",
          "status": "READY",
          "displayOrder": 1
        },
        {
          "title": "프로젝트명을 입력하고 생성 CTA를 클릭한다.",
          "descriptionHTML": "<p>새 프로젝트가 생성된다.</p>",
          "expectedResult": "새 프로젝트가 생성된다.",
          "sceneId": "scene_project_create_01",
          "status": "READY",
          "displayOrder": 2
        }
      ]
    },
    {
      "title": "로그인 실패 시 에러 메시지 확인",
      "description": "잘못된 계정 또는 실패한 OAuth 응답이다.",
      "displayOrder": 1,
      "type": "functional",
      "priority": "high",
      "status": "draft",
      "labels": [
        "AI"
      ],
      "preconditions": "로그인 화면에서 실패한 인증을 재현할 수 있다.",
      "steps": [
        {
          "title": "로그인 화면에서 Google 로그인 버튼을 클릭한다.",
          "descriptionHTML": "<p>로그인 실패 시 사용자에게 명확한 에러 메시지가 보인다.</p>",
          "expectedResult": "로그인 실패 시 사용자에게 명확한 에러 메시지가 보인다.",
          "sceneId": "scene_login_01",
          "status": "READY",
          "displayOrder": 1
        }
      ]
    }
  ],
  "scenes": [
    {
      "id": "scene_login_01",
      "title": "로그인",
      "description": "Google 로그인 버튼이 있는 진입 화면"
    },
    {
      "id": "scene_project_create_01",
      "title": "프로젝트 생성",
      "description": "프로젝트명 입력과 생성 CTA가 있는 화면"
    }
  ]
}

분석 API

POST /api/ai/analyze-coverage와 POST /api/ai/qa-analysis는 저장용이 아닙니다. 빠진 검증이나 ISTQB 점수만 볼 때 호출합니다. QA 분석은 LLM을 부르지 않습니다.

{
  "project": {
    "id": "proj_tw_qa_01",
    "title": "TravelWallet QA",
    "description": "사용자가 Google OAuth로 로그인한 뒤 새 프로젝트를 생성한다."
  },
  "ruleGroups": [
    {
      "id": "rg_login_01",
      "title": "로그인",
      "rules": [
        {
          "id": "rule_login_fail_01",
          "ruleGroupId": "rg_login_01",
          "description": "로그인 실패 시 사용자에게 명확한 에러 메시지를 보여준다."
        }
      ]
    }
  ],
  "scenes": [
    {
      "id": "scene_login_01",
      "title": "로그인",
      "description": "Google 로그인 버튼이 있는 진입 화면"
    },
    {
      "id": "scene_project_create_01",
      "title": "프로젝트 생성",
      "description": "프로젝트명 입력과 생성 CTA가 있는 화면"
    }
  ],
  "testCases": [
    {
      "title": "로그인 성공 후 프로젝트 생성",
      "description": "유효한 Google 계정으로 로그인한 뒤 프로젝트를 만든다.",
      "displayOrder": 0,
      "type": "functional",
      "priority": "high",
      "status": "draft",
      "labels": [
        "AI"
      ],
      "preconditions": "사용자는 유효한 Google 계정을 가지고 있다.",
      "steps": [
        {
          "title": "로그인 화면에서 Google 로그인 버튼을 클릭한다.",
          "descriptionHTML": "<p>로그인에 성공하고 프로젝트 생성 화면으로 이동한다.</p>",
          "expectedResult": "로그인에 성공하고 프로젝트 생성 화면으로 이동한다.",
          "sceneId": "scene_login_01",
          "status": "READY",
          "displayOrder": 1
        },
        {
          "title": "프로젝트명을 입력하고 생성 CTA를 클릭한다.",
          "descriptionHTML": "<p>새 프로젝트가 생성된다.</p>",
          "expectedResult": "새 프로젝트가 생성된다.",
          "sceneId": "scene_project_create_01",
          "status": "READY",
          "displayOrder": 2
        }
      ]
    },
    {
      "title": "로그인 실패 시 에러 메시지 확인",
      "description": "잘못된 계정 또는 실패한 OAuth 응답이다.",
      "displayOrder": 1,
      "type": "functional",
      "priority": "high",
      "status": "draft",
      "labels": [
        "AI"
      ],
      "preconditions": "로그인 화면에서 실패한 인증을 재현할 수 있다.",
      "steps": [
        {
          "title": "로그인 화면에서 Google 로그인 버튼을 클릭한다.",
          "descriptionHTML": "<p>로그인 실패 시 사용자에게 명확한 에러 메시지가 보인다.</p>",
          "expectedResult": "로그인 실패 시 사용자에게 명확한 에러 메시지가 보인다.",
          "sceneId": "scene_login_01",
          "status": "READY",
          "displayOrder": 1
        }
      ]
    }
  ]
}

에러

{
  "message": "project, scenes, rules, ruleGroups, or featureDescription is required",
  "code": "AI_VALIDATION_ERROR"
}

code는 AI 계층 에러일 때만 있습니다. 인증 헤더는 생성 API에 필요 없습니다.