▲

자동 갱신되는 스크린샷

 (interblah.net)
1P by GN⁺ 9시간전 | ★ favorite | 댓글 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 같은 지시를 함께 담음
    • <!-- SCREENSHOT: acme-tools/inbox | element | selector=#inbox-brand-new-section -->
    • 바로 아래 이미지 태그가 결과물이 들어갈 위치로 쓰임
  • UI의 색상, 버튼 위치, 문구가 조금만 바뀌어도 기존 문서 스크린샷은 쉽게 낡아지는데, 이 흐름은 그런 수동 갱신 부담을 줄임

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

  • 내부적으로는 Rake task가 Capybara와 Cuprite를 통해 headless Chrome을 실행해 모든 Markdown 파일의 SCREENSHOT 주석을 스캔함
  • 스크린샷 작업은 팀 기준으로 묶어 처리되며, 같은 팀에서는 한 번만 로그인한 뒤 여러 URL을 순회하도록 구성됨
  • 지원하는 캡처 모드는 세 가지임
    • element: CSS selector로 특정 DOM 요소를 캡처함
    • full_page: 전체 페이지를 캡처하고, 필요하면 높이 기준으로 잘라낼 수 있음
    • viewport: 브라우저 창에서 현재 보이는 영역만 캡처함
  • 세부 옵션으로 click, wait, crop을 둘 수 있어 버튼 클릭 뒤 나타나는 상태나 애니메이션 이후의 화면도 자동으로 잡아낼 수 있음
    • <!-- SCREENSHOT: nectar-studio/manage/rules | full_page | click=".rule-create-button" wait=200 crop=0,800 -->
    • 버튼을 눌러 폼을 연 뒤 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하는 흐름만으로 스크린샷을 항상 최신 상태로 맞출 수 있어, 수동 캡처와 수동 크롭의 마찰이 거의 사라짐

함께 보면 좋은 글 β

▲
GN⁺ 9시간전  [-]
Hacker News 의견들
  • 나도 비슷하게 .#screenshots derivation을 추가해뒀고, 초반 설정 비용은 크지만 그다음엔 유지보수가 거의 들지 않음
    프로그램으로 스크린샷을 생성하는 김에 앱의 light/dark theme 두 버전을 같이 만들고, prefers-color-scheme: dark에 맞춰 바꿔 끼우면 됨
    이런 요소는 GitHub README에서도 잘 동작함: https://github.com/CyberShadow/CyDo#readme
    • 이 방식에 강하게 공감함
      모바일 앱에서는 Nix로 일회성 Android 에뮬레이터를 띄워 최신 스크린샷을 생성하게 했고, 사전 설정도 필요 없고 실행 후 데이터도 남지 않음
      내 경우 설정 자체도 그렇게 힘들진 않았고, 아이디어를 떠올리는 쪽이 더 어려웠으며 Nix 코드는 좋아하는 LLM으로 한 번에 만들었음
      수동으로 스크린샷을 갱신하는 일이 세상에서 제일 고된 건 아니지만, upload-apk + take-screenshot + transfer-back-to-PC + edit 흐름이 늘 미묘하게 귀찮아서 결국 거의 안 하게 됨
  • 모바일에서는 코드 예제 가로 스크롤이 꼭 필요함
    문맥으로 대충 추측은 가능했지만 그래도 불편했음
  • 이건 모바일 프로젝트에서 정말 유용함
    앱 스토어는 스크린샷이 필수인데, 화면 크기 수와 현지화 수만큼 이미지를 만들어야 해서 금방 번거로워짐
    예전엔 이걸 위해 직접 스크립트를 썼고, 지금은 https://fastlane.tools/ 같은 Fastlane 도구가 큰 도움이 됨
    내 로직 퍼즐 게임 Nonoverse에도 Fastlane을 쓰고 있고, 앱스토어 페이지에서 예시 스크린샷을 볼 수 있음: https://apps.apple.com/us/app/nonoverse-nonogram-puzzles/id6...
    App Preview 영상 녹화도 여러 장면까지 포함해 자동화해뒀고, 궁금한 사람이 있으면 글로 따로 정리할 만한 주제라고 봄
    • 흥미가 확 당기는데, 이게 유료 서비스인지 아니면 로컬에서 도는 OS 앱인지 잘 감이 안 옴
  • 꽤 멋짐
    내가 vibe coding으로 만드는 작은 캐주얼 게임들은 늘 앱이 CLI로 헤드리스 실행되고, 오프스크린 텍스처 렌더링과 스크린샷 명령, 성능 계측까지 가능한 상태에서 시작함
    이걸 넣는 데 시간도 거의 안 들고, 에이전트가 UI를 자동화하고 중요한 지점을 살펴볼 수 있는 통로도 생김
    덕분에 에이전트가 스크린샷을 갱신하게 만드는 것도 아주 쉬워짐
    빌드 과정에 완전히 녹아든 형태만큼 깔끔하진 않지만, 이제 그 부분도 추가해볼 생각임
    • 나도 똑같이 함
      offscreen screenshot path와 world pos/camera view vector를 넣는 CLI 인자도 있고, 텍스트 기반 입력 형식으로 스크립트 벤치마크를 돌림
      이 형식은 이름 붙은 세그먼트 여러 줄과 세그먼트별 n 게임 틱 길이, 그리고 각 세그먼트의 컨트롤 입력으로 구성됨
      게임 코드를 작업하면서 비주얼과 성능을 A/B 테스트할 때 이걸 아주 많이 씀
    • 이런 캐주얼 게임들 링크를 좀 공유해줄 수 있을지 궁금함
      나도 vibe coding이 게임 개발을 얼마나 쉽게 만드는지 관심이 큼
      Adobe Flash 시절엔 인디 게임 생태계가 정말 활기찼고, 그 뒤로는 그 정도의 개발 용이성을 건드린 게 거의 없었음
      vibe coding은 그 수준을 처음으로 넘어서는 도구처럼 보임
    • 이걸 넣는 데 시간도 거의 안 든다는 말은 경우에 따라 다름
      어떤 엔진을 쓰는지 궁금함
  • 정말 멋짐
    Markdown 문서 안에 스크린샷 선언을 인라인으로 넣을 수 있다는 점이 특히 마음에 듦
    내 데스크톱 앱에서는 여러 언어와 light/dark 모드의 스크린샷을 생성하고, 노이즈를 제거하고, Windows/macOS 창 프레임까지 입히는 솔루션을 만들어뒀음
    여기에 정리해뒀음: https://maxschmitt.me/posts/cakedesk-website-redesign#screen...
    지금은 별도 스크립트라 유지보수가 꽤 귀찮은데, markdown/mdx 일부로 편입하는 쪽을 살펴봐야겠음
    좋은 영감을 받았음
  • 이런 게 정말 자주 필요했음
    아무도 눈치채지 못할 X 최고의 작업물 같은 밈으로 써도 될 정도임
  • 이거 좋음
    내가 만든 https://github.com/zombocom/rundoc에도 비슷한 기능이 있음
    주된 목적은 튜토리얼 생성이라서, 실행한 명령의 출력도 다시 문서 안에 넣어줌
  • 여기서는 실시간 렌더링 접근도 가능하지 않을까 싶음
    도구의 라이브 프리뷰를 직사각형 안에 넣는 식임
    도구가 가볍다면 시각적으로도 최적일 수 있고, 브라우저의 접근성 설정이나 사용자 애드온 같은 렌더링 설정도 그대로 반영할 수 있음
  • e2e 테스트를 돌릴 때 스크린샷 생성도 같이 해보는 방식을 생각해본 적이 있음
    문서용 docs/도 같은 저장소에 두고, 문서를 업데이트하면서 새 스크린샷이 필요해지면 새 테스트를 추가하는 식이면 잘 맞을 듯함
  • 좋음
    나도 몇 년 전에 정확히 이걸 만들기 시작했다가, 결국 https://picshift.io/처럼 더 범용적인 쪽으로 추상화했음
    그래도 여전히 스크린샷 유스케이스는 정말 마음에 들고, 이 프로젝트의 원래 이름도 ScreenSync였음
    • 좋고, 잘 만들었고, 이런 다양한 접근법이 같이 존재하는 게 반가움
답변달기