웹 편집기 자동화가 깨질 때 공식 API로 옮기는 기준

웹 편집기 자동화, 글자가 보이는 것과 저장되는 것

웹 편집기의 contenteditable은 웹 페이지의 일부를 편집 가능하게 만드는 HTML 속성이다. 일반 입력 칸처럼 문자열만 받는 경우도 있지만, 굵은 글씨나 문단을 다루는 편집기는 구조도 함께 다룬다. 같은 속성이라도 plaintext-only이면 서식 있는 편집이 꺼진다. MDN은 이 영역에 붙여넣을 때 서식이 제거된다고 설명한다. 글자를 넣는 데 성공해도 원하던 서식까지 들어갔는지는 별도로 봐야 한다.

입력 과정에는 이벤트(무슨 일이 생겼는지 프로그램에 알리는 신호)가 있다. beforeinput은 브라우저가 내용을 바꾸기 전 편집 동작을 다룰 기회를 준다. inputType은 그 동작의 종류다. W3C 문서는 타이핑의 insertText, 붙여넣기의 insertFromPaste, 조합 중 입력의 insertCompositionText를 따로 정의한다. 확인한 Input Events Level 2 문서는 Working Draft(작업 초안) 상태다. 겉으로 같은 문장이 나타나더라도 편집기가 받은 입력의 종류까지 같다는 뜻은 아니다.

이 차이 때문에 «붙여넣을 때는 되는데 문자열을 넣으면 안 된다»는 증상은 단순한 속도 문제로 설명하기 어렵다. 붙여넣기 처리에만 서식을 읽는 코드가 있거나, 키 입력에만 반응하는 처리가 있을 가능성을 따져 볼 수 있다. 다만 이런 가능성은 이벤트 정의로부터 세운 진단 가설이다. 특정 편집기의 내부 구현을 확인한 결론은 아니다. 어느 경로에서 문제가 생겼는지 먼저 좁혀야 원인을 엉뚱한 대기 시간으로 덮지 않는다.

contenteditable 입력은 어디서 달라지는가

다음은 특정 제품의 오류 목록이 아니라 시험용 문서에서 남길 관찰표다. 문장을 짧게 정하고 입력 내용은 그대로 둔 채 방법만 바꾼다. 글자 수를 늘리거나 서식을 더하는 것은 기본 문장이 남는지 본 뒤에 한다. 내용과 방법을 함께 바꾸면 어느 차이가 결과를 바꿨는지 알기 어렵다.

1. 손으로 짧은 문장을 넣고 저장한 뒤 문서를 다시 연다. 잘 됐으면 입력한 문장이 그대로 돌아온다. 손으로도 빠지면 편집 권한이나 저장 오류부터 담당자에게 전달한다.
2. 같은 문장을 문제의 입력 방법으로 넣는다. 잘 됐으면 저장 뒤에도 손으로 넣은 결과와 같다. 입력 직후의 화면만 같다면 아직 저장 검증이 끝난 것이 아니다.
3. 문장이 남으면 문단과 굵게 표시를 더해 비교한다. 잘 됐으면 다시 연 문서에 글자와 구조가 함께 남는다. 서식만 사라지면 편집 영역의 속성과 공식 지원 형식을 본다.

IME(자모를 조합해 한글 같은 문자를 만드는 입력기)도 별도 변수다. MDN은 사용자의 모든 수정에서 beforeinput이 발생하는 것은 아니며, 브라우저와 운영체제에 따라 차이가 있다고 적는다. 그래서 한글 문자열을 프로그램으로 넣은 결과가 정상이어도 실제 조합 입력 경로까지 검증한 것은 아니다. 글자가 합쳐지는 도중의 동작이 필요한 시험이라면 그 범위를 시험 항목에 따로 적는다.

화면 요소를 찾는 단계부터 실패했다면 브라우저 자동화의 층별 확인법으로 돌아가 입력 대상부터 좁힐 수 있다. 반대로 요소를 찾고 글자까지 보인다면, 그 뒤의 저장 결과를 기록하는 것이 이번 판단에 더 가깝다.

Playwright fill 안됨, 키별 입력으로 바꾸기 전 볼 것

Playwright는 브라우저를 프로그램으로 다루는 도구다. 공식 문서는 fill()이 대상에 초점을 맞추고 입력한 텍스트로 input 이벤트를 일으키며, input·textarea·contenteditable 요소를 지원한다고 설명한다. «contenteditable이라 fill을 못 쓴다»는 설명은 문서와 맞지 않는다. 먼저 실제 편집 영역을 가리켰는지, 그 영역이 편집 가능한지부터 봐야 한다.

공식 저장소의 v1.56.1 구현을 읽으면 교체 입력이라는 뜻이 더 선명하다. injectedScript.ts의 fill()은 대상 내용을 선택하고 needsinput을 반환한다. 내용을 선택할 때는 편집 영역 안의 노드를 범위로 잡는다. 이어 dom.ts의 호출부는 비어 있지 않은 문자열을 keyboard.insertText로 보낸다. 이 경로를 보면 기존 문장 뒤에 덧붙이려던 일에 fill()을 썼을 때 왜 예상이 어긋날 수 있는지 설명된다.

이 소스에서 읽은 선택·입력 경로를 모든 버전과 편집기의 보장으로 넓힐 수는 없다. 사용 중인 버전의 동작은 그 버전 문서와 시험 결과로 판단해야 한다. 다만 타이핑·붙여넣기·문자열 교체를 같은 동작으로 취급하면 안 된다는 점은 현행 Playwright 문서의 메서드 구분과도 맞는다.

fill과 pressSequentially를 같은 조건에서 비교하기

키 입력을 특별히 처리하는 페이지에는 pressSequentially()를 검토할 수 있다. 현행 API 문서는 이 메서드가 v1.38에 추가되었고, 키 사이 지연의 기본값은 0밀리초라고 적는다. 같은 문서는 이 메서드가 글자마다 keydown, keypress/input, keyup 이벤트를 차례로 보낸다고 설명한다. 그러면서도 대부분은 fill()을 쓰고, 페이지에 특별한 키보드 처리가 있을 때만 한 글자씩 누르라고 권한다. 메서드를 바꾼다고 저절로 느린 입력이 되지는 않는다. 지연을 늘리는 일과 필요한 키 이벤트를 보내는 일은 서로 다르다.

아래는 Playwright Test가 이미 준비된 환경에서 쓸 수 있는 연습 예시다. 공식 문서의 메서드를 로컬 빈 편집 영역에 적용하도록 묶었다. 실제 서비스의 저장 기능을 흉내 내는 코드는 아니다. 파일을 시험 폴더의 editor.spec.ts로 두면 된다. 이 글에서는 코드를 실행한 결과를 주장하지 않는다.

import { test, expect } from '@playwright/test';

test('빈 편집 영역에서 입력 방법 비교', async ({ page }) => {
  await page.setContent(
    '<div role="textbox" aria-label="연습 본문" contenteditable="true"></div>'
  );
  const editor = page.getByRole('textbox', { name: '연습 본문' });

  await editor.fill('sample text');
  await expect(editor).toHaveText('sample text');

  await editor.fill('');
  await editor.pressSequentially('sample text');
  await expect(editor).toHaveText('sample text');
});

1. 연습 예시에서 두 입력 방법의 결과를 비교한다. 잘 됐으면 같은 텍스트를 검사하는 조건이 모두 통과한다. 이 단계가 막히면 서비스 편집기의 문제와 섞기 전에 도구 실행 환경을 살핀다.
2. 시험이 허용된 편집기에서는 실제 입력 영역을 가리키도록 대상만 바꿔 비교한다. 잘 됐으면 입력 뒤 표시 내용이 같다. 입력 대상이 여러 개라면 보이는 겉 상자와 편집 영역을 구별한다.
3. 서비스의 정식 저장 절차를 거쳐 다시 연 문서를 비교한다. 잘 됐으면 두 방식의 저장 결과까지 같다. 빈 편집 영역에서 통과한 검사를 서비스의 저장 성공으로 읽지 않는다.

붙여넣기가 필요한 상황에서 합성 paste 이벤트만 보내는 방식도 주의할 지점이다. MDN은 그런 이벤트를 만들 수 있지만 문서 내용에는 영향을 주지 않는다고 설명한다. 이벤트를 보냈다는 기록은 브라우저의 실제 붙여넣기가 수행됐다는 근거가 아니다. execCommand() 역시 MDN에서 사용 중단 대상으로 표시한 메서드다. 대안이 없는 사용 사례가 남아 있다는 설명까지 있으므로, 작동 여부를 단정하기보다 새 연동의 기본 해법으로 채택할 이유가 있는지 따져야 한다.

인용 — MDN · paste event

It's possible to construct and dispatch a synthetic paste event, but this will not affect the document's contents.

우리말 뜻: 합성 paste 이벤트를 만들어 전달할 수는 있지만, 그것만으로 문서 내용이 바뀌지는 않는다.

웹 편집기 자동화를 공식 API로 옮길 판단표

공식 API는 서비스가 프로그램에 공개한 요청·응답 규칙이다. 화면에서 편집하는 대신 지원하는 데이터 형식으로 작업을 요청한다. 화면 위치나 입력 이벤트에 의존하는 부분을 줄일 수 있다는 점이 전환의 이유가 된다. 그런데 API가 존재한다는 사실과 필요한 문서를 만들 수 있다는 사실은 다르다. 화면에서는 되는 문단·표·첨부 관계가 API의 쓰기 형식에는 없을 수 있으므로 지원 범위를 먼저 대조한다.

검토할 문서를 «업무 문서»처럼 넓게 적으면 빠진 기능이 나중에 드러난다. 필요한 결과를 본문, 문단, 굵게 표시, 링크, 표, 첨부 파일처럼 나누는 편이 낫다. 이는 특정 API가 이 기능을 제공한다는 목록이 아니다. 각 서비스 문서에서 지원 여부를 채워 넣을 요구사항 표다. 읽기 응답에 필드가 있어도 만들기·수정 요청에 같은 필드를 쓸 수 있다고 추정하지 않는다. 엑셀처럼 파일 형식이 공개된 결과물은 화면 대신 라이브러리로 파일을 직접 만드는 길도 있는데, 이때도 저장 뒤 다시 열어 보는 원칙은 같다. 그 예는 openpyxl로 엑셀을 쓸 때 조용히 깨지는 경우에 정리해 두었다.

API 전환을 결정하기 전에 채울 메모

아래 메모는 API 요청 본문이 아니다. 담당자에게 넘길 요구사항을 같은 항목으로 정리하는 양식이다. 처음에는 작업을 실행하지 않고 문서의 어느 부분이 각 칸을 뒷받침하는지만 적어도 된다. 지원 여부가 빈칸이면 전환 일정부터 잡기보다 그 칸을 답할 담당자를 찾는 편이 정확하다.

필요한 결과: 본문과 필수 서식
공식 작업 명칭: 개발 문서에 적힌 명칭
쓰기 형식: 해당 작업의 요청 본문 규격
읽기 경로: 저장된 대상을 다시 조회하는 작업
권한 범위: 공식 문서의 정확한 scope 이름
대상 권한: 접근할 문서나 폴더에서 허용된 동작
이용 조건: 요금제, 제한, 신청 필요 여부
완료 조건: 다시 읽은 본문과 필수 서식이 요구사항과 같음

1. 필요한 본문과 서식을 쓰기 명세의 필드에 대응시킨다. 잘 됐으면 필요한 항목마다 공식 문서의 근거가 붙는다. 필수 서식이 빠지면 화면 입력을 없애기 전에 문서 형식 변경이 가능한지 묻는다.
2. 저장된 대상을 다시 조회할 경로를 적는다. 잘 됐으면 응답에서 받은 대상 식별자로 결과를 찾아 비교할 수 있다. 성공 표시만 있고 본문을 읽을 수 없다면 누가 어떤 경로로 결과를 검토할지 남긴다.
3. 시험용 대상에서 변경 전후를 비교할 항목을 정한다. 잘 됐으면 본문 누락, 서식 손실, 다른 대상 변경을 각각 알아낼 수 있다. 정식 시험 권한을 받기 전에는 문서 대조와 설계까지만 진행한다.

이 글의 전환 권고는 필요한 쓰기 형식, 결과를 읽을 경로, 허용된 권한이 모두 설명되는 범위부터 옮기는 것이다. 외관을 눈으로 판정해야 하는 부분은 별도 화면 검토로 남길 수 있다. API로 전환한 범위와 화면에서 검토할 범위를 적어 두면, 일부만 바꾼 상태를 전체 검증 완료로 오해하지 않는다.

응답이 끊겼을 때의 처리도 완료 조건에 포함한다. 첫 요청이 반영됐는지 모른 채 같은 생성 요청을 다시 보내면 중복을 구별하기 어렵다. 서비스 문서에 중복 방지나 결과 조회 절차가 있는지 살피고 그 절차를 따른다. HTTP 문서도 실패한 자동 재시도를 다시 반복하지 말라고 권고한다. 이 글은 임의의 재시도 간격이나 횟수를 정하지 않는다. 서비스가 제공하는 정식 수단으로 결과를 판별할 수 있는지가 전환 검토 항목이다.

공식 API 연동, OAuth 승인과 대상 권한을 함께 보기

OAuth는 사용자가 프로그램에 정해진 범위의 접근을 허락하는 체계다. 승인 코드 흐름에서는 사용자의 승인 뒤 받은 코드를 토큰(정해진 범위 안에서 접근을 허락받았다는 표시로 쓰는 문자열)으로 교환한다. PKCE는 승인 코드 교환을 요청한 프로그램과 묶어 코드 가로채기 위험을 줄이는 장치다. 공개 클라이언트는 비밀을 안전하게 보관하기 어려운 앱을 뜻하며, RFC 9700은 이런 클라이언트가 승인 코드를 보호하는 데 PKCE를 사용해야 한다고 정한다.

여기서 PKCE를 붙인다는 설명만으로 설정 검토를 끝내면 빠지는 값이 있다. RFC 7636에서 code_challenge_method를 생략했을 때의 기본값은 plain이다. 같은 문서는 지원할 수 있는 클라이언트가 S256을 사용해야 한다고 정한다. S256은 검증 문자열을 SHA-256 해시(원문을 되돌릴 수 없는 고정 길이 값으로 바꾸는 계산)로 바꿔 챌린지를 만드는 방식이다. SDK(서비스가 내주는 개발용 라이브러리 묶음)나 연동 설정을 검토할 때 매개변수 이름뿐 아니라 사용 방식까지 읽어야 한다.

승인 코드와 PKCE를 검토하는 순서

다음은 제공 서비스의 공식 OAuth 안내와 함께 읽을 검토 순서다. 실제 승인 화면을 열거나 토큰을 발급하는 실행 절차는 아니다. 서비스마다 등록 방식과 지원 범위가 다르므로 주소나 권한 이름을 임의로 채운 요청 예시는 쓰지 않는다.

1. 공식 문서에서 이 프로그램에 허용된 승인 코드 흐름과 PKCE 지원을 찾는다. 잘 됐으면 앱 유형과 권장 SDK가 그 흐름에 대응한다. 이름만 비슷한 예제를 다른 유형에 옮기지 않는다.
2. 코드 챌린지 방식이 S256인지 살핀다. 잘 됐으면 SDK 설명이나 설정에서 사용 방식이 드러난다. 기본값이 안전할 것이라고 추정하지 않고 제공 문서를 대조한다.
3. 필요한 동작에 해당하는 scope만 요청하도록 적는다. 잘 됐으면 본문 조회·수정처럼 각 범위에 용도가 붙는다. RFC 9700은 접근 토큰의 권한을 해당 용도에 필요한 최소 범위로 제한하도록 권고한다.
4. 승인 결과가 요구한 범위와 맞는지 살핀다. 잘 됐으면 서비스가 실제 허용한 범위를 알 수 있다. RFC 6749는 서버가 요청 범위를 전부 또는 일부 받아들이지 않을 수 있다고 설명한다.
5. 시험 대상에서 허용된 동작과 허용되지 않은 동작을 구별할 검증 항목을 만든다. 잘 됐으면 수정 가능한 대상과 접근이 거절되어야 할 대상이 분명하다. 권한 검증 시험은 담당자가 승인한 시험용 자료로 진행한다.

scope는 접근 범위를 표현하는 문자열이다. RFC 6749는 공백으로 구분하고 대소문자를 구별하는 목록으로 정의한다. 그래서 이름을 자연어로 추측하거나 쉼표로 이어 붙이면 다른 값이 될 수 있다. 권한 이름은 제공 서비스의 공식 문서에서 그대로 가져와야 한다. 요청에 넓은 범위를 넣어 오류를 피하는 식으로 문제를 풀면 필요한 범위를 정리하려던 목적이 사라진다.

토큰이 발급됐다는 사실은 대상 문서의 수정 권한까지 입증하지 않는다. OWASP는 API가 요청받은 대상에서 그 동작을 수행할 권한이 있는지 검사해야 한다고 설명한다. 사용자에게 허용된 폴더와 프로그램에 허용된 범위가 모두 맞아야 한다. 접근이 거절되면 인증 여부, 승인된 범위, 대상별 권한을 나눠 담당자에게 전달하면 실패 지점을 찾기 쉽다.

자주 묻는 것

contenteditable이면 fill을 쓸 수 없나?

Playwright 문서는 contenteditable을 fill의 지원 대상으로 적는다. 먼저 실제 편집 영역을 찾았는지 본다. 표시가 바뀌어도 저장 뒤 내용이 돌아오지 않으면 입력 이벤트와 저장 결과를 나눠 살필 문제다. 특정 편집기가 필요한 입력을 받아들였다는 뜻까지 메서드의 지원 목록이 보장하지는 않는다.

pressSequentially로 바꾸면 한글 입력 문제도 해결되나?

그 결과만으로 판단할 수 없다. API 문서의 키별 입력과 실제 IME 조합 과정은 검증할 범위가 다르다. 한글이 완성된 문자열을 넣는 일인지, 사용자가 조합하는 과정을 시험하는 일인지부터 정한다. 후자라면 브라우저와 운영체제를 포함한 시험 항목이 필요하다.

공식 API가 있으면 문단과 표도 그대로 옮길 수 있나?

각 API의 쓰기 규격을 봐야 한다. 이 글의 판단표는 본문·필수 서식을 공식 필드에 대응시키도록 만든 것이다. 화면 편집 기능이나 읽기 응답에 보인다는 이유로 쓰기도 지원한다고 가정하지 않는다. 필요한 서식의 근거가 없으면 문서 형식을 줄일 수 있는지 담당자와 먼저 합의한다.

OAuth 승인을 받았는데 문서 수정이 거절되면 무엇을 보나?

실제로 승인된 scope와 그 문서에서 허용된 동작을 나눠 본다. 요청한 scope와 발급된 범위는 다를 수 있고, 대상 객체별 권한 검사도 필요하다. 권한을 넓혀 다시 시도하기 전에 어떤 범위가 부족한지 공식 문서와 시험 대상의 접근 설정을 대조한다.

정리 — 입력을 고칠 범위와 API로 옮길 범위

웹 편집기 자동화가 흔들릴 때는 화면에 글자를 넣는 데 성공했는지보다 저장 뒤 같은 내용을 다시 읽을 수 있는지를 먼저 본다. Playwright의 fill과 키별 입력은 목적이 다르고, 붙여넣기 이벤트를 보냈다는 사실도 문서 변경을 보장하지 않는다. 입력 방법을 비교할 때 같은 문장과 빈 시작 상태를 쓰면 원인을 좁히기 쉽다.

공식 API로 옮길 범위는 필요한 쓰기 형식, 저장 결과를 읽는 경로, 허용된 권한으로 정한다. 담당자에게 넘길 메모에 이 근거를 붙이고, 비어 있는 칸은 지원 확인 항목으로 남긴다. 화면 입력에서 생기던 불확실성을 다른 요청 방식으로 옮기기만 하지 않으려면 완료 조건까지 같이 설계해야 한다.

참고 자료

1. Playwright. Actions — fill의 지원 요소와 input 이벤트, 키별 입력 설명(2026-11-11 확인). playwright.dev
2. W3C. Input Events Level 2 — inputType과 조합 입력, Working Draft 상태(2026-11-11 확인). w3.org
3. MDN. Element beforeinput event — 이벤트가 발생하지 않거나 취소할 수 없는 경우(2026-11-11 확인). developer.mozilla.org
4. MDN. contenteditable — plaintext-only와 붙여넣기 서식(2026-11-11 확인). developer.mozilla.org
5. MDN. Document execCommand — 사용 중단 표시와 남아 있는 사용 사례(2026-11-11 확인). developer.mozilla.org
6. MDN. Element paste event — 합성 이벤트와 실제 문서 변경의 차이(2026-11-11 확인). developer.mozilla.org
7. Playwright. Locator pressSequentially — 추가 버전과 키 사이 지연 기본값(2026-11-11 확인). playwright.dev
8. IETF. RFC 6749 — 승인 코드 흐름과 scope 표현(2026-11-11 확인). rfc-editor.org
9. IETF. RFC 9700 — 공개 클라이언트의 PKCE와 토큰 권한 제한(2026-11-11 확인). rfc-editor.org
10. IETF. RFC 7636 — S256과 생략 시 plain 기본값(2026-11-11 확인). rfc-editor.org
11. OWASP. API1:2023 Broken Object Level Authorization — 대상 객체와 동작별 권한 검사(2026-11-11 확인). api-security.owasp.org
12. IETF. RFC 9110 — 실패한 자동 재시도의 반복에 대한 권고(2026-11-11 확인). rfc-editor.org
13. Microsoft Playwright v1.56.1. injectedScript.ts — fill의 내용 선택과 needsinput 반환 경로(2026-11-11 확인). raw.githubusercontent.com
14. Microsoft Playwright v1.56.1. dom.ts — needsinput 뒤 keyboard.insertText 호출(2026-11-11 확인). raw.githubusercontent.com