Groundhog는 앱이 개발·테스트 중 보내는 이메일을 http://localhost:3025의 로컬 받은편지함에 모은다. SMTP와 Groundmail, SendGrid, Postmark, Mailgun, Resend, Amazon SES의 HTTP 발송 API를 에뮬레이션해 실제 서비스에 메일을 보내지 않고 가입 코드와 비밀번호 재설정 메일 등을 확인할 수 있다.
Node.js 20 이상에서는 다음 명령으로 실행한다. Docker 이미지도 제공하며, 이미지 아키텍처는 amd64와 arm64를 지원한다.
npx @groundmail/groundhog
SMTP는 포트 1025를 사용한다. 지원되는 이메일 서비스의 공식 SDK를 수정하지 않고 사용하려면 앱의 API 기본 URL을 Groundhog 주소로 바꾸면 된다. API 키와 사용자 이름, 비밀번호에는 임의의 값을 사용할 수 있다. 받은편지함은 이메일의 HTML·텍스트·원문·헤더와 첨부 파일을 보여주며, 일회용 코드와 링크도 추출한다.
테스트에서는 waitForEmail()로 이메일을 기다리고 코드와 링크를 가져올 수 있다. Playwright와 Vitest용 도우미가 있으며, MCP 서버를 설정하면 코딩 에이전트도 받은편지함에서 이메일을 읽을 수 있다. 발송 실패를 시험하는 기능은 429, 422, 401, 서버 오류 또는 시간 초과를 제공자별 오류 형식으로 시뮬레이션한다. 배달·반송·불만·열람·클릭 웹훅도 제공자 형식에 맞춰 전송할 수 있다.
Groundhog는 메일을 중계하지 않는다. 잡힌 이메일은 사용자가 ‘Send to my real inbox’를 눌렀을 때만 실제 받은편지함으로 전달된다. 이 기능은 무료 Groundmail 계정 연결이 필요하며, 도메인을 인증하기 전에는 Groundmail의 샌드박스 발신자가 계정 소유자의 주소로만 사본을 보낸다. 제공자에 저장된 템플릿은 로컬에서 렌더링되지 않아 템플릿 이름과 전달 데이터를 보여준다. Amazon SES 웹훅 서명은 로컬에서 재현할 수 없으므로 개발 중 서명 검사를 건너뛰어야 한다. 웹훅에 쓰는 고정 로컬 키는 공개된 값이므로 로컬 개발 밖에서 사용하면 안 된다.
MailHog에서 옮기는 경우 SMTP 포트는 1025로 유지되고 받은편지함 주소는 8025에서 3025로 바뀐다. Groundhog 저장소와 사용 안내에서 15초 데모, 기여 안내, 보안 안내, MIT 라이선스를 확인할 수 있다.
댓글 (0)
로그인하면 이 기사에 내 생각을 남길 수 있어요