파이썬 Selenium 실행 JS 사용법 execute_script execute_async_script 반환과 Promise 처리

⚡ execute_script 기본 사용법과 반환값

파이썬 Selenium에서 가장 많이 사용되는 기능 중 하나가 바로 execute_script입니다.
이 메서드는 브라우저의 자바스크립트 엔진을 직접 호출하여 원하는 코드를 실행할 수 있게 해주는데요.
예를 들어 DOM 요소를 가져오거나, 스크롤을 내리거나, 특정 값을 반환받는 경우에 활용됩니다.

일반적으로 execute_script는 동기 방식으로 실행되며, 자바스크립트 코드가 반환하는 값은 그대로 파이썬으로 전달됩니다.
숫자, 문자열, 불리언, 배열, 객체 등 대부분의 기본 데이터 타입을 받을 수 있으며, DOM 요소를 반환하면 Selenium이 이를 자동으로 WebElement 객체로 변환합니다.

from selenium import webdriver

driver = webdriver.Chrome()
driver.get("https://example.com")

# 자바스크립트 실행 - 페이지 제목 반환
title = driver.execute_script("return document.title;")
print(title)

# 스크롤 내리기
driver.execute_script("window.scrollTo(0, document.body.scrollHeight);")

위 예제에서 첫 번째 스크립트는 페이지의 제목을 가져와 반환합니다.
자바스크립트 return 키워드가 사용된 부분은 곧바로 파이썬 변수에 할당됩니다.
두 번째 스크립트는 반환값이 없기 때문에 단순히 브라우저에서 동작만 수행합니다.

즉, execute_script는 간단한 자바스크립트 실행과 동기적 반환에 최적화되어 있으며, 대부분의 상황에서는 이 방식만으로도 충분히 원하는 작업을 수행할 수 있습니다.
하지만 Ajax 호출이나 타이머처럼 시간이 걸리는 작업에는 다른 접근이 필요합니다.

⏳ execute_async_script 비동기 실행 방식

웹 페이지에는 네트워크 요청이나 타이머, 이벤트 리스너처럼 실행이 끝날 때까지 시간이 걸리는 코드가 많습니다.
이럴 때 execute_script를 사용하면 브라우저가 응답을 돌려주지 않아 TimeoutException 같은 오류가 발생할 수 있습니다.
이를 해결하기 위해 Selenium은 execute_async_script라는 메서드를 제공합니다.

이 방식은 비동기 자바스크립트를 실행할 수 있도록, 마지막에 반드시 콜백(callback) 함수를 호출해야 합니다.
Selenium은 해당 콜백이 실행되기 전까지 기다리며, 콜백의 인자로 전달한 값이 곧 파이썬으로 반환됩니다.

from selenium import webdriver

driver = webdriver.Chrome()
driver.get("https://example.com")

# 비동기 스크립트 실행
result = driver.execute_async_script("""
    var callback = arguments[0];
    setTimeout(function() {
        callback("3초 후 반환된 데이터");
    }, 3000);
""")

print(result)  # "3초 후 반환된 데이터"

위 예제에서 자바스크립트의 setTimeout은 3초 뒤에 콜백을 실행합니다.
그 전까지 Selenium은 대기하고 있다가, 콜백이 실행되면 해당 값이 파이썬으로 반환됩니다.

따라서 API 요청, Ajax 처리, 지연 실행 같은 상황에서는 반드시 execute_async_script를 사용해야 안정적인 결과를 얻을 수 있습니다.
이 기능을 적절히 활용하면 페이지 내부의 비동기 로직까지 제어할 수 있어 자동화의 범위를 크게 확장할 수 있습니다.

🔄 Promise 반환값 처리와 주의점

최근의 웹 애플리케이션은 Promise 기반의 비동기 코드를 광범위하게 사용합니다.
하지만 Selenium에서 단순히 execute_script로 Promise를 실행하면 아직 완료되지 않은 상태가 반환되므로, 원하는 데이터를 바로 얻지 못하는 문제가 생깁니다.

이 경우 가장 안전한 방법은 execute_async_script를 활용해 Promise의 then() 또는 catch() 안에서 콜백을 호출하는 방식입니다.
즉, Promise가 완료될 때까지 기다렸다가 Selenium에 최종 결과를 전달하는 구조로 작성해야 합니다.

# 자바스크립트 Promise를 Selenium에서 처리하기
result = driver.execute_async_script("""
    var callback = arguments[0];
    fetch("https://jsonplaceholder.typicode.com/posts/1")
        .then(response => response.json())
        .then(data => callback(data))
        .catch(error => callback("Error: " + error));
""")

print(result)

위 예제에서는 fetch() API가 반환하는 Promise를 받아 JSON 데이터가 준비된 시점에 콜백으로 전달합니다.
이렇게 하면 네트워크 요청이 완료될 때까지 기다렸다가 Selenium이 최종 결과를 정상적으로 받을 수 있습니다.

즉, Selenium에서 Promise를 다룰 때는 비동기 처리라는 특성을 고려해야 하며, 적절히 콜백 구조를 작성하지 않으면 데이터 로드 실패나 무한 대기 같은 문제가 발생할 수 있습니다.

🛠️ 실전 예제 코드와 활용 시나리오

이제 실제로 Selenium에서 execute_script와 execute_async_script를 어떻게 활용할 수 있는지 살펴보겠습니다.
단순한 DOM 조작부터, 네트워크 API 호출, 스크롤 처리까지 다양한 활용 시나리오가 존재합니다.

📌 동기 실행 활용 예제

페이지의 특정 요소를 조작하거나 화면을 이동시키는 경우에는 execute_script를 사용하는 것이 간단하고 빠릅니다.

# 특정 요소의 텍스트 가져오기
element_text = driver.execute_script(
    "return document.querySelector('h1').innerText;"
)
print(element_text)

# 무한 스크롤 페이지 로딩
driver.execute_script("window.scrollTo(0, document.body.scrollHeight);")

📌 비동기 실행 활용 예제

API 요청이나 Ajax 데이터 로딩처럼 시간이 걸리는 작업에서는 execute_async_script가 필수입니다.

# Ajax 요청 후 데이터 가져오기
result = driver.execute_async_script("""
    var callback = arguments[0];
    fetch("https://jsonplaceholder.typicode.com/users/1")
        .then(resp => resp.json())
        .then(data => callback(data))
        .catch(err => callback("Error: " + err));
""")

print(result)

• ⚡DOM 조작 → 텍스트, 속성, 스타일 변경
• 🌐API 요청 → Ajax, Fetch로 서버 데이터 받기
• 🔄무한 스크롤 처리 → 동적 페이지 컨텐츠 로딩

이처럼 Selenium의 자바스크립트 실행 기능은 단순 제어를 넘어, 실제 사용자 브라우저 환경을 그대로 시뮬레이션하는 데 유용합니다.
특히 데이터 크롤링이나 자동화 테스트 환경에서 활용도가 높습니다.

⚠️ 오류와 예외 처리 전략

Selenium에서 자바스크립트를 실행하다 보면 다양한 오류와 예외 상황을 맞이하게 됩니다.
스크립트 실행 자체가 실패하는 경우도 있고, 비동기 작업이 끝나지 않아 무한 대기 상태에 빠지기도 합니다.
따라서 안정적인 자동화를 위해서는 반드시 예외 처리를 고려해야 합니다.

📌 자주 발생하는 오류 유형

📌 안전한 코드 작성 전략

• ✅try-except 문으로 예외 상황을 포착하고 로그 남기기
• ✅WebDriverWait과 같은 명시적 대기 조건을 함께 사용하기
• ✅Promise 기반 로직은 반드시 callback() 또는 resolve 시점에서 반환 처리

이처럼 발생 가능한 오류를 사전에 인지하고, 적절한 예외 처리와 대기 전략을 세워두면 예측 불가능한 상황에서도 안정적인 자동화가 가능합니다.

❓ 자주 묻는 질문 (FAQ)