k6-script-creation은(는) 무엇을 하나요?

이 스킬은 팀 내 모든 구성원이 k6에 대한 사전 지식이 없어도 실행, 이해, 수정할 수 있는 k6 성능 테스트를 생성합니다. 이를 위해 각 스크립트는 동일한 구조를 가지며, 이름은 그 역할을 명확히 나타내고, 자격 증명은 코드 외부에 저장되며, 각 부분을 설명하는 .md 파일이 함께 제공됩니다.

팀의 우선순위: 부하(load) 및 스트레스(stress) 테스트, HTTP와 k6 브라우저 모두 포함. **스모크(smoke)**는 항상 사전 단계로 수행됩니다.

진리의 원천: 공식 문서

작성되는 모든 내용은 https://grafana.com/docs/k6/latest/ (k6 v2.x)와 일치해야 합니다. 이 스킬의 참조 자료는 해당 문서를 요약한 것입니다. 만약 어떤 내용이 다루어지지 않았거나, API, 옵션, 메트릭에 대해 조금이라도 의문이 있다면 공식 페이지를 확인하세요 (references/official-docs.md에 맵이 있습니다). 인터넷의 많은 예제는 v2에서 더 이상 작동하지 않는 오래된 API(k6/experimental/browser, 동기식 브라우저, browser_web_vital_fid)를 사용합니다.

참조 파일 (필요한 것만 읽으세요)

파일	언제 읽을까요?
`references/test-types.md`	항상: 테스트 유형, 스테이지 프로필, 실행기 선택
`references/thresholds-checks.md`	항상: 표준 임계값 및 체크 작성 방법
`references/http-patterns.md`	API 테스트: 라이프사이클, 인증, 비밀, 상관관계, 데이터
`references/browser-patterns.md`	k6 브라우저 또는 하이브리드 테스트
`references/doc-template.md`	설명 `.md` 파일 작성 시
`references/official-docs.md`	특정 주제의 공식 페이지 검색
`assets/lib/config.js`	`k6/lib/config.js`에 그대로 복사
`assets/templates/*`	플로우, 테스트, README, `.secrets.example`의 기초

프로젝트의 표준 구조

k6/
├── tests/
│   ├── api/        <type>-<flow>.js                         예: load-checkout.js, stress-search-products.js
│   └── browser/    <type>-<flow>-browser.js                 예: load-login-browser.js
├── lib/
│   ├── config.js   (assets/lib/config.js에서 복사)
│   ├── flows/      <flow>.js — 사용자 단계, 모든 테스트 유형에서 재사용
│   └── pages/      <page>-page.js — 페이지 객체 (브라우저 전용, 플로우에 여러 페이지가 있는 경우)
├── data/           JSON/CSV 테스트 데이터 (절대 자격 증명 포함 금지)
├── docs/           <script-name>.md
├── .secrets.example
└── README.md       (assets/templates/k6-README.md에서 가져오며 스크립트 인덱스 포함)

이름 규칙: 케밥-케이스, 유형 접두사 (smoke-, load-, stress-, spike-, soak-, breakpoint-) + 설명적인 비즈니스 플로우 (checkout, search-products, test1이나 api 금지). 브라우저 테스트는 접미사 -browser를 사용합니다. .md 파일은 스크립트와 정확히 동일한 이름을 가집니다.

언어: 주석과 문서는 한국어로 작성합니다. 코드 식별자는 영어를 사용합니다.

프로젝트에 이미 k6/ 폴더가 있다면, 기존 config.js, 플로우, 페이지 객체를 중복 생성하지 말고 재사용하고, 기존 구조를 존중하세요.

워크플로우

1. 요청 이해

사용자의 말에서 다음을 추출하세요:

테스트 유형: 부하(load), 스트레스(stress) 또는 기타. "얼마나 버틸 수 있는지" 또는 "한계까지 밀어붙이기"를 원하면 스트레스(또는 정확한 한계점을 원하면 브레이크포인트)입니다. "정상 부하" 또는 "일반적인 하루"를 원하면 부하(load)입니다.
API, 브라우저 또는 하이브리드
엔드포인트 또는 화면 및 플로우 순서, 인증 방식, 각 단계에서 검증할 내용
부하 (동시 사용자 수 또는 요청/초), 지속 시간 및 SLA (예: p95 < 500ms)
대상 환경

합리적으로 추정할 수 없고 작업을 막는 것만 물어보세요: URL이나 엔드포인트를 제공하지 않았다면 물어보고, 목표가 프로덕션인지 명확하지 않을 때는 항상 물어보세요. 나머지는 참조 자료의 기본값(SLA 500ms, think time 1-3초, 스트레스 = 부하의 2배)으로 가정하고, 각 가정은 .md의 "가정" 섹션에 기록합니다. 사용자가 자신의 부하 수치를 모른다면 알려주세요: 부하 수치 없이 실행된 테스트는 사용자가 원하는 질문과 다른 질문에 답변하게 됩니다.

2. 구조 준비

k6/에 누락된 항목을 생성하세요: lib/config.js (assets/lib/config.js의 정확한 복사본), 스크립트에서 사용하는 키를 포함한 .secrets.example, 템플릿에서 가져온 README.md, 그리고 프로젝트 .gitignore에 다음을 추가하세요:

k6/.secrets
k6/screenshots/

3. 플로우 및 테스트 작성

플로우는 k6/lib/flows/<flow>.js에 작성합니다 (assets/templates/flow-api.js를 기반으로). 요청, 체크, 번호가 매겨진 그룹, name 태그, think time을 포함합니다. 플로우에 로그인이 필요하면 setup()에서 호출하는 login() 함수를 내보냅니다.
테스트는 k6/tests/api/<type>-<flow>.js에 작성합니다 (assets/templates/test-api.js 기반). options (시나리오 + 임계값), setup(), default()만 정의하며, default()는 플로우를 호출합니다. 스테이지와 임계값은 명시적으로 파일에 작성하며, 각 줄에 주석을 답니다.
브라우저 테스트는 k6/tests/browser/<type>-<flow>-browser.js에 작성합니다 (assets/templates/test-browser.js 기반). 기본값은 하이브리드: HTTP 부하 + 소수의 브라우저 VU. references/browser-patterns.md를 읽으세요.
항상 smoke-<flow>.js도 생성하세요 (아직 없는 경우). 저렴하고(플로우 재사용), 부하 또는 스트레스 전 필수 첫 단계입니다.
동일한 플로우에 대한 부하 테스트 스크립트 없이 스트레스 테스트를 요청받으면, 둘 다 생성하세요: 공식 문서에 따르면 스트레스는 부하 테스트 후에 실행되며 스크립트를 재사용합니다.

팀과 시스템을 보호하는 협상 불가 규칙:

자격 증명, 토큰, API 키는 오직 k6/secrets (await secrets.get('NAME'))를 통해 --secret-source=file=k6/.secrets와 함께 사용합니다. 코드, data/, __ENV 기본값, console.log에 절대 포함하지 마세요.
URL과 환경은 lib/config.js에서 읽은 -e BASE_URL / -e TARGET_ENV를 통해 전달합니다. 절대 하드코딩하지 마세요.
config.js의 프로덕션 보호 기능을 제거하거나 약화시키지 마세요.
jslib import는 정확한 버전과 함께 사용합니다 (official-docs.md 참조).
브라우저: k6/browser, async 함수, 시나리오에 options.browser.type: 'chromium', finally 블록에서 page.close(), 비동기 체크를 위한 k6-utils의 check, sleep() 대신 page.waitForTimeout().
각 요청에는 안정적인 name 태그 ('GET /items/:id')를 사용하여 ID가 포함된 URL이 메트릭 수를 폭발시키지 않도록 합니다.

4. 설명 `.md` 파일 작성

k6/docs/<name>.md에 스크립트당 하나씩, references/doc-template.md의 모든 섹션을 따라 작성합니다. 읽는 사람은 전문가가 아닙니다: 각 용어를 처음 나올 때 설명하고 (VU, 반복, p95, 임계값), 각 숫자의 이유를 설명하며, 스크립트의 실제 값을 사용합니다. ASCII 부하 프로필 다이어그램, 체크 및 임계값 표(평문으로), 정확한 실행 명령어(먼저 스모크), 일반적인 오류를 포함합니다. 그런 다음 스크립트를 k6/README.md의 인덱스에 추가합니다.

5. 검증

각 새 스크립트에 대해 k6 inspect -e BASE_URL=https://example.test -e TARGET_ENV=staging <script>를 실행합니다. 부하를 생성하지 않고 구문 오류, 깨진 import, 잘못된 옵션을 감지합니다. k6가 설치되지 않은 경우 그 사실을 알리고 명령어를 제공하여 직접 실행하도록 합니다.
실제 실행은 사용자의 명시적 허가가 있는 경우에만 스모크(소수의 VU, 몇 초)로, 프로덕션이 아닌 환경에서 수행합니다. 절대 부하, 스트레스, 스파이크, 소크, 브레이크포인트를 직접 실행하지 마세요: 이는 공유 시스템에 실제 부하를 생성합니다.

6. 응답

짧은 응답 형식:

생성되거나 수정된 파일 목록.
스모크 및 요청된 테스트를 실행하는 명령어.
주요 가정 (.md에 있는 것과 동일).
검증한 내용과 하지 않은 내용 (예: "k6 inspect 통과; 아직 API에 대해 실행되지 않음").

기존 스크립트 검토 및 수정

스크립트를 이해, 수정 또는 개선하라는 요청이 들어오면:

전체를 읽고 표준 및 공식 문서와 비교합니다 (오래된 API, await 없는 브라우저, page.close 누락, 코드 내 자격 증명, 임계값 없음, name 태그 없음, think time 없음, "롤러코스터" 같은 프로필 등).
문제를 심각도 순서대로 간단한 언어로 설명하고 변경 사항을 제안합니다.
수정 시 스크립트의 .md 파일도 업데이트 (또는 생성)하여 문서가 코드와 일치하도록 합니다.
이름이 표준을 따르지 않으면 이름 변경을 제안하되, 확인 없이 변경하지 마세요. 스크립트를 호출하는 파이프라인이 손상될 수 있습니다.

k6-script-creation