--- name: property-tests description: "EARS 수용 기준(WHEN … THEN … SHALL) 하나마다 fast-check 속성 검사를 하나씩 만드는 규칙. 기준값은 스펙 문장의 숫자에서 가져오고(구현 상수 import 금지), 경계 바로 안쪽 값을 반드시 생성하며, 나머지 입력은 모두 유효하게 고정한다. '수용 기준으로 테스트 만들어', '속성 검사 생성', 'generate property-based tests from acceptance criteria' 요청이나 판정이 노랑(no-tests·stale)일 때 쓴다." --- # property-tests — 수용 기준을 속성 검사로 검사는 "이 기준의 WHEN 조건을 만족하는 **모든** 입력에 대해 결과가 THEN과 같다"를 확인하는 속성이다. 예시 하나를 확인하는 테스트가 아니다. 다 만든 검사는 check-the-checks를 거쳐야 채택된다. ``: `.kiro/hooks/tripwire.json`의 command에서 하위 명령 앞부분(예: `node ../guard/dist/cli.js`). 파일이 없으면 setup 스킬 1단계와 같은 방법으로 찾는다. ## 1. 입력 모으기 (읽기만) - 대상 기준의 ID·문장·`textHash`: `.kiro/guard/index.json`을 파일 읽기 도구로 읽는다. 없으면 guard를 개발하는 저장소에서는 ` check`를 먼저 실행하고, guard가 설치된 저장소(`.kiro/guard/bin/`)에서는 사람에게 실행을 부탁하거나 스펙 문서를 직접 읽는다 — 설치된 guard는 예약 경로 안이라 문지기가 셸 실행을 막는다. 문장은 `.kiro/specs//requirements.md`의 것과 같아야 한다. - 같은 스펙의 다른 기준 전부: 나머지 입력을 유효하게 고정할 때 쓴다. - 검사 대상: 기준의 동작을 밖에서 관찰할 수 있는 공개 진입점 함수(예: `validateSignup`). 그 함수의 입력·출력 형태만 본다. 구현 안의 비교식·상수는 기준값의 출처가 아니다. ## 2. 파일과 이름 | 항목 | 규칙 | 이유 | |---|---|---| | 파일 | 기준 하나 = 파일 하나. `config.json`의 `testGlobs`가 가리키는 테스트 폴더 아래 `/.prop.test.ts` (예: `tests/signup/R2.3.prop.test.ts`) | 봉인이 파일 단위다. 한 파일에 여러 기준을 넣으면 하나를 다시 만들 때 나머지 기준의 봉인까지 깨진다 | | 테스트 이름 | `[Rn.m] <기준 요약>` (예: `[R2.3] 8자 미만 비밀번호는 거절`). 작업 공간에 스펙이 둘 이상이면 `[:Rn.m]` | 짧은 태그는 그 ID를 가진 스펙이 정확히 하나일 때만 연결되고, 아니면 고아가 된다 | | 머리 주석 | 첫 줄 `// tripwire: : ` (예: `// tripwire: signup:R2.3 sha256:…`). `textHash`는 index.json 값을 그대로 복사하고 직접 계산하지 않는다 | 기록용(guard는 읽지 않는다): 어느 문장으로 만든 검사인지 사람이 대조할 수 있게 남긴다. `stale` 판정은 봉인 때 `sealed.json`에 남은 textHash로만 한다 — 봉인 전 검사는 문장이 바뀌어도 노랑이 되지 않는다 | | import | `vitest`, `fast-check`, 검사 대상 진입점 함수만 | 3절 | ## 3. 기준값은 스펙 문장에서 - 숫자·단위·경계는 스펙 문장에서 읽어 검사 파일 안에 적는다. 이름 붙인 상수로 두고 출처를 주석으로 단다(예: `SPEC_MIN_LENGTH = 8`, 주석 `R2.3 '8자 미만이면 거절'`). - 구현의 상수(예: `MIN_PASSWORD_LENGTH`)나 도우미(예: 나이 계산 함수)를 import하거나 불러서 생성 범위나 기대값을 만들지 않는다. 구현의 경계가 6으로 바뀌면 검사의 범위도 같이 6으로 바뀌어, 정상 코드에서는 통과하면서 위반은 못 잡는 검사가 된다. - 다른 검사 파일이나 공용 도우미 파일도 import하지 않는다. 봉인되지 않은 파일을 고쳐 봉인된 검사의 동작을 바꾸는 길이 생긴다. 필요한 생성기는 그 검사 파일 안에 둔다. ## 4. 속성 짜는 법 1. **조건의 입력 전체**: WHEN 조건을 만족하는 입력을 넓게 생성한다. 예: "8자 미만" → 2~7자(다른 기준을 지키려고 영문자·숫자를 하나씩 넣으므로 최소 2자)의 여러 문자 구성. 2. **경계 바로 안쪽을 반드시 포함**: 숫자 경계는 그 수치를 `fc.integer({ min, max })`로 먼저 고른 뒤 값을 만든다(길이를 먼저 고르고 그 길이의 문자열, 만 나이를 먼저 고르고 생년월일). 경계 바로 안쪽 값(7자, 만 13세, 21시 00분)이 100회 안에 반드시 나와야 경계를 한 칸만 옮긴 실수도 잡는다. 고를 수 있는 값이 20개를 넘는 범위(하루의 분 0~1439, 금액 등)에서는 고르게 뽑는 것만으로 경계가 나오지 않는다 — 경계 바로 안쪽 값을 생성기 안에 섞는다: `fc.oneof(fc.constant(<경계 바로 안쪽 값>), fc.integer({ min, max }))`. 경계를 `fc.assert` 밖의 `expect`로 따로 확인하지 않는다 — 그렇게 실패하면 fast-check의 반례와 시험한 입력 기록이 남지 않아 guard가 반례를 기록하지 못한다. 3. **나머지 입력은 모두 유효하게**: 같은 스펙의 다른 기준을 모두 만족하는 기본 입력을 스펙 문장에서 정하고, 대상 기준에 관련된 값만 생성기로 바꾼다(예: 가입이면 `@`가 있고 가입되지 않은 이메일, 영문자·숫자가 든 8자 이상 비밀번호, 만 14세 이상 생년월일). 그래야 결과를 가르는 것이 대상 기준 하나뿐이고 실패가 정확히 그 요구사항을 가리킨다. 조건 안에서도 다른 기준을 함께 어기는 값(예: 8자 미만이면서 숫자가 없는 비밀번호)은 만들지 않는다. 기준 문장과 상관없는 입력은 고정 값으로 두고 `fc.property`의 인자로 넣지 않는다 — 비밀번호 길이 기준이면 생성기는 비밀번호 하나뿐이고(`fc.property(shortPassword, (password) => …)`), 동의 여부 같은 값을 `fc.boolean()`으로 함께 생성하지 않는다. 반례는 기준을 어긴 값만으로 읽혀야 한다(`["a0aaaa"]`, `["a0aaaa", false]`는 안 된다). `fc.property`의 인자는 검사 대상 함수에 그대로 넣는 입력 필드 값이어야 한다 — 수치를 먼저 골랐으면 생성기 안에서 `.map`으로 필드 값으로 바꾼 뒤 인자로 받는다(분 1260을 골랐으면 `'21:00'`으로). 반례 `["21:00"]`은 그 입력 칸에 그대로 넣어 볼 수 있지만 `[1260]`은 그렇지 않다. 기준이 입력 여러 개 사이의 관계를 말해(새 금액이 지금 금액의 20분의 1을 넘게 오름) 값을 함께 뽑아야 하면, 인자 하나를 그 기준에 관련된 필드 값만 담은 배열로 만들고 순서를 주석에 적는다 — `// [지금 금액, 새 금액]`, `fc.tuple(...).map(([now, extra]) => [now, now + Math.floor(now / 20) + 1 + extra])`. 반례가 `[[20,22]]`처럼 값만으로 짧게 찍힌다. 필드 이름을 키로 한 객체(`[{"currentRent":20,"newRent":22}]`)로 만들지 않는다 — 반례가 길어져 guard serve 화면의 반례 칸에서 잘린다. 4. **결과는 스펙이 말한 것만**: THEN의 관찰 가능한 결과(예: 가입이 거절되는가)만 확인한다. 스펙에 없는 내부 사유 코드·오류 문구·호출 순서는 확인하지 않는다. 조건 밖의 입력(예: 8자 이상)에 대해 스펙이 말하지 않은 결과를 단정하지 않는다. 5. **결정적으로**: 현재 시각·환경 변수·네트워크에 기대지 않는다. 검사 대상이 오늘 날짜 같은 값을 받으면 고정 값을 넘긴다. 날짜 경계는 고정한 오늘에서 직접 만든다(오늘이 2026-11-14면 2012-11-14 출생은 만 14세, 2012-11-15 출생은 만 13세). 6. **생성기는 처음부터 조건에 맞게**: `map`·`tuple`로 조건을 만족하게 구성하고, `filter`는 드물게 걸러지는 경우에만 쓴다. 7. **fast-check 4**: `fc.fullUnicode`·`fc.fullUnicodeString`·`fc.unicodeString`·`fc.stringOf`·`fc.asciiString`은 없다. 문자열은 `fc.string({ unit, minLength, maxLength })`(`unit`: `'grapheme'`·`'grapheme-composite'`·`'grapheme-ascii'`(기본)·`'binary'`·`'binary-ascii'` 또는 한 글자를 내는 생성기), `fc.stringMatching(정규식)`, `fc.constantFrom(...)`으로 만든다. 그 밖에 `fc.integer({ min, max })`, `fc.tuple`, `fc.array`, `fc.boolean`. 실행은 `fc.assert(fc.property(...))`이고, 실행 횟수(`numRuns`)를 기본값보다 줄이지 않는다. 8. **스펙에 없는 해석 금지**: 대소문자 구분, 앞뒤 공백 처리처럼 스펙 문장에 없는 해석을 검사에 넣지 않는다. 필요하면 사람에게 묻고, rule-intake 스킬로 기준을 보완하자고 제안한다. ## 5. 만든 뒤 1. 그 기준의 검사만 실행한다: `npx vitest run -t "R2.3"`(이름 필터 — 예시의 ID를 대상 ID로 바꾼다). 봉인된 검사 파일의 경로가 든 셸 명령은 문지기가 막으므로, 검사를 돌릴 때는 파일 경로 대신 이름 필터나 전체 실행(`npx vitest run`)을 쓴다. `npx`가 없으면 ``(config.json의 `testDir`, 없으면 작업 공간 루트)에서 `node node_modules/vitest/vitest.mjs run -t "R2.3"`. guard check도 그 위치의 vitest만 쓰고 상위 폴더는 찾지 않는다. 2. **통과** → check-the-checks 스킬로 넘어간다. 통과만으로는 채택되지 않는다. 3. **실패** → 반례가 기준의 WHEN 조건을 만족하는지 스펙 문장으로 판단한다. - 만족하는데 코드가 받아들였다 = **코드가 기준을 어긴 것**이다. 검사를 고치지 않는다. 반례와 함께 사람에게 알리고 resolve-violation 스킬의 설명 형식을 따른다. - 만족하지 않는다(다른 기준까지 어긴 값 등) = 생성기 오류다. 생성기만 고친다. 기준값과 범위는 그대로 둔다. 4. 이 과정에서 검사 대상 코드(`src/` 등)와 vitest 설정은 고치지 않는다. 새 패키지를 설치하지 않는다. ## 하지 않는 것 - 검사를 통과시키려고 기준값을 바꾸거나, 생성 범위를 좁히거나, 조건을 빼는 것 - `sealed.json`에 오른 검사 파일을 고치는 것 — 그 요구사항에 사람이 '스펙을 고친다'를 승인한 동안의 재생성만 예외(resolve-violation) - 테스트 이름에서 태그를 빼거나, 다른 기준의 태그를 붙이는 것