자동 갱신되는 스크린샷

2 hours ago 1

실행 중인 웹 애플리케이션에서 스크린샷을 자동 캡처해 도움말 문서 빌드와 함께 갱신하는 흐름으로, UI 변경 뒤에도 문서 이미지를 최신 상태로 유지하기 쉬움
Markdown 안의 SCREENSHOT 주석이 대상 경로, 캡처 방식, CSS selector 같은 지시를 담고, 빌드 과정에서 이를 읽어 실제 이미지로 채워 넣음
Rake task가 Capybara와 Cuprite를 통해 headless Chrome을 실행하고, 팀별로 작업을 묶어 한 번 로그인한 뒤 여러 URL을 순회하며 캡처함
캡처는 element, full_page, viewport 세 가지 모드를 지원하고, click, wait, crop, torn, hide 같은 옵션으로 열린 상태의 UI나 불필요한 요소도 함께 제어함
rails manual:build 한 번으로 스크린샷 생성과 도움말 페이지 빌드가 함께 돌아가며, 코드와 문서를 같은 PR이나 commit 안에서 맞추기 쉬워 수동 캡처와 수동 크롭의 마찰이 크게 줄어듦

자동 갱신되는 스크린샷 방식

Jelly의 도움말 센터는 실행 중인 웹 애플리케이션에서 스크린샷을 자동 캡처하고, 다시 빌드할 때 함께 갱신되도록 구성됨
문서는 Markdown으로 작성되며, Self-updating screenshots 본문 기준으로 Redcarpet로 HTML로 처리한 뒤 Rails 앱의 ERB 뷰로 렌더링됨
Markdown 안에는 SCREENSHOT 주석이 들어가며, 여기서 대상 경로, 캡처 방식, CSS selector 같은 지시를 함께 담음
- 
- 바로 아래 이미지 태그가 결과물이 들어갈 위치로 쓰임
UI의 색상, 버튼 위치, 문구가 조금만 바뀌어도 기존 문서 스크린샷은 쉽게 낡아지는데, 이 흐름은 그런 수동 갱신 부담을 줄임

캡처 파이프라인과 유지보수 효과

내부적으로는 Rake task가 Capybara와 Cuprite를 통해 headless Chrome을 실행해 모든 Markdown 파일의 SCREENSHOT 주석을 스캔함
스크린샷 작업은 팀 기준으로 묶어 처리되며, 같은 팀에서는 한 번만 로그인한 뒤 여러 URL을 순회하도록 구성됨
지원하는 캡처 모드는 세 가지임
- element: CSS selector로 특정 DOM 요소를 캡처함
- full_page: 전체 페이지를 캡처하고, 필요하면 높이 기준으로 잘라낼 수 있음
- viewport: 브라우저 창에서 현재 보이는 영역만 캡처함
세부 옵션으로 click, wait, crop을 둘 수 있어 버튼 클릭 뒤 나타나는 상태나 애니메이션 이후의 화면도 자동으로 잡아낼 수 있음
- 
- 버튼을 눌러 폼을 연 뒤 200ms 기다리고, 특정 영역으로 잘라 캡처하도록 동작함
추가 옵션으로 torn과 hide도 있음
- torn은 CSS clip-path를 이용해 찢어진 종이 가장자리 효과를 적용함
- hide는 dev toolbar나 cookie banner처럼 화면에 나오지 않아야 하는 요소를 임시로 숨김
전체 파이프라인은 rails manual:build 명령 하나로 실행되며, 모든 스크린샷 캡처와 도움말 페이지 빌드를 함께 처리함
문서 소스는 public/manual/ 아래에 basics, setup, advanced 같은 섹션별로 정리되어 있음
빌드 단계에서 이 Markdown 파일들은 app/views/help/ 아래의 ERB 뷰로 변환되며, breadcrumb와 섹션 내비게이션도 함께 생성됨
기능 개발과 도움말 갱신을 같은 코드베이스 안에서 함께 다룰 수 있어, 코드와 문서의 동기화를 같은 PR이나 같은 commit 안에서 유지하기 쉬워짐
스크롤이 필요한 요소, 클릭해야 열리는 popover, 불필요한 부분을 피하기 위한 crop 같은 예외 처리는 구현에 더 많은 시간을 요구했지만, 구축 후에는 도움말 센터를 훨씬 자주 갱신하게 됨
UI를 바꾸고 빌드를 다시 실행한 뒤 결과를 commit하는 흐름만으로 스크린샷을 항상 최신 상태로 맞출 수 있어, 수동 캡처와 수동 크롭의 마찰이 거의 사라짐