품질 속성 시나리오

비기능 요구사항을 측정할 수 있는 시나리오로 다듬은 문서입니다. 아키텍처(01-architecture)는 이 시나리오들을 만족하도록 구성되어 있어야 하고, 시나리오마다 그것을 확인할 테스트가 있어야 합니다.

읽는 법

  • 시나리오는 SEI(Bass · Clements · Kazman, Software Architecture in Practice)의 여섯 부분으로 씁니다: 자극원(누가 · 무엇이), 자극(무슨 일), 환경(어떤 상황에서), 대상(시스템의 어느 부분), 응답(시스템이 하는 일), 응답 측정(합격 기준).
  • 아키텍처는 이 시나리오를 만족시키는 구조와 그 결정(ADR)입니다. 테스트는 합격 기준을 확인하는 방법과 실행할 때입니다. 테스트는 같은 ID로 자동 테스트를 만듭니다(테스트 이름에 T-0012 · QA-03: …처럼 그 시나리오의 ID를 넣습니다). 테스트 ID는 그 시나리오를 확인하는 테스트로, 테스트 목록 스크립트가 채웁니다(손으로 고치지 않습니다 → 99-test-list). 층마다 어떻게 테스트하는지는 02-test-architecture에 있습니다.
  • 합격 기준의 수치 가운데 요구사항에 없던 것은 제안값이라고 적었습니다. 확인받기 전입니다.
  • 목표의 근거는 그 수치를 왜 그렇게 정했는지입니다. 근거를 찾지 못한 수치는 “근거 없음(제안값)“이라고 밝혀 둡니다.
  • 시나리오가 기대는 유즈케이스는 02-use-cases의 ID로 적습니다.

1. 목록

ID품질 속성시나리오 (한 줄)요구사항중요도난이도우선
QA-01정합성어떤 편집 명령을 이어 해도 문서는 불변식을 지킨다R-NFR-01상중높음
QA-02정합성 · 신뢰성깨진 파일을 열어도 원본은 그대로이고 편집기는 죽지 않는다R-FMT-06상중높음
QA-03호환성 · 결정성같은 문서는 어느 배포 대상 · 브라우저 · OS에서 저장해도 같은 바이트다R-NFR-02, R-FMT-03상상높음
QA-04호환성열고 편집하지 않고 저장하면 원본과 같은 바이트다R-FMT-03상중높음
QA-05호환성옛 형식 버전의 파일이 모두 열린다R-FMT-02중하중간
QA-06이식성저장된 그림은 플러그인도 글꼴도 없는 뷰어에서 편집기와 같게 보인다R-FMT-01, R-FMT-07, R-FMT-08상상높음
QA-07성능블록 500개 문서에서 편집 한 번이 100ms 안에 화면에 반영된다R-NFR-03상상높음
QA-08성능블록 500개 문서가 정해진 시간 안에 열린다R-NFR-03 (제안)중중중간
QA-09자원저장 파일과 편집기 번들의 크기가 정해진 값을 넘지 않는다R-FMT-07 (제안)중중중간
QA-10변경 용이성새 배포 대상(셸)을 붙일 때 core · editor를 수정하지 않는다R-NFR-02, ADR-0002상중높음
QA-11변경 용이성화면 렌더링 백엔드를 바꿀 때 구현체 하나만 바뀌고 저장 파일은 그대로다ADR-0030중중중간
QA-12변경 용이성블록 종류를 추가할 때 셸을 수정하지 않고 기존 파일은 그대로 열린다R-BLK-12, R-BLK-13, R-BLK-14 (P2 블록)중하중간
QA-13변경 용이성화면 언어를 더할 때 코드를 수정하지 않는다R-NFR-04하하낮음
QA-14테스트 가능성core의 테스트는 DOM 없이 Node에서 실행된다R-NFR-06상하높음
QA-15사용성 · 접근성키보드만으로 주요 유즈케이스를 끝낼 수 있다R-NFR-05, R-EDIT-03상중높음
QA-16접근성고대비 화면 색과 흑백 팔레트는 정해진 대비를 지킨다R-NFR-05중하낮음
QA-17신뢰성저장에 실패해도 편집한 내용을 잃지 않는다UC-06 최소 보장상중높음
QA-18성능느린 휴대폰과 모바일 망에서 웹의 편집 화면이 정해진 시간 안에 보인다R-NFR-09중상중간
QA-19신뢰성초기화 중 응답 지연이나 오류가 발생해도 빈 화면으로 남지 않는다R-NFR-10상중높음
QA-20호환성 · 사용성휴대폰(Android의 Chrome)에서 터치로 열고 편집한다R-NFR-08중중중간
QA-21보안 · 신뢰성깨지거나 꾸민 공유 링크를 열어도 편집기는 죽지 않고, 작은 링크가 메모리를 다 쓰지 않는다R-WEB-05상중높음

중요도는 어기면 사용자가 얼마나 다치는가, 난이도는 만족시키려면 구조에 얼마나 힘이 드는가입니다(상 · 중 · 하). 난이도가 높을수록 아키텍처가 힘을 들이는 곳입니다(QA-03 · 06 · 07 · 18). “우선”은 둘을 함께 본 아키텍처의 무게입니다. 높음은 구조를 정하는 시나리오이고(어기면 구조를 바꿔야 함), 중간 · 낮음은 구현에서 맞출 수 있는 시나리오입니다.

2. 시나리오

QA-01 편집 명령과 불변식

편집 중의 문서는 편집 명령으로만 변경되고, 명령의 조합은 테스트로 모두 열거할 수 없습니다. 어떤 순서로 실행해도 불변식이 유지되도록 보장해, 손상된 문서가 만들어지거나 저장되는 것을 막습니다.

부분내용
자극원작성자
자극편집 명령을 임의의 순서로 잇달아 실행한다(삽입, 삭제, 감싸기, 풀기, 이동, Method로 빼기, 실행 취소 · 다시 실행 …)
환경정상 편집 중. 어떤 문서 상태에서든
대상core의 모델과 편집 명령
응답모든 명령의 결과 문서가 불변식을 지킨다. 지킬 수 없는 명령은 거절되고 문서는 그대로다
응답 측정무작위 명령열 테스트에서 불변식 위반 0건 (제안값: 명령열 10,000개 × 길이 200)
목표의 근거위반 0건: 불변식을 어긴 문서는 저장하면 다른 앱에서 열리지 않으므로 하나도 허용할 수 없다. 명령열 10,000개 × 길이 200은 근거 없음(제안값)
  • 아키텍처: 명령은 문서를 받아 새 문서를 반환하는 순수 함수이고, 새 문서를 만들 때마다 불변식을 검사한다. 위반하는 문서는 만들어지지 않는다 → 6. 공통 관심사, ADR-0029, 3. 불변식
  • 테스트: 속성 기반 테스트(property-based test, 예: fast-check). 무작위 문서와 무작위 명령열을 만들어 매 단계 불변식을 검사한다. 실패하면 가장 짧은 반례로 줄여 회귀 테스트에 추가한다. 실행할 때: 모든 커밋(CI)
  • 테스트 ID: packages/core/src/commands/properties.test.ts의 테스트 2개(T-0171 ~ T-0172). packages/editor/src/session/random-keys.test.ts의 테스트 1개(T-0228)

QA-02 깨진 파일 열기

저장 파일은 다른 도구, 동기화 오류, 수동 편집으로 손상될 수 있는 외부 입력입니다. 열 수 없는 파일을 만나도 사용자의 원본을 보존하고 편집기가 비정상 종료되지 않게 합니다.

부분내용
자극원다른 도구, 망가진 동기화, 손으로 수정한 파일
자극모델이 없거나, JSON이 깨졌거나, 불변식을 어긴 모델이 든 파일을 연다
환경모든 배포 대상
대상core의 파일 형식(역직렬화)
응답편집할 수 없다고 알리고 끝난다. 원본 파일에 쓰지 않는다
응답 측정퍼징 입력에서 처리되지 않은 예외 0건, 원본 파일의 바이트 변화 0건
목표의 근거0건: 사용자의 파일을 망가뜨리거나 편집기가 죽는 일은 한 번도 허용할 수 없다(R-FMT-06)
  • 아키텍처: 역직렬화할 때도 편집 명령과 같은 불변식 검사를 한다. 열기는 읽기만 한다 → 5. 버전 관리, 5.2 저장과 열기
  • 테스트: 퍼징(올바른 파일을 무작위로 망가뜨린 입력 + 손으로 만든 깨진 파일 묶음). 열기 뒤 원본 파일의 해시가 같은지 검증한다. 실행할 때: 모든 커밋(짧게), 매일 밤(길게)
  • 테스트 ID: T-0419, T-0424, T-0436. 인수 테스트 AT-06(T-0008)

QA-03 결정적 저장 출력

저장한 다이어그램을 git 같은 버전 관리 시스템으로 관리할 때, 실행 환경에 따라 바이트가 달라지면 내용을 바꾸지 않은 파일에도 diff가 생깁니다. 저장 결과가 문서의 내용과 뷰 상태만으로 결정되게 해 배포 대상, 브라우저, OS의 영향을 배제합니다.

부분내용
자극원작성자
자극같은 문서(같은 내용, 같은 뷰 상태)를 저장한다. 저장하는 사람의 화면 언어는 달라도 된다
환경서로 다른 배포 대상(웹, Obsidian, 데스크톱), 브라우저(Chrome, Edge, Firefox, Safari), OS(Windows, macOS, Linux, Android)
대상core의 레이아웃 · 렌더러 · 파일 형식, fonts
응답같은 바이트의 파일을 쓴다
응답 측정골든 문서 묶음의 저장 결과 SHA-256이 모든 환경에서 100% 일치
목표의 근거100%: 그림을 git 같은 버전 관리 시스템으로 관리할 때 한 바이트만 달라도 바꾸지 않은 그림에 diff가 생긴다(R-NFR-02의 “불필요한 git diff 방지”)
  • 아키텍처: 레이아웃과 렌더러는 순수 함수다. 텍스트 폭은 브라우저에 조회하지 않고 번들 글꼴의 advance 폭 테이블로 계산하고 정수 px로 올린다. JSON의 키 순서와 줄바꿈을 고정하고, 시각 · 기기 정보 · 난수를 쓰지 않는다. 서브세팅은 결정적이다 → 6. 공통 관심사, ADR-0026
  • 테스트: 골든 파일 테스트. 대표 문서 묶음(한글 · 영문 · 기호, 블록 종류 모두, 접힘 · 펴 보기 포함)을 저장해 저장소의 기대 파일과 바이트로 비교한다. 같은 테스트를 Node와 각 브라우저(Playwright)에서 실행한다. 실행할 때: 모든 커밋(Node, Chromium), 출시 전(모든 브라우저와 Obsidian)
  • 테스트 ID: T-0816. packages/core/src/model/site-folded.test.ts의 테스트 22개(T-1324 ~ T-1341). 인수 테스트 AT-10(T-0012)
  • 위험: Firefox와 Safari는 스파이크에서 확인하지 못했다 → 8. 위험과 검증이 필요한 사항

QA-04 저장 왕복 무손실

QA-03이 실행 환경 사이의 동일성이라면, 이 시나리오는 열기와 저장 사이의 동일성입니다. 파일을 열어 보기만 했을 때 파일이 변경되지 않게 해, 버전 관리 시스템을 쓰는 사용자의 커밋에 의도하지 않은 변경이 섞이지 않게 합니다.

부분내용
자극원작성자
자극파일을 열고 아무것도 편집하지 않고 저장한다
환경파일을 만든 앱과 같은 형식 버전
대상파일 형식(역직렬화 → 직렬화)
응답원본과 같은 파일을 쓴다
응답 측정골든 문서 묶음의 왕복(round-trip)에서 바이트 차이 0건
목표의 근거0건: QA-03과 같다. 열고 닫기만 했는데 diff가 생기면 안 된다
  • 아키텍처: QA-03과 같다. 뷰 상태도 파일에 들어 있어 열 때 그대로 복원된다 → ADR-0018
  • 테스트: 골든 파일 왕복 테스트. 실행할 때: 모든 커밋
  • 테스트 ID: T-0329, T-0354, T-0423, T-0429. packages/core/src/model/site-folded.test.ts의 테스트 22개(T-1324 ~ T-1341). 인수 테스트 AT-02(T-0002, T-0022)
  • 알아 둘 것: 화면 언어가 달라도 같다. 그림에 적는 텍스트(“참”, “거짓”, “블록 n개”)는 문서 설정의 언어를 따르기 때문이다(ADR-0041). 그림의 언어가 적히지 않은 옛 파일만, 처음 저장할 때 연 사람의 화면 언어가 더해진다

QA-05 하위 호환성

저장 파일은 앱의 특정 버전보다 오래 남습니다. 파일 형식이 바뀌어도 이전에 저장한 문서를 계속 열 수 있게 해, 앱을 업데이트했다는 이유로 사용자가 문서를 잃지 않게 합니다.

부분내용
자극원작성자
자극옛 형식 버전으로 저장된 파일을 연다
환경형식 버전이 올라간 뒤의 앱
대상파일 형식의 마이그레이션
응답버전별 마이그레이션을 차례로 적용해 지금 형식의 모델로 연다
응답 측정형식 버전 1부터의 모든 골든 파일이 100% 열리고 불변식을 지킨다(프로토타입의 v0 파일은 열지 않는다 → ADR-0035)
목표의 근거100%: 옛 파일 하나가 열리지 않으면 사용자는 그 그림을 잃는다
  • 아키텍처: 형식 버전은 정수, 버전마다 마이그레이션 함수 하나 → 5. 버전 관리
  • 테스트: 형식 버전을 올릴 때마다 그 버전의 골든 파일을 저장소에 고정해 두고(삭제하지 않음), 모두 여는 테스트. 실행할 때: 모든 커밋
  • 테스트 ID: 없음

QA-06 렌더링 이식성

저장 파일은 모델을 내장한 표준 SVG이므로 AriadneNSD가 없는 환경에서도 그대로 표시되어야 합니다. GitHub, 노트, 브라우저에서 읽는 독자가 작성자가 편집기에서 본 것과 같은 다이어그램을 보게 하는 것이 이 저장 형식의 목적입니다.

부분내용
자극원독자
자극저장된 .ns.svg를 연다
환경AriadneNSD도 번들 글꼴도 없는 뷰어: Chrome, Firefox, Safari, GitHub의 파일 보기, Obsidian(플러그인 없음), Google Drive 미리보기
대상저장된 SVG 파일
응답편집기 화면의 문서 레이어와 같은 그림이 보인다. 텍스트는 텍스트로 남는다(선택 · 검색 가능)
응답 측정SVG 1.1 검증 오류 0건. 빠진 문자(대체 글꼴로 그려진 문자) 0개. 기준 그림과의 픽셀 차이 1% 이하(제안값, 안티앨리어싱 차이를 허용)
목표의 근거0건 · 0개: 우리 코드가 없는 뷰어(GitHub · 노트 · 인쇄)에서 그림이 달라지면 저장 형식의 뜻이 없다. 픽셀 차이 1%는 근거 없음(제안값: 브라우저마다의 안티앨리어싱만 허용하려는 값)
  • 아키텍처: 쓰인 문자만 남긴 서브셋 글꼴과 문서 테마의 색을 파일 안에 포함한다. 편집 중에만 보이는 표시는 오버레이 레이어라 저장되지 않는다 → ADR-0026, ADR-0018, 5.2 저장과 열기
  • 테스트: 시각 회귀 테스트. 골든 문서를 각 브라우저에서 이미지로 열어(Playwright 스크린샷) 기준 그림과 픽셀로 비교한다. SVG 1.1 검증기로 문법을 검증한다. GitHub · Drive · Obsidian은 수동 점검표. 실행할 때: 모든 커밋(Chromium), 출시 전(나머지)
  • 테스트 ID: 인수 테스트 AT-08(T-0010)

QA-07 편집 반응 시간

구조 편집기는 편집할 때마다 레이아웃과 렌더링을 다시 수행하므로, 문서가 커질수록 입력 지연이 드러나기 쉽습니다. 큰 문서에서도 입력이 즉시 반영되어 작성자의 작업 흐름이 끊기지 않게 합니다.

부분내용
자극원작성자
자극블록 하나의 텍스트를 편집하거나 블록을 삽입한다
환경블록 500개 문서. 기준 기기(제안값: 4년 된 보급형 노트북, 예: 4코어 CPU · 8 GB, Chrome)
대상편집 명령 → 레이아웃 → 렌더링 → 화면 갱신
응답바뀐 그림이 화면에 보인다
응답 측정입력부터 화면 갱신까지 p95 100ms 이하
목표의 근거100ms: 사람이 “바로 반응했다”고 느끼는 한계로 널리 쓰는 값이다(Nielsen의 응답 시간 세 한계 0.1 · 1 · 10초 가운데 0.1초). 블록 500개는 R-NFR-03의 값이고, 그 자체의 근거는 적혀 있지 않다
  • 아키텍처: 불변 문서와 구조적 공유로 바뀌지 않은 하위 트리를 구분해 낼 수 있다. 증분 레이아웃(메모이제이션)을 할지는 측정해서 정한다 → ADR-0029, 4. 성능
  • 테스트: 성능 벤치마크. 블록 500개 문서에서 대표 명령 20가지를 각 100번 실행해 p95를 측정한다. Node에서 core만(레이아웃 + 렌더링, 목표의 절반인 50ms 이하를 제안)과 브라우저에서 화면 갱신까지(Playwright, 성능 타임라인)로 나눈다. 실행할 때: 모든 커밋(Node, 결과를 기록해 느려지면 알림), 출시 전(기준 기기)
  • 테스트 ID: T-1175, T-1176, T-0487, T-1152, T-1153, T-1159, T-1160, T-0517. packages/core/src/layout/fold-layout.test.ts의 테스트 26개(T-1113 ~ T-1126). apps/web/src/perf/perf-segments.test.ts의 테스트 3개(T-1177 ~ T-1179). 인수 테스트 AT-05(T-0007, T-1147, T-1148, T-1155, T-1156)
  • 측정 구간: 입력부터 화면까지의 경로를 C&C 뷰의 커넥터로 나눈다. 점검 모드(9. 점검 모드)가 명령마다 구간별 p95를 보인다. 예산은 기준 기기에서의 p95이고, 합격은 지금처럼 전체 p95로만 가른다(구간 예산은 어디를 고칠지 찾는 기준).
구간커넥터시작 → 끝 (코드의 자리)예산검증
입력C-01 ~ C-04키 이벤트 → 명령 실행 직전. 키 처리(EditorSession.handleKey · readKey)와 아래 구간에 들지 않은 동기 작업. 키 처리 시간에서 측정한 구간을 뺀 나머지2msT-1178
편집 명령C-04 · C-05명령의 실행(registry.run의 spec.run, 글자는 EditorSession.commitEditing)에서 아래 구간을 뺀 것. 새 내용 · 색인 · 선택을 만듦8msT-1175
불변식 검사C-05EditorSession.apply의 checkInvariants4msT-1175
레이아웃C-07 · C-08renderDoc의 layout (글자 폭 포함)12msT-1176, T-0517
그림C-09renderDoc의 buildScene + toSvg14msT-1176, T-0517
알림C-06 · C-11EditorSession.setState가 호출하는 리스너(셸에 알림, 인라인 에디터, 다음 프레임 예약)10msT-1175
DOM 반영C-10첫 프레임의 CanvasView.draw: 문서 레이어의 innerHTML, 오버레이, 선택 상자20msT-1175
브라우저(우리 코드 밖)그 뒤 두 번째 프레임까지: 스타일 · 레이아웃 · 페인트와 화면 주사율의 기다림. 그 시간에서 측정한 구간을 뺀 나머지30msT-1178
  • 예산의 근거: core의 구간(편집 명령 ~ 그림)은 측정값에 여유를 두고 38ms, 화면 쪽(알림 · DOM 반영 · 브라우저)에 60ms를 둔다. 브라우저 구간은 60Hz 화면의 한 프레임(17ms)을 기다리는 시간을 품어야 해서 가장 크다. 레이아웃 12 · 그림 14ms는 Node의 벤치마크 한도(각 p99 20ms, T-0517)보다 좁다. 브라우저에서 기준 기기의 값이기 때문이다.
  • 측정값 (2026-11-17, 개발 기계의 Chromium, 명령마다 30번): 감속 없이는 모든 명령이 p95 34 ~ 35ms로 합격이고, core의 구간을 다 더해도 4ms 아래다. CPU 4배 감속(기준 기기 대신)에서는 8가지 모두 불합격(p95 173 ~ 267ms)이다. core의 구간은 각 15ms 아래로 예산 안이고, 시간은 DOM 반영(27 ~ 136ms)과 브라우저(53 ~ 199ms)가 차지한다. 문서 레이어를 전체 교체하고 브라우저가 블록 500개의 SVG를 다시 레이아웃 · 페인트하는 시간이다. 그래서 증분 레이아웃보다 화면 쪽(바뀐 곳만 DOM에 반영하기)이 고칠 곳이다 → MVP 개발
  • 열린 질문: “500개”를 문서의 블록 수로 셀지, 펴 보인 호출 블록까지 그려지는 블록 수로 셀지 → 8. 위험과 검증이 필요한 사항

QA-08 여는 시간 (제안)

파일을 여는 시간은 작성자가 문서로 돌아올 때마다 겪는 대기 시간입니다. 열 때 모델만 읽고 레이아웃과 렌더링을 새로 수행하는 구조가 큰 문서에서도 충분히 빠른지 확인합니다.

부분내용
자극원작성자
자극파일을 연다
환경블록 500개 문서, QA-07의 기준 기기
대상역직렬화 → 마이그레이션 → 레이아웃 → 렌더링
응답편집할 수 있는 화면이 보인다
응답 측정1초 이하 (제안값)
목표의 근거1초: 기다리는 동안 생각의 흐름이 끊기지 않는 한계(Nielsen의 1초)에서 가져온 제안값
  • 아키텍처: 열 때는 모델 JSON만 읽고 그림 부분과 서브셋 글꼴은 읽지 않는다 → 5.2 저장과 열기
  • 테스트: QA-07과 같은 벤치마크에 열기를 더했다. Node에서 core만: 저장한 파일(블록 500개, 실제 서브셋 글꼴만 한 글꼴 자리를 넣음)을 열어 검사하고 레이아웃 · 그리기까지 p99 100ms 이하. 화면에 붙여 편집할 수 있게 되기까지는 브라우저에서 측정한다(아직 없음). 실행할 때: 모든 커밋
  • 테스트 ID: T-0540

QA-09 파일과 번들의 크기 (제안)

저장 파일에는 서브셋 글꼴이, 편집기 번들에는 블록 글꼴이 포함되어 크기가 커질 요인이 구조적으로 존재합니다. 저장소에 커밋되는 파일과 사용자가 다운로드하는 번들이 과도하게 커지지 않도록 상한을 둡니다.

부분내용
자극원작성자
자극문서를 저장한다 / 편집기를 내려받는다
환경서로 다른 한글 300자를 쓴 블록 100개 문서 / 첫 방문
대상저장 파일 / 웹 번들, Obsidian main.js
응답파일과 번들이 작다
응답 측정저장 파일 300 KB 이하, Obsidian main.js 3 MB 이하 (둘 다 제안값)
목표의 근거근거 없음(제안값)
  • 아키텍처: 편집기에는 기본 블록 글꼴 D2Coding 보통 굵기 하나를 번들한다. 한자를 뺀 문자(라틴 · 유럽 확장, 한글, 그리스, 키릴, 가나)를 포함하고, woff2로 약 328 KB다 → ADR-0034. 웹은 이것을 문자 범위의 슬라이스 38개로 나눠 화면에 나온 문자의 슬라이스만 받는다 → ADR-0040. 저장 파일에는 쓰인 문자만 추린 서브셋 글꼴을 포함한다. 서브셋이 300 KB 안에 드는지는 정하지 않음 → 8. 위험과 검증이 필요한 사항, 02-layout
  • 테스트: 번들 사이즈 체크(bundle size budget, 빌드 산출물과 골든 문서의 저장 결과 크기를 측정하고, 넘으면 실패). 실행할 때: 모든 커밋
  • 테스트 ID: T-0355. 테스트가 아닌 검사: 번들 사이즈 체크 apps/web/scripts/check-size.mjs (CI의 웹 빌드 뒤)

QA-10 셸 확장성

AriadneNSD는 하나의 편집기를 여러 배포 대상에 제공합니다. 새 배포 대상을 추가할 때 공통 코드를 변경하지 않게 해, 이미 출시한 배포 대상에 회귀가 생기지 않게 합니다.

부분내용
자극원개발자
자극새 배포 대상의 셸을 만든다(예: Confluence, VSCode)
환경설계 · 개발 중
대상패키지 구조, editor와 셸의 인터페이스
응답새 셸 패키지 안에서 필요 인터페이스 둘을 구현하고, 제공 인터페이스를 호스트에 등록하는 것으로 끝난다
응답 측정core · editor · fonts의 변경 0줄
목표의 근거0줄: 시나리오의 뜻 그대로다. 배포 대상이 일곱이라(01-requirements) 셸마다 공통 코드를 고치면 앞의 대상이 깨진다
  • 아키텍처: 필요 인터페이스 DocumentStore · SettingsStore, 제공 인터페이스 CommandRegistry · SettingsSchema. 의존은 셸 → editor → core 한 방향 → 4.2 editor와 셸의 인터페이스, ADR-0031, ADR-0033
  • 테스트: 정적 분석(의존 규칙 검사, 예: dependency-cruiser). core가 editor나 apps/*를 import하면, editor가 apps/*를 import하면 실패. 테스트 더블 셸(메모리 안의 DocumentStore)로 editor의 테스트를 실행한다. 새 셸을 붙인 PR에서 packages/의 변경을 검증한다. 실행할 때: 모든 커밋
  • 테스트 ID: packages/editor/src/create-editor.test.ts의 테스트 52개(T-1175 ~ T-0820). 테스트가 아닌 검사: 의존 방향 검사 dependency-cruiser (pnpm deps)
  • 알아 둘 것: IDE 플러그인은 원본이 소스 코드라 예외일 수 있다 → 7. 배포 구성

QA-11 렌더링 백엔드 교체 용이성

지금 화면은 저장 파일과 같은 SVG를 DOM에 전체 교체하는 방식이고, 성능 측정 결과에 따라 변경된 블록만 갱신하는 방식으로 바꿀 수 있습니다. 렌더링 백엔드를 교체할 때의 변경 범위를 구현체 하나로 제한해 core와 저장 결과를 보호합니다.

부분내용
자극원개발자
자극화면 렌더링을 “SVG 문자열 삽입”에서 UI 프레임워크로 그리기로 바꾼다
환경출시 뒤
대상editor의 렌더링 백엔드
응답백엔드 구현체 하나만 바뀐다
응답 측정core의 변경 0줄. QA-03 · QA-06의 골든 파일 바이트 변화 0건. 히트 테스트와 선택 오버레이의 테스트가 그대로 통과
목표의 근거0줄 · 0건: 시나리오의 뜻 그대로다. 저장 파일이 바뀌면 QA-03을 어긴다
  • 아키텍처: 씬 빌드와 SVG 출력을 나눈 렌더러, 렌더링 백엔드 인터페이스 하나, DOM이 아니라 레이아웃 결과로 하는 히트 테스트 → ADR-0030, 4.3 의존 규칙
  • 테스트: 히트 테스트와 오버레이 위치를 레이아웃 결과만으로 확인하는 단위 테스트(DOM 없음). 렌더링 백엔드 인터페이스에 대한 계약 테스트(같은 씬 → 같은 화면 요소). 실행할 때: 모든 커밋
  • 테스트 ID: 없음

QA-12 블록 종류 추가

블록 종류는 제품이 발전하면서 늘어납니다(P2의 탈출, 병렬 등). 블록을 추가할 때의 변경을 core와 키 표로 한정하고, 이미 저장한 파일과의 호환성을 유지합니다.

부분내용
자극원개발자
자극새 블록 종류를 추가한다(예: P2의 탈출, 병렬)
환경출시 뒤
대상core의 모델 · 명령 · 레이아웃 · 씬 빌드
응답바뀌는 곳은 core의 그 블록에 대한 부분과 키 표뿐이다
응답 측정셸의 변경 0줄. 옛 파일은 그대로 열린다(QA-05)
목표의 근거0줄: 시나리오의 뜻 그대로다
  • 아키텍처: 블록은 판별 유니온(kind)이고, TypeScript의 완전성 검사(exhaustiveness check)가 손볼 곳을 모두 알려 준다. 명령은 CommandRegistry로 셸에 자동으로 나타난다 → 1.4 블록, ADR-0033
  • 테스트: 컴파일러의 완전성 검사(never), QA-05의 옛 파일 테스트, QA-01의 무작위 명령열에 새 블록을 추가함. 실행할 때: 모든 커밋
  • 테스트 ID: 테스트가 아닌 검사: TypeScript의 완전성 검사 (pnpm typecheck)

QA-13 화면 언어 추가

화면 언어는 영어와 한국어로 시작하며 이후 추가될 수 있습니다. 문자열을 코드에서 분리해, 번역자가 코드를 수정하지 않고 메시지 카탈로그만으로 언어를 추가할 수 있게 합니다.

부분내용
자극원번역자
자극화면 언어 하나를 추가한다
환경출시 뒤
대상editor와 core의 메시지 카탈로그
응답카탈로그 파일을 추가하는 것으로 끝난다
응답 측정코드의 변경 0줄(언어 목록 한 줄 제외). 화면에 카탈로그 밖의 텍스트 0개
목표의 근거0줄: 시나리오의 뜻 그대로다(번역은 카탈로그만 고친다)
  • 아키텍처: 화면의 텍스트는 editor, 그림에 적는 텍스트는 core가 한 곳씩에서 관리한다 → 6. 공통 관심사
  • 테스트: 정적 분석: UI 코드(.tsx)의 JSX에 쓴 글자와 title · aria-label · placeholder · alt 속성의 글자를 ESLint가 차단한다(번역하지 않는 제품 이름과 확장자는 이름 붙은 상수로). 카탈로그 넷(그림 · 엔진 · UI · 웹 셸)이 언어마다 모든 키를 가지는지는 타입 검사가 검증한다. 단위 테스트는 빈 문자열이 없는지, {name} 자리표시가 언어마다 같은지, 엔진과 UI 카탈로그에 같은 키가 없는지 검증한다. 언어 목록은 core의 locales 한 줄이다. 실행할 때: 모든 커밋
  • 테스트 ID: T-0530, T-1157. packages/core/src/i18n/messages.test.ts의 테스트 2개(T-0531 ~ T-0532). packages/editor/src/i18n/messages.test.ts의 테스트 3개(T-0533 ~ T-0535). 테스트가 아닌 검사: JSX에 쓴 텍스트 금지 규칙 (eslint.config.js, pnpm lint), 카탈로그마다 모든 언어의 키 (pnpm typecheck)

QA-14 DOM 독립 테스트 용이성

core와 fonts는 모든 배포 대상이 공유하는 핵심 로직입니다. 브라우저 없이 빠르게 테스트할 수 있게 해 커밋마다 검증하고, 특정 실행 환경에 종속되는 것을 구조적으로 막습니다.

부분내용
자극원개발자, CI
자극core · fonts의 테스트를 실행한다
환경브라우저 없는 Node
대상core, fonts
응답모든 테스트가 실행된다
응답 측정core · fonts에서 DOM · 브라우저 API를 쓰는 곳 0곳. 단위 테스트 전체 1분 이하(제안값)
목표의 근거0곳: 시나리오의 뜻 그대로다. 1분은 근거 없음(제안값: 커밋마다 실행해도 작업이 끊기지 않을 시간)
  • 아키텍처: core와 fonts는 DOM과 브라우저 API에 의존하지 않는다 → 4.3 의존 규칙
  • 테스트: core · fonts의 TypeScript 설정에서 lib에 dom을 빼서, 쓰면 컴파일이 실패하게 한다. CI가 Node에서만 단위 테스트를 실행한다. 실행할 때: 모든 커밋
  • 테스트 ID: 테스트가 아닌 검사: core · fonts의 tsconfig에 dom이 없음 (pnpm typecheck)

QA-15 키보드 접근성

마우스를 쓸 수 없는 사용자와 키보드 조작을 선호하는 개발자 모두 주요 작업을 끝까지 수행할 수 있어야 합니다. 한 단계라도 마우스가 필요하면 그 작업 전체가 불가능해지므로, 모든 명령과 포커스를 키보드로 접근할 수 있게 합니다.

부분내용
자극원마우스를 쓰지 않는 작성자
자극UC-01 새로 만들기, UC-02 열기, UC-03 편집, UC-05 훑어보기, UC-06 저장을 한다
환경웹, 데스크톱, Obsidian
대상editor의 키 입력과 포커스
응답마우스 없이 끝낸다. 지금 어디에 있는지 항상 보인다
응답 측정위 유즈케이스의 인수 시나리오가 키 입력만으로 100% 통과. 포커스가 보이지 않는 순간 0번
목표의 근거100% · 0번: 키보드만 쓰는 사람에게는 한 단계만 차단되어도 그 일을 끝낼 수 없다
  • 아키텍처: 모든 명령은 CommandRegistry에 있고 키 표 하나로 키에 잇는다. 메뉴와 툴바도 같은 레지스트리에서 나온다 → ADR-0033, 03-keymap
  • 테스트: E2E 테스트(Playwright, 키 입력만). 레지스트리의 명령마다 키나 키로 열 수 있는 메뉴가 있는지 보는 테스트. 실행할 때: 모든 커밋(웹), 출시 전(Obsidian, 데스크톱)
  • 테스트 ID: 인수 테스트 AT-04(T-0004, T-0005, T-0006)

QA-16 고대비

저시력 사용자도 블록의 구조와 텍스트를 구분할 수 있어야 하고, 흑백으로 인쇄한 다이어그램도 읽을 수 있어야 합니다. 색 대비를 주관적 판단이 아니라 WCAG 기준으로 검증합니다.

부분내용
자극원저시력 작성자
자극고대비 화면 색, 흑백 팔레트를 선택한다
환경모든 배포 대상
대상화면 색과 테마의 디자인 토큰
응답텍스트와 선이 배경과 뚜렷이 구분된다
응답 측정텍스트와 배경의 대비 7:1 이상(WCAG AAA, 제안값), 선과 배경은 3:1 이상
목표의 근거7:1은 WCAG 2.x의 텍스트 대비 AAA, 3:1은 WCAG 2.1의 비텍스트 대비(1.4.11) 기준이다
  • 아키텍처: 색은 토큰 맵으로 렌더러에 전달하고, 테마와 화면 색은 다른 맵이다 → 6. 공통 관심사, 8. 테마
  • 테스트: 토큰 표에서 쌍(텍스트 · 배경, 선 · 배경)의 대비를 계산하는 단위 테스트. 지금은 밝은 기본 테마만 있어, 그 테마의 3.3절 기준(텍스트 4.5:1, 선 3:1)을 종이와 블록 배경 여섯 위에서 검증한다. 고대비 화면 색과 흑백 인쇄 팔레트가 생기면 같은 테스트에 이 시나리오의 기준(7:1)으로 더한다. 실행할 때: 모든 커밋
  • 테스트 ID: packages/core/src/render/theme.test.ts의 테스트 11개(T-0536 ~ T-0986)

QA-17 저장 실패

저장은 권한, 디스크 용량, 네트워크처럼 앱이 제어할 수 없는 요인으로 실패할 수 있습니다. 실패해도 편집한 내용을 유지하고 실패 사실을 알려, 사용자가 작업을 잃지 않고 다시 저장할 수 있게 합니다.

부분내용
자극원호스트 플랫폼
자극저장 중 쓰기가 실패한다(권한 없음, 디스크 가득, 네트워크 끊김)
환경모든 배포 대상
대상저장 흐름(editor → DocumentStore)
응답실패를 알리고, 편집기의 내용과 “저장 안 됨” 표시를 그대로 둔다
응답 측정편집한 내용의 손실 0건. 원본 파일이 온전히 남는지는 미결정 → 02-use-cases
목표의 근거0건: 사용자가 한 편집을 잃는 일은 한 번도 허용할 수 없다(UC-06의 최소 보장)
  • 아키텍처: 문서는 불변이고 editor가 갖고 있으므로, 쓰기 실패는 문서를 바꾸지 않는다. DocumentStore의 쓰기는 실패를 던지지 않고 값(WriteResult: cancelled · denied · failed)으로 반환한다 → 6. 셸과의 연결
  • 테스트: 실패하는 테스트 더블 DocumentStore로 저장하고, 문서 · “저장 안 됨” 표시 · 알림을 보는 테스트. 실행할 때: 모든 커밋
  • 테스트 ID: 인수 테스트 AT-07(T-0009, T-0023)

QA-18 모바일 시작 시간

웹은 설치 없이 접근하는 진입점이고, 휴대폰으로 처음 방문한 사용자는 저사양 기기와 느린 네트워크에서 앱을 처음 경험합니다. 첫 방문의 대기 시간을 제한해 편집 화면이 보이기 전에 사용자가 이탈하지 않게 합니다.

부분내용
자극원휴대폰으로 처음 온 사람
자극웹의 주소를 연다
환경캐시가 빈 브라우저. 기준: CPU 4배 느림과 “slow 4G”(왕복 150 ms, 내려받기 1.6 Mbps, Lighthouse의 모바일 측정과 같음)
대상웹의 첫 내려받기(HTML · JS · 화면용 블록 글꼴)와 시작
응답편집 화면이 보이고, 이어서 블록 글꼴로 바뀐다
응답 측정편집 화면 3초 이하, 블록 글꼴까지 5초 이하 (2026-11-01에 메인테이너가 확인. 그날 측정값은 CPU 6배에서 약 1.8초와 4초)
목표의 근거3초: 모바일 페이지가 3초를 넘으면 떠나는 사람이 크게 는다는 조사(Google, 2016)에서 흔히 쓰는 값. 5초는 근거 없음(메인테이너가 확인한 값)
  • 아키텍처: 편집 화면은 블록 글꼴을 기다리지 않고 그린다(텍스트 폭은 글꼴 파일이 아니라 번들한 advance 폭 테이블로 계산하므로 레이아웃은 같다). 저장용 TTF와 wasm은 첫 편집 뒤에 받는다 → 5. 배포, ADR-0026
  • 테스트: E2E(Playwright, Android 폰 흉내 + CPU · 네트워크 감속). 편집 화면과 블록 글꼴이 보인 때를 재어 합격 기준과 견준다. 원인을 나눠 보는 재기 스크립트 src/apps/web/scripts/measure-startup.mjs. 실행할 때: 모든 커밋(흉내), 출시 전(실제 휴대폰)
  • 테스트 ID: apps/web/e2e/mobile.spec.ts의 테스트 6개(T-0287 ~ T-0523)

QA-19 초기화 장애 시 빈 화면 방지

웹 앱은 사용자의 브라우저와 기기 환경을 통제할 수 없어 초기화 중 저장소 응답 지연이나 스크립트 오류가 발생할 수 있습니다. 빈 화면은 사용자에게 아무 정보도 주지 못하고 결함 분석도 어렵게 하므로, 편집 화면으로 계속하거나 원인을 표시합니다.

부분내용
자극원브라우저
자극시작하는 동안 브라우저 저장소(IndexedDB)가 응답하지 않거나, 스크립트가 오류를 낸다
환경웹. 어떤 브라우저 · 기기에서든
대상웹의 시작(index.html, main.tsx)
응답저장소가 응답하지 않으면 메모리로 대신하고 편집 화면을 띄운다. 오류면 멈춘 단계 · 오류 · 브라우저 정보를 화면에 적는다
응답 측정저장소가 응답하지 않을 때 편집 화면까지 3초 + 시작 시간 이하. 빈 화면으로 남는 경우 0번(어떤 경우든 15초 안에 편집 화면이나 이유가 보인다)
목표의 근거3초는 저장소 열기의 시간 제한(06-web)이다. 15초는 근거 없음(제안값)
  • 아키텍처: 저장소 열기의 시간 제한(3초)과 메모리 대체, 시작 화면과 시작 단계(data-boot-step) → 2. 로컬 백업과 자동 저장, 7. 웹에서의 화면
  • 테스트: E2E(응답하지 않는 indexedDB.open, 시작 중 오류를 흉내). 실행할 때: 모든 커밋
  • 테스트 ID: apps/web/e2e/boot.spec.ts의 테스트 2개(T-0278 ~ T-0279)

QA-20 모바일 사용성

웹은 휴대폰 브라우저에서도 접근할 수 있으므로, 데스크톱을 전제로 한 화면 배치와 포인터 조작만으로는 부족합니다. 좁은 화면과 터치 입력에서도 문서를 열고 기본 편집을 수행할 수 있게 합니다.

부분내용
자극원휴대폰을 쓰는 작성자
자극예제를 열고, 블록을 넣고, 블록을 선택한다
환경Android의 Chrome, 세로 화면(폭 약 400px), 터치
대상웹의 좁은 화면 배치와 터치 입력
응답좁은 화면 배치(☰ 메뉴, 여러 줄의 툴바)로 보이고, 탭으로 끝낸다
응답 측정위 흐름이 탭만으로 100% 통과(문자 입력은 화면 키보드)
목표의 근거100%: 시나리오의 뜻 그대로다
  • 아키텍처: 좁은 화면 배치 → 화면 배치, MB1
  • 테스트: E2E(Playwright의 Android 폰 흉내: 화면 크기 · 터치 · user agent). 실제 휴대폰은 출시 점검표. 실행할 때: 모든 커밋(흉내), 출시 전(실제 휴대폰)
  • 테스트 ID: apps/web/e2e/mobile.spec.ts의 테스트 6개(T-0287 ~ T-0523)

QA-21 비신뢰 공유 링크 입력 처리

공유 링크는 문서 내용을 URL에 담으므로, 링크를 여는 것은 누구나 만들 수 있는 외부 입력을 처리하는 일입니다. 손상되거나 악의적으로 구성한 링크로부터 편집기와 사용자가 작업 중인 문서를 보호합니다.

부분내용
자극원링크를 만든 누구나(꾸민 사람도)
자극잘리거나 바뀐 공유 링크, 아주 긴 링크, 작게 꾸렸지만 풀면 아주 커지는 링크(zip bomb), 모델이 파일의 규칙을 어기는 링크를 연다
환경웹. 페이지를 처음 열 때나, 열린 탭의 주소창에 붙여 넣을 때
대상웹 셸의 공유 링크 읽기(apps/web/src/files/share-link.ts)와 모델 파서
응답링크를 열지 않고 이유(손상 · 너무 큼 · 더 새 버전 · 이 브라우저가 풀 수 없음)를 알린 뒤 평소처럼 시작한다. 지금 문서는 바뀌지 않는다
응답 측정편집기가 죽는 경우 0번. 1 MB가 넘는 링크는 풀지 않음. 푼 크기가 16 MB를 넘는 순간 멈춤
목표의 근거1 MB는 브라우저가 주소로 받는 한도(Chromium 2 MB, 다른 브라우저는 더 작은 경우가 있음)의 안쪽이다(06-web). 16 MB는 근거 없음(제안값: 링크가 메모리를 다 쓰지 않게 하는 상한)
  • 아키텍처: 길이를 먼저 보고, 스트림으로 풀며 크기를 세고, 모델은 파일과 같은 검증 파서를 거친다 → ADR-0043, 3. 공유 URL과 보기 모드
  • 테스트: 단위 테스트(잘린 · 바뀐 · 긴 링크, zip bomb, 봉투가 틀린 JSON, 모델 검증 실패)와 E2E(손상된 링크로 페이지를 엶). 실행할 때: 모든 커밋
  • 테스트 ID: T-1140

3. 테스트 전략

시나리오의 테스트를 종류별로 모으면 다음과 같습니다. 테스트 기반은 MVP 코드와 함께 만들었습니다(속성 기반 테스트 src/packages/core/src/format/round-trip.test.ts, 골든 파일 src/packages/core/golden/, 의존 규칙 src/.dependency-cruiser.cjs, 성능 벤치마크 src/packages/core/src/render/render.bench.ts). 표의 “매일 밤” 실행은 아직 없습니다. 도구는 ADR-0038에서 정했고, 계층마다의 쓰임과 인수 테스트는 02-test-architecture에 있습니다.

테스트 종류시나리오도구실행할 때
속성 기반 테스트QA-01, QA-12fast-check모든 커밋
퍼징QA-02fast-check, 깨진 파일 묶음모든 커밋(짧게), 매일 밤
골든 파일(바이트 비교)QA-03, QA-04, QA-05, QA-11저장소의 기대 파일 + SHA-256모든 커밋
시각 회귀QA-06Playwright 스크린샷 + 픽셀 비교모든 커밋(Chromium), 출시 전
성능 벤치마크QA-07, QA-08Vitest bench, Playwright 성능 타임라인모든 커밋(기록), 출시 전(기준 기기)
번들 사이즈 체크QA-09빌드 산출물 크기 검사모든 커밋
정적 분석QA-10, QA-13, QA-14dependency-cruiser, ESLint, tsconfig의 lib모든 커밋
계약 테스트QA-10, QA-11, QA-17테스트 더블 DocumentStore, 렌더링 백엔드 계약모든 커밋
E2EQA-15, QA-19, QA-20, QA-21Playwright(키 입력만, 폰 흉내와 터치)모든 커밋(웹), 출시 전
시작 시간QA-18Playwright(폰 흉내 + CPU · 네트워크 감속)모든 커밋(흉내), 출시 전(실제 휴대폰)
단위 테스트QA-16, QA-21Vitest모든 커밋
수동 점검표QA-03, QA-06 (Obsidian, GitHub, Drive, Safari), QA-18 · QA-20 (실제 휴대폰)출시 점검표출시 전

4. 미결정 사항

미결정

  • 제안값의 확인: QA-01의 명령열 크기, QA-06의 픽셀 차이 1%, QA-07의 기준 기기, QA-08의 1초, QA-09의 300 KB와 3 MB, QA-14의 1분, QA-16의 7:1
  • QA-07: “블록 500개”를 문서의 블록 수로 셀지, 그려지는 블록 수로 셀지
  • 보안과 개인 정보의 시나리오: AI 대화창의 API 키, 광고 스크립트와 한 페이지에 있는 것(6. 미결정 사항). 그 기능들(P3)을 설계할 때 추가한다. 공유 링크는 QA-21