안내 캡처 34장을 두 번에 나눠 다시 찍었다

시스템 이용안내는 글이 아니라 그림으로 설명하는 문서입니다. 표준데이터 탭, OID 탭, 물리 아키텍처 탭마다 실제 화면 캡처가 슬라이드로 들어가요. 여기에 신청서 작성 예시 PDF까지 있는데, 이것도 단계마다 찍은 화면을 이어 붙인 문서입니다.

그래서 화면을 고치면 문서가 같이 낡습니다. 9월에 두 번 다시 찍었어요. 이용안내만 세면 9월 4일에 18장, 9월 9일 밤에 16장, 합쳐서 34장입니다. 신청서 작성 예시 PDF 캡처도 두 번 모두 따로 다시 찍었고(9월 9일에는 11장), 그 사이 9월 9일 오후에는 진행 단계 칩 변경으로 같은 8장을 두 차례(16:04·16:47) 찍었다가 팀원의 원복으로 원본이 되돌아온 회차도 있었습니다.

이 글은 캡처를 어떻게 다시 찍었는지가 아니라, 무엇을 찍을지 정하는 일이 왜 자동화가 안 되는지에 대한 이야기예요.

1차 — 역할 이름이 낡아 있었다

9월 초에 권한 체계가 ISO 14817-2 역할로 정리됐습니다(팀원 작업). 안내 문서에는 옛 이름이 그대로 남아 있었어요. 이용안내 7단계 그림의 담당 칩이 관리자·심의위원회였는데 실제 표시명은 데이터 스튜어드·변경통제위원회입니다.

이름만 바꾸면 되는 일이 아니었습니다. 사용자 안내에 어떤 역할을 실을 것인가를 먼저 정해야 했어요. 시스템 역할은 여덟인데 안내에 넷만 실었습니다. 기준은 하나예요 — 사용자 화면에 이름이 나오는 역할만 싣는다.

등록관리자·집행위원회·등록기관 관리자·슈퍼 관리자는 관리 페이지에서만 쓰이니 뺐습니다. 같은 기준으로 물리 아키텍처 탭의 담당 관리자 역할 카드와 「서비스·시나리오 등록」 슬라이드도 지웠어요. 사용자가 못 가는 화면을 사용자 안내가 설명하고 있으면 안 됩니다.

지운 슬라이드가 되살아나지 않도록 물리 아키텍처 슬라이드를 4장으로 잠그는 e2e 스펙을 뒀습니다. 안내에서 뭘 뺐다는 사실은 문서에 적어도 잘 안 읽히지만, 테스트로 적어 두면 되살릴 때 빨간불이 켜져요.

역할 안내 탭에는 「역할은 어떻게 받나」를 새로 넣었습니다. 소속 기관·담당 범위·기간, 자기 심사 금지, 이력 보존, 소속이 바뀌면 회수. 역할 이름만 알려 주고 받는 방법을 안 적어 두면 결국 문의로 돌아옵니다.

촬영은 스펙이 한다

캡처는 손으로 찍지 않습니다. Playwright 스펙이 전부 찍어요. 콘텐츠 영역만 요소 캡처해서 헤더·브레드크럼·푸터를 빼고, 1200px 폭에 2배 배율로 찍습니다.

async function shoot(page, name) {
  const el = page.locator(CONTENT).first();
  await expect(el).toBeVisible({ timeout: 15000 });
  await el.screenshot({ path: `${OUT}/${name}` });
}

여기서 판단이 들어간 건 기다리는 방식입니다. 캡처 스펙은 일반 테스트와 목적이 달라요. 테스트는 기대한 상태가 아니면 실패하고 멈춰야 하지만, 캡처는 일단 찍어 놓고 사람이 보는 게 낫습니다. 한 장이 덜 뜬 상태였다고 나머지를 안 찍을 이유가 없어요.

// 이상적 상태 도달을 기다리되, 실패해도 캡처는 남겨 자가검수 대상으로 삼는다
async function soft(locator, label) {
  try {
    await locator.first().waitFor({ state: "visible", timeout: 12000 });
  } catch {
    warnings.push(`  ⚠ ${label}`);
  }
}

못 기다린 항목은 모아서 마지막에 [미확인 항목]으로 뱉습니다. 실패가 아니라 검수 목록이에요.

디버그 툴바에는 이보다 앞선 8월 캡처 때 데었습니다. dev 전용 툴바가 그림에 찍혀서 숨기는 스크립트를 넣었는데, DOMContentLoaded를 기다렸더니 늦었어요. 물리 아키텍처 구성도가 편집기를 iframe으로 물고 오는데 그 프레임의 툴바가 그림 위에 그대로 찍혔습니다. 그래서 즉시 주입하게 바꿨더니, 이번엔 루트 요소가 아직 없는 순간에 스크립트가 통째로 죽어 툴바가 또 찍혔어요. 그 자리에 남긴 주석입니다.

      // ⚠️ documentElement 가 아직 없을 수 있다 — 여기서 throw 하면 init script 전체가 죽어
      //    아래 리스너 등록까지 날아가고 툴바가 그대로 찍힌다(실제로 한 번 그랬다).
      const root = document.head || document.documentElement;

있는 요소에 먼저 붙이고, 뒤늦게 붙는 프레임을 위해 load에서도 한 번 더 겁니다.

2차 — 같은 날 화면이 세 번 바뀌었다

9월 9일에는 하루 동안 바뀐 것들이 한꺼번에 캡처로 내려왔습니다.

마지막 줄이 재미있는 자리입니다. 1차 때 dev 카탈로그 탭은 0건이 정상이어서 빈 화면이 안내에 실려 있었어요. "데이터가 생기면 다시 찍는다"고 적어 뒀고, 이번에 그게 해소됐습니다. 안내 문서가 개발 환경의 데이터 상태를 그대로 물려받는다는 뜻이기도 해요.

촬영 스펙의 마커도 화면을 따라 손봐야 했습니다. 접히던 검색 조건 패널이 필터줄 개편으로 사라져서, 기다리는 대상을 필터줄의 마지막 칸으로 바꿨어요. 셀렉트 안의 전체 상태는 닫힌 상태에서 안 보이니 마커로 쓸 수 없습니다. 상세 화면 구획 이름도 기본 항목에서 기본 설명으로 바뀌어 있었고요.

쓰지 않는 캡처 하나는 스펙째 지웠습니다. 관리자 인스턴스 화면을 찍던 50줄짜리 테스트인데, 1차에서 관리자 슬라이드를 뺀 뒤로 쓰는 곳이 없었어요. jstree를 API로 조작해 노드를 고르는 복잡한 스펙이라 유지비가 특히 비쌌습니다. 안내에 안 싣기로 한 화면이니 되살릴 일도 없고요.

함정 — 앞 촬영이 남긴 데이터가 다음 그림에 찍힌다

신청·심사 흐름 캡처는 실제로 신청을 만들고 제출하고 승인한 뒤 취소까지 합니다. 스펙이 자기 뒷정리를 하지만 취소 기록과 OID 노드는 dev DB에 남아요.

그게 다음 촬영에 그대로 찍힙니다. 실제로 OID 트리 건수와 심사 목록 세 줄이 오염된 채 한 번 찍혔어요. 그래서 촬영 전에 지난 신청과 OID를 지우고 시작합니다. 순서도 중요합니다 — 작성 예시를 먼저 찍으면 그 신청과 OID가 뒤이은 이용안내 촬영에 섞여요.

띠 단계 수도 맞춰야 합니다. 심사 절차는 설정값을 따르는데 개발 환경 기본값이 간편 5단계라, 그대로 찍으면 운영은 7칸인 띠가 안내에서는 5칸으로 나옵니다.

from constance import config; config.DEFAULT_WORKFLOW_TYPE = 0

찍기 전에 맞추고 끝나면 되돌립니다. 이 설정값이 조용히 흐르는 문제는 8월에 한 번 크게 겪었어요.

원격 서버를 대상으로 돌리는 건 금지해 뒀습니다. 시드가 안 실려 0건·404가 찍히고, 흐름 테스트가 남의 환경에 잔여 데이터를 만들어요. 예외가 물리 아키텍처 3장인데, 개발 환경에는 서비스가 0건이라 운영 화면으로 찍었습니다. 디자인은 로컬과 같았고 서비스 건수만 달랐어요.

검증

• 작성 예시는 PDF로 렌더되는 문서라, 캡처를 갈아 끼운 뒤 두 주소가 200으로 응답하고 이미지가 각각 11장·10장 실리는지 확인했습니다. 파일만 바꿔 놓고 문서에서 안 불리면 소용없으니까요.
• 물리 아키텍처 슬라이드는 4장으로 잠그는 e2e 스펙으로 막았습니다. 되살아나면 빨간불이 켜져요. 역할 안내 탭에서 뺀 역할 카드는 잠그지 않았습니다.
• 촬영 순서와 청소 절차, 마커를 바꾼 이유를 문서에 남겼습니다. 다음 촬영 때 같은 오염을 반복하지 않으려고요.

남은 것 · 한계

• 캡처는 바이너리라 리뷰가 안 됩니다. 수십 장이 바뀌었다는 사실만 diff에 남고 무엇이 어떻게 달라졌는지는 파일을 열어 봐야 알아요. 코드 변경은 리뷰어가 읽지만 그림 변경은 사실상 찍은 사람만 봅니다.
• 세 장은 안 바꿨습니다. 작성 예시의 참조 OID 캡처인데, 문서 본문이 가리키는 번호가 개발 환경에 없어요. 스펙을 임시로 다른 번호로 바꿔 찍긴 했지만 본문과 어긋나서 옛 파일을 유지하고 스펙은 되돌렸습니다. 본문과 그림이 맞는 쪽을 택하고, 그림이 조금 낡은 건 안고 갑니다.
• 한 장은 건수만 다릅니다. 트리 버킷 숫자가 하나 차이 나는데 개발 데이터 차이라 안 바꿨어요.
• 캡처가 개발 환경의 데이터 상태를 물려받습니다. 1차의 빈 카탈로그 화면이 그랬어요. 안내에 실을 그림을 어떤 데이터 위에서 찍을지는 아직 매번 사람이 판단합니다.
• 자동화된 건 셔터뿐입니다. 무엇을 찍을지, 어떤 화면을 안내에서 뺄지, 어떤 그림이 본문과 맞는지는 전부 손으로 정했어요. 캡처를 다시 찍는 일의 비용은 촬영이 아니라 이 판단에 있습니다.
• 툴바가 찍힌 일은 스펙 주석에, 잔여 데이터가 찍힌 일은 이력 문서에 "실제로 한 번"으로 남겨 뒀습니다. 같은 실수를 또 하지 않으려는 기록일 뿐, 그림이 잘못 찍힌 걸 잡아 주는 장치는 아직 없어요.

관련 글: 화면이 없어진 기능을 설명하고 있었다 · 제출 단계 칩에 스튜어드가 찍혀 있었다 · Playwright로 메뉴 136종 QA 스윕 · pk를 박아둔 e2e 스펙 11개가 한꺼번에 빨개졌다