E2E Test Agent: 자연어로 작성한 테스트 시나리오를 기반으로 테스트를 수행하는 AI E2E 테스트 프레임워크

9bow · 11월 16, 2025, 5:30오전

E2E Test Agent 소개

E2E Test Agent는 대규모 언어 모델(LLM, Large Language Model)을 활용하여 자연어로 작성된 테스트 시나리오를 실행하는 새로운 형태의 엔드투엔드(E2E, End-to-End) 테스트 프레임워크입니다. 이 도구의 핵심 아이디어는 “테스트를 코드가 아닌 사람의 언어로 작성하자”는 것입니다. 즉, 개발자뿐 아니라 기획자, QA, 비즈니스 담당자도 이해할 수 있도록 테스트 케이스를 자연어(영어)로 작성하면, AI가 자동으로 해당 행동을 수행하고 결과를 검증합니다.

기존의 UI 테스트 프레임워크(예: Playwright, Cypress 등)는 CSS 셀렉터나 DOM 구조에 의존하기 때문에 UI 변경 시 테스트가 쉽게 깨지는 문제가 있습니다. 반면 E2E Test Agent는 의도 기반(Intent-based) 접근법을 채택하여 “무엇을 테스트할 것인가”에 집중하고, “어떻게 할 것인가”는 AI에게 맡깁니다. 이렇게 함으로써 테스트 코드 유지보수 부담을 크게 줄이고, UI 변경에도 유연하게 대응할 수 있습니다.

E2E Test Agent 프레임워크는 OpenAI 뿐만 아니라, Claude, OpenRouter 등 OpenAI API 호환 LLM과 통신할 수 있습니다. 또한 Playwright MCP 서버를 통해 실제 브라우저 자동화를 수행합니다.

기존 테스트 방식과의 비교

예를 들어 특정 사이트에 방문하여 특정 테스트를 수행하는 경우, 기존의 테스트 자동화는 다음과 같이 코드 중심 접근을 취합니다.

await page.goto("https://playwright.dev");
await page.click('button[data-testid="get-started-btn"]');
await expect(page.locator(".sidebar-menu")).toBeVisible();

이러한 코드 중심의 테스트 작성 방식은 잘 동작하지만, 시간이 지나며 CSS 셀렉터 변경이나 DOM 구조 수정이 발생하면 테스트가 쉽게 깨집니다. 또한 테스트 목적(의도)이 코드로는 명확히 드러나지 않습니다.

이와 달리, E2E Test Agent에서는 동일한 테스트를 아래와 같이 자연어로 작성할 수 있습니다:

open playwright.dev
scroll all the way down,
click on "Get started",
check if the page side menu is visible.

이러한 자연어 기반으로 테스트를 작성하는 방식의 장점은 다음과 같습니다:

의도 기반으로 작성하기 때문에 누구나 무엇을 할지를 기준으로 테스트를 작성할 수 있습니다.
셀프 힐링(Self-Healing) 기능을 통해 UI 변경에도 자동 적응되어 유지보수 비용이 감소합니다.

결국, 테스트의 “언어”를 사람 중심으로 바꾸는 것이 E2E Test Agent의 핵심 혁신입니다.

E2E Test Agent 동작 방식

┌─────────────────┐
│  Test Files     │ Plain English test steps
│  (.test files)  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  TestAgent      │ Orchestrates test execution
│  Class          │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  LLM Agent      │ Interprets tests & decides actions
│                 │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  MCP Tools      │ Browser automation, web search, etc.
│  (Playwright)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Your App       │ Real interactions, real results
└─────────────────┘

E2E Test Agent는 다음의 5단계 파이프라인을 통해 테스트를 실행합니다:

테스트 파일(확장자가 .test인 파일들)로부터 자연어 테스트를 읽습니다.
TestAgent 클래스가 실행을 관리합니다.
LLM Agent가 테스트 문장을 해석하고 수행 계획을 생성합니다.
MCP 도구(Playwright 등) 를 사용하여 수행 계획에 맞춰 실제 브라우저 기반 테스트를 수행합니다.
테스트 결과를 수집 및 요약하여 사용자를 위한 리포트를 생성합니다.

이 구조 덕분에 프레임워크는 언어 이해 + 실행 제어 + 실제 브라우저 상호작용을 자연스럽게 통합합니다.

E2E Test Agent 설치 및 초기 설정

E2E Test Agent 프레임워크는 npm 또는 yarn 등으로 바로 설치할 수 있습니다:

# npm 사용 시
npm install e2e-test-agent

# yarn 사용 시
yarn add e2e-test-agent

설치 후에는 E2E Test Agent이 동작할 LLM 관련 설정들을 작성합니다. 해당 설정들은 아래와 같은 내용들을 포함하며, 프로젝트 루트에 .env 파일로 위치해야 합니다:

# .env 파일 내용
MODEL_NAME="gpt-4o"
API_KEY="your-openai-api-key"
BASE_URL="https://api.openai.com/v1"
TESTS_DIR="./tests"

위 설정에서 BASE_URL을 변경하여 OpenAI뿐 아니라 Anthropic Claude, OpenRouter, Ollama, LM Studio 등 OpenAI API와 동일한 프로토콜을 따르는(OpenAI API Compatible) 다른 서비스와도 호환이 가능합니다.

각 환경 변수에 대한 설명은 다음과 같습니다:

환경 변수	설명	기본값
MODEL_NAME	사용할 LLM 모델	gpt-4o
API_KEY	OpenAI API 키	필수
BASE_URL	API 엔드포인트	OpenAI 기본 URL
TESTS_DIR	테스트 파일 디렉토리	./tests

E2E Test Agent 사용법

빠른 시작

아래와 같이 테스트 실행 파일(Test Runner)를 작성합니다:

import { TestAgent } from "e2e-test-agent";
import "dotenv/config";

async function main() {
  const testAgent = new TestAgent({
    modelName: process.env.MODEL_NAME || "gpt-4o",
    apiKey: process.env.API_KEY!,
    baseURL: process.env.BASE_URL,
    testsDir: process.env.TESTS_DIR || "./tests",
    maxSteps: 20,
  });

  const results = await testAgent.runAllTests();
  testAgent.printSummary(results);
}

main().catch(console.error);

위 내용을 run-tests.ts 라는 파일명으로 저장한 뒤, 다음과 같이 실행하면 됩니다:

# tsx로 바로 실행 (개발시 권장)
npx tsx run-tests.ts

# 또는, 컴파일 후 Node.js로 실행도 가능
tsc run-tests.ts
node run-tests.js

테스트 작성

E2E Test Agent가 수행할 테스트를 tests/ 디렉토리 내 .test라는 확장자를 갖는 파일로 작성합니다. 예를 들어, 다음은 tests/1.test 파일의 예시입니다:

open playwright.dev
scroll all the way down,
click on "Get started",
check if the page side menu is visible.

그 외, 다음과 같은 방식으로 tests/2.test 파일을 생성하여 테스트를 작성할 수 있습니다:

navigate to github.com
search for "typescript"
click on the first repository
verify the repository has a README file

코드에 포함하여 실행 (Programmatic Usage)

기존 개발된 프로젝트 및 테스트 코드에 추가하여 사용할 수 있습니다. 다음은 테스트를 실행하는 예시 코드입니다:

import { TestAgent } from "e2e-test-agent";

const testAgent = new TestAgent({
  modelName: "gpt-4o",
  apiKey: process.env.API_KEY!,
  baseURL: process.env.BASE_URL,
  testsDir: "./tests",
  maxSteps: 20,
});

// 전체 테스트 실행
const results = await testAgent.runAllTests();
testAgent.printSummary(results);

// 특정 테스트만 실행 (예. ./tests/1.test)
const result = await testAgent.runSingleTest("./tests/1.test", 1);

MCP 서버 확장 예시

그 외에도, 다음과 같이 TestAgent를 생성하며 mcpServers를 키(key)로 갖는 MCP Server 서버 정보 객체를 추가하여 사용할 수도 있습니다:

const testAgent = new TestAgent({
  apiKey: "...",
  mcpServers: {
    playwright: { command: "npx", args: ["@playwright/mcp@latest"] },
    filesystem: {
      command: "npx",
      args: ["@modelcontextprotocol/server-filesystem"],
    },
  },
});

이렇게 MCP Server를 통해 파일 시스템 접근, API 호출 등 다양한 확장이 가능합니다.

테스트 결과 예시

============================================================
Running Test #1: 1.test
============================================================

Result: {
  "success": true,
  "steps_completed": [
    "Opened playwright.dev",
    "Scrolled to bottom",
    "Clicked Get started button",
    "Verified sidebar visibility"
  ],
  "final_status": "passed"
}
============================================================
✅ PASSED - Test #1: 1.test
Total: 1 | Passed: 1 | Failed: 0

테스트 결과에는 단계별 실행 내역, 성공 여부, 관찰 결과까지 요약됩니다.

라이선스

E2E Test Agent 프로젝트는 MIT 라이선스로 공개되어 있습니다. 상업적 사용을 포함한 대부분의 용도에서 자유롭게 사용할 수 있습니다.

E2E Test Agent 홈페이지

E2E Test Agent 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~