Zeppelin E2E how-to guide

https://github.com/apache/zeppelin/pull/5072 ← Playwright 환경설정 및 왜 선택했는지 등의 내용은 PR 참조

1. Objective

• Playwright를 사용하여 Zeppelin New UI e2e 테스트 코드 작성
• LLM(MCP) 도구(Claude or Gemini + Playwright MCP 등) 를 활용하여 테스트 코드 자동 생성
  • 자연어 기반 지시(NL → 코드) 규칙 정의
• ⇒ 궁극적으로 총 57개의 파일에 대해 OSSCA25 마감까지 커버리지 50% 달성

2. Prerequisite environment

이광원님 가이드

→ 적어도 Zeppelin 빌드 및 실행이 되어있어야 합니다.

cd zeppelin-web-angular

# 프론트 환경설정 안되어있다면 진행
nvm use
npm i
npm run postinstall
npm run ng
npm run start

# Playwright 브라우저 설치
npx playwright install

# 테스트 속도를 높이기 위해 로컬 프론트 서버 미리 실행 **
npm run start

# 아래 코드로 e2e 동작 확인
npm run e2e:fast

npm run e2e:fast 결과

2.1 Explanation of the Playwright script

만약 MCP가 별로라면 codegen 사용하시면 편하실 거에요. // codegen 사용시 프론트 로컬서버 실행되어야 함

→ 테스트가 어떻게 작성되어야 하는지는 generate-test-by-argument rule 참조

3. Strategy for Leveraging MCP

3.1 초간단 버전! **

claude, gemini, cursor, co-pilot 중 하나를 사용하고 Playwright MCP 설정이 전제되어야 함

시나리오에 대해 아래의 형태로 입력

→ 각 시나리오는 Jira ZEPPELIN-6331 서브 이슈들 댓글에 추가해두었습니다.

$ARGUMENT(시나리오)는 아래와 같아 이를 바탕으로 **E2E 테스트 생성기**를 활용해 테스트를 작성해줘

**/* 시나리오 이부분에 입력 */**

# E2E 테스트 생성기

너는 지금부터 Playwright로 E2E 테스트를 사용하는 QA 전문가야

## 환경 관련
* zeppelin-web-angular 내부에서 nvm use로 정해진 node 버전을 사용해줘
* zeppelin-web-angular/playwright.config.ts 와 zeppelin-web-angular/e2e/ 환경에서 진행하니까 잘 파악해줘
* 테스트 작성을 위해 분석할 폴더는 zeppelin-web-angular/ 내부야
* 모든 테스트는 영어로 작성되어야 해
* 불필요한 주석은 달지마

## 테스트 방식
* $ARGUMENT로 전달된 테스트 요구사항(요소, 동작, 기대 결과)을 잘 분석해줘
* Playwright MCP를 사용해서 테스트를 진행해줘
* 테스트가 전부 끝나면 E2E 테스트를 작성해줘
* BDD 스타일(Given-When-Then)로 작성해줘
* 테스트 시나리오 파일을 URL path 단위 폴더구조로 묶어줘
* 작성한 테스트들을 전부 실행해주고 실패하는 테스트가 있다면 성공 할때까지 시도해줘
* 사용 가능하다면 Text-based Selector을 우선적으로 사용해줘 만약 사용이 불가
능한데 CSS Selector가 복잡해지고 사이드이펙트 발생이 가능할 경우 Attribute Selector(data-testid)를 사용해줘
* waitForTimeout은 되도록이면 사용하지말고 필요한 상황에는 toHaveCount를 사용해줘
* 공통으로 사용되는 util 메서드는 zeppelin-web-angular/e2e/utils.ts에 추가해줘
* 테스트 커버리지 측정을 위해 addPageAnnotationBeforeEach나 addPageAnnotation 함수를 utils.ts를 통해 추가해야해 이 때 e2e/utils.ts의 PAGES 객체를 사용해서 현재 페이지(혹은 컴포넌트)를 추가해줘
* 모든 테스트에 e2e/utils.ts의 performLoginIfRequired를 사용해서 tearup 해줘
* POM 방식으로 아래와 같이 명확하게 역할을 분리해서 나눠줘

/models/.ts // Page Object: DOM 요소(locators)와 기본 액션만 (클릭 , 입력, 네비게이션, 단순 상태확인) /models/.util.ts // Business Logic: 복잡한 워크플로우, 복합 검증 로직, 테스트 시나리오별 헬퍼 메서드 /tests/*.spec.ts // Test Scenarios: BDD 스타일 테스트 케이스, Page Object와 Util을 조합한 실제 테스트

### Page Object (*.ts) 에만 포함할 것:
* Locator 정의 (readonly locators)
* 기본 액션 (navigate, click, type, select 등)
* 단순 상태 확인 (isVisible, getText, getUrl 등)
* BasePage 상속

### Util (*.util.ts) 에만 포함할 것:
* 복합 검증 로직 (verify 메서드들)
* 워크플로우 조합 (여러 액션을 연결한 시나리오)
* 테스트별 헬퍼 메서드
* 복잡한 비즈니스 로직

3.2 Claude(유료 ← 무료 사용을 원할 경우 2.2 Gemini CLI 사용)

Claude Code 설치

npm install -g @anthropic-ai/claude-code

• GamsGo Purchase and Cursor Code Connection Guide

  

  

  

  GamsGo 브라우저 설치 및 해당 브라우저에서만 Claude 사용 가능한 상태

  # Claude 실행
  claude
  
  # Claude 로그인 요청
  /login
  

  

  

  → URL GamsGo 브라우저로 복사 붙여넣기

Playwright MCP 설치

# Playwright MCP 서버 설치
npm install -g @executeautomation/playwright-mcp-server

# Claude Code 연결(project // 전역 설정을 원하면 원하면 project 대신 global)
claude mcp add playwright -s project -- npx @executeautomation/playwright-mcp-server

# 설정 확인
claude
claude mcp list

Claude command ‘.md’ 파일 ./claude/commands 폴더에 추가

~/.claude/commands/e2e-recognize-testable-scenario.md

# E2E 테스트 시나리오 분석

너는 지금부터 Playwright로 E2E 테스트를 사용하는 QA 전문가야

## 테스트 방식
* $ARGUMENT로 입력한 부분에 필요한 페이지를 추론해주고 해당 페이지에 접속해줘
  * 변경사항이 있는 경우 localhost:4200 포트로 접속해야 해
* 컴포넌트 분석 및 Playwright MCP를 사용해서 어떤 요소들을 테스트하면 좋을지 나열해줘
* 조사가 끝나면 요소들을 자연어로 마크다운 형태로 정리해줘

~/.claude/commands/e2e-generate-test-by-argument.md

# E2E 테스트 생성기

너는 지금부터 Playwright로 E2E 테스트를 사용하는 QA 전문가야

## 환경 관련
* zeppelin-web-angular 내부에서 nvm use로 정해진 node 버전을 사용해줘
* zeppelin-web-angular/playwright.config.ts 와 zeppelin-web-angular/e2e/ 환경에서 진행하니까 잘 파악해줘
* 테스트 작성을 위해 분석할 폴더는 zeppelin-web-angular/ 내부야
* 모든 테스트는 영어로 작성되어야 해
* 불필요한 주석은 달지마

## 테스트 방식
* $ARGUMENT로 전달된 테스트 요구사항(요소, 동작, 기대 결과)을 잘 분석해줘
* Playwright MCP를 사용해서 테스트를 진행해줘
* 테스트가 전부 끝나면 E2E 테스트를 작성해줘
* BDD 스타일(Given-When-Then)로 작성해줘
* 테스트 시나리오 파일을 URL path 단위 폴더구조로 묶어줘
* 작성한 테스트들을 전부 실행해주고 실패하는 테스트가 있다면 성공 할때까지 시도해줘
* 사용 가능하다면 Text-based Selector을 우선적으로 사용해줘 만약 사용이 불가
능한데 CSS Selector가 복잡해지고 사이드이펙트 발생이 가능할 경우 Attribute Selector(data-testid)를 사용해줘
* waitForTimeout은 되도록이면 사용하지말고 필요한 상황에는 toHaveCount를 사용해줘
* 공통으로 사용되는 util 메서드는 zeppelin-web-angular/e2e/utils.ts에 추가해줘
* 테스트 커버리지 측정을 위해 addPageAnnotationBeforeEach나 addPageAnnotation 함수를 utils.ts를 통해 추가해야해 이 때 e2e/utils.ts의 PAGES 객체를 사용해서 현재 페이지(혹은 컴포넌트)를 추가해줘
* 모든 테스트에 e2e/utils.ts의 performLoginIfRequired를 사용해서 tearup 해줘
* POM 방식으로 아래와 같이 명확하게 역할을 분리해서 나눠줘

/models/.ts // Page Object: DOM 요소(locators)와 기본 액션만 (클릭 , 입력, 네비게이션, 단순 상태확인) /models/.util.ts // Business Logic: 복잡한 워크플로우, 복합 검증 로직, 테스트 시나리오별 헬퍼 메서드 /tests/*.spec.ts // Test Scenarios: BDD 스타일 테스트 케이스, Page Object와 Util을 조합한 실제 테스트

### Page Object (*.ts) 에만 포함할 것:
* Locator 정의 (readonly locators)
* 기본 액션 (navigate, click, type, select 등)
* 단순 상태 확인 (isVisible, getText, getUrl 등)
* BasePage 상속

### Util (*.util.ts) 에만 포함할 것:
* 복합 검증 로직 (verify 메서드들)
* 워크플로우 조합 (여러 액션을 연결한 시나리오)
* 테스트별 헬퍼 메서드
* 복잡한 비즈니스 로직

→ 완벽한게 아니라 업데이트 필요(의견 주시면 반영하겠습니다)

Claude commands 적용 확인

Example

# Claude Code 실행
claude

# E2E 테스트 시나리오 분석
/e2e-recognize-testable-scenario

나는 src/app/share/about-zeppelin/about-zeppelin.component 이 컴포넌트가 사용되는 부분에 대해 E2E 테스트 시나리오를 작성하고 싶어

# E2E 테스트 시나리오 분석 > 결과

E2E 테스트 시나리오

1. 모달 표시 테스트

시나리오: About Zeppelin 모달이 정상적으로 열리는지 확인

• 메인 페이지 접속
• 로그인 완료 대기
• 우상단 사용자명 드롭다운 클릭
• "About Zeppelin" 메뉴 항목 클릭
• 모달이 표시되는지 확인
• 모달 제목이 "About Zeppelin"인지 확인

1. 컴포넌트 요소 검증 테스트

시나리오: 모달 내 모든 요소가 올바르게 표시되는지 확인

• About 모달 열기
• Apache Zeppelin 로고 이미지 존재 확인
• "Apache Zeppelin" 제목 텍스트 확인
• "Version" 라벨 존재 확인
• 버전 번호가 표시되는지 확인 (빈 값이 아닌지)
• "Get involved!" 링크 존재 확인
• 라이선스 링크 존재 확인

1. 외부 링크 동작 테스트

시나리오: 외부 링크가 올바른 URL로 연결되는지 확인

• About 모달 열기
• "Get involved!" 링크의 href가 "http://zeppelin.apache.org/"인지 확인
• 라이선스 링크의 href가 "http://www.apache.org/licenses/LICENSE-2.0"인지 확인
• target="_blank" 속성 확인 (새 탭에서 열림)

1. 모달 닫기 테스트

시나리오: 모달이 정상적으로 닫히는지 확인

• About 모달 열기
• ESC 키로 모달 닫기 확인
• 모달 외부 영역 클릭으로 모달 닫기 확인
• 닫기 버튼 클릭으로 모달 닫기 확인 (있는 경우)

1. 반응형 레이아웃 테스트

시나리오: 다양한 화면 크기에서 레이아웃이 올바르게 표시되는지 확인

• 데스크톱 크기에서 모달 표시 확인
• 태블릿 크기에서 모달 표시 확인
• 모바일 크기에서 모달 표시 확인
• 로고와 콘텐츠 영역의 그리드 레이아웃 확인 (sm: 8/16, xs: 0/24)

1. 접근성 테스트

시나리오: 키보드 네비게이션 및 스크린 리더 지원 확인

• 탭 키로 드롭다운 메뉴 항목 접근 가능 확인
• Enter 키로 "About Zeppelin" 메뉴 활성화 확인
• 모달 내 링크들에 탭 키로 접근 가능 확인
• 이미지에 alt 텍스트 "Apache Zeppelin" 존재 확인

# E2E 테스트 생성기
/e2e-generate-test-by-argument

{위 결과를 바탕으로 추가할 것 추가하고 제거할 것 제거한 후 $ARGUMENT로 요청}

{직접 BDD(Given When Then) 형태로 테스트를 문장으로 작성 후 $ARGURMENT로 요청하는 방식도 가능}

# *테스트 코드 작성 완료 및 검토*

3.3 Gemini CLI(분당 60회, 하루 1천회 무료)

Gemini CLI 설치

npm install -g @google/gemini-cli

# gemini cli 접속 및 구글 로그인
gemini

Playwright MCP 설치

# Playwright MCP 서버 설치
npm install -g @executeautomation/playwright-mcp-server

# ~/.gemini/settings.json 에 아래 내용 추가

{ ... "mcpServers": { "playwright": { "command": "npx", "args": ["-y", "@executeautomation/playwright-mcp-server"] } } }

# 설정 확인
gemini
gemini mcp list

Gemini commands ‘.toml’ 파일 ./gemini/commands 폴더에 추가

~/.gemini/commands/e2e/recognize-testable-scenario.toml

description="E2E 테스트 시나리오 분석"
prompt = """
Please provide a detailed situation and specific component: {{args}}.

너는 지금부터 Playwright로 E2E 테스트를 사용하는 QA 전문가야

## 테스트 방식
* {{args}}로 입력한 부분에 필요한 페이지를 추론해주고 해당 페이지에 접속해줘
  * 변경사항이 있는 경우 localhost:4200 포트로 접속해야 해
* 컴포넌트 분석 및 Playwright MCP를 사용해서 어떤 요소들을 테스트하면 좋을지 나열해줘
* 조사가 끝나면 요소들을 자연어로 마크다운 형태로 정리해줘
"""

~/.gemini/commands/e2e/generate-test-by-argument.toml

description="E2E 테스트 생성기"
prompt = """
Please provide a detailed scenario: {{args}}.

너는 지금부터 Playwright로 E2E 테스트를 사용하는 QA 전문가야

## 환경 관련
* zeppelin-web-angular 내부에서 nvm use로 정해진 node 버전을 사용해줘
* zeppelin-web-angular/playwright.config.ts 와 zeppelin-web-angular/e2e/ 환경에서 진행하니까 잘 파악해줘
* 테스트 작성을 위해 분석할 폴더는 zeppelin-web-angular/ 내부야
* 모든 테스트는 영어로 작성되어야 해
* 불필요한 주석은 달지마

## 테스트 방식
* {{args}}로 전달된 테스트 요구사항(요소, 동작, 기대 결과)을 잘 분석해줘
* Playwright MCP를 사용해서 테스트를 진행해줘
* 테스트가 전부 끝나면 E2E 테스트를 작성해줘
* BDD 스타일(Given-When-Then)로 작성해줘
* 테스트 시나리오 파일을 URL path 단위 폴더구조로 묶어줘
* 작성한 테스트들을 전부 실행해주고 실패하는 테스트가 있다면 성공 할때까지 시도해줘
* 사용 가능하다면 Text-based Selector을 우선적으로 사용해줘 만약 사용이 불가
능한데 CSS Selector가 복잡해지고 사이드이펙트 발생이 가능할 경우 Attribute Selector(data-testid)를 사용해줘
* waitForTimeout은 되도록이면 사용하지말고 필요한 상황에는 toHaveCount를 사용해줘
* 공통으로 사용되는 util 메서드는 zeppelin-web-angular/e2e/utils.ts에 추가해줘
* 테스트 커버리지 측정을 위해 addPageAnnotationBeforeEach나 addPageAnnotation 함수를 utils.ts를 통해 추가해야해 이 때 e2e/utils.ts의 PAGES 객체를 사용해서 현재 페이지(혹은 컴포넌트)를 추가해줘
* 모든 테스트에 e2e/utils.ts의 performLoginIfRequired를 사용해서 tearup 해줘
* POM 방식으로 아래와 같이 명확하게 역할을 분리해서 나눠줘

/models/.ts // Page Object: DOM 요소(locators)와 기본 액션만 (클릭 , 입력, 네비게이션, 단순 상태확인) /models/.util.ts // Business Logic: 복잡한 워크플로우, 복합 검증 로직, 테스트 시나리오별 헬퍼 메서드 /tests/*.spec.ts // Test Scenarios: BDD 스타일 테스트 케이스, Page Object와 Util을 조합한 실제 테스트

### Page Object (*.ts) 에만 포함할 것:
* Locator 정의 (readonly locators)
* 기본 액션 (navigate, click, type, select 등)
* 단순 상태 확인 (isVisible, getText, getUrl 등)
* BasePage 상속

### Util (*.util.ts) 에만 포함할 것:
* 복합 검증 로직 (verify 메서드들)
* 워크플로우 조합 (여러 액션을 연결한 시나리오)
* 테스트별 헬퍼 메서드
* 복잡한 비즈니스 로직
"""

Gemini CLI commands 적용 확인

Example - Claude example 참조

# Gemini CLI 실행
Gemini

# E2E 테스트 시나리오 분석
/e2e:recognize-testable-scenario

{{args}}

# E2E 테스트 생성기
/e2e:generate-test-by-argument

{{args}}

4. Contribution Guide

중복 작업을 피하기 위해 기여자는 다음 절차를 따라주세요.

4.1 Check available tasks

• /zeppelin-web-angular/e2e/util.ts의 PAGES 변수를 확인하여 작업할 수 있는 영역을 찾습니다.
• 각 항목은 프로젝트의 특정 페이지 컴포넌트에 해당합니다.

4.2 Claim a task

• https://issues.apache.org/jira/browse/ZEPPELIN-6331
  • 이미 존재하는 이슈를 assign하여 시작하셔도 됩니다.
  • 시작하기 전에 새로운 하위 이슈(Sub-Issue)를 열어 작업 내용을 명시합니다.

작업 내용 예시:

헤더 영역, ..., ...에 대한 테스트를 작성하고 싶습니다.

PATH: src/app/share/header/header.component
...
...

4.3 Create a sub-issue

• 제목에는 영역명을 포함시켜 주세요.

  예: [E2E] Header Area

• 어떤 영역을 작업할 것인지 구체적으로 적어주세요.

• 메인 트래킹 이슈를 참조 링크로 연결합니다.

4.4 Submit a Pull Request

• 작업이 완료되면 하위 이슈를 참조하여 PR을 생성합니다.