@swarmmachina/swm-cdp v0.1.1

swm-cdp

Chrome DevTools Protocol

Типизированный ESM-клиент Chrome DevTools Protocol без runtime-зависимостей. Команды, события и flattened sessions с явным владением процессом Chrome.

Используйте для browser smoke tests, диагностики и управления локальным Chrome на уровне протокола. Пакет экспериментальный; высокоуровневые локаторы и автоматическое ожидание элементов остаются за пределами API.

Node.jsswm-cdpCDP pipe / WebSocketChrome
22 / 24
Node.js
0
runtime deps
ESM
формат модуля
MPL-2.0
лицензия

Установка и быстрый старт

Shellinstall
npm install @swarmmachina/swm-cdp
JavaScriptquick-start.js
import { spawnChrome } from '@swarmmachina/swm-cdp'

const browser = spawnChrome({ headless: true, transport: 'pipe' })

try {
  const cdp = await browser.attach()
  const target = await cdp.send('Target.createTarget', { url: 'about:blank' })
  const { sessionId } = await cdp.send('Target.attachToTarget', {
    flatten: true,
    targetId: target.targetId
  })

  await cdp.send('Runtime.enable', undefined, sessionId)
  const result = await cdp.send(
    'Runtime.evaluate',
    { expression: 'document.title', returnByValue: true },
    sessionId
  )
  console.log(result.result.value)
} finally {
  await browser.close()
}
  • Установите Chrome или Chromium отдельно; chromeExecutable или CHROME_PATH задаёт путь явно.
  • spawnChrome() синхронно создаёт владельца процесса; attach() отдельно ждёт готовность CDP.
  • Передавайте sessionId в команды вкладки. Для команды без параметров используйте undefined перед sessionId.
  • browser.close() закрывает принадлежащий библиотеке Chrome и очищает временный профиль. Закрытие клиента от attach() также закрывает владельца.

Возможности пакета

Типизированный протокол
send(), on() и once() используют сгенерированные типы команд, результатов и событий CDP.
Владение Chrome
Browser разделяет создание, attach, закрытие и очистку профиля; pipe используется по умолчанию.
Ограниченные очереди
Лимиты pending requests, task queue, сообщений и outbound buffer; eventBackpressure по умолчанию закрывает соединение при переполнении.
Discovery и finder
HTTP discovery работает через встроенный fetch, а findChrome() ищет executable без запуска браузера.

Runtime и платформы

СредаСтатусПримечание
Node.js ^22.13.0 / 24.xПоддерживаетсяNative ESM и встроенный WebSocket; Node.js 26 не входит в engines.
Локальный Chrome / ChromiumНужен отдельноБраузер не включён в npm-пакет.
127.0.0.1 / [::1]WebSocket endpointconnect() принимает browser-level endpoint только на literal loopback IP; localhost и удалённые адреса отклоняются.

Карта API

CdpClient

Типизированные команды, события и завершение соединения.

connect()send()on()once()onClose()onError()close()

Browser

Явный владелец процесса Chrome и временного профиля.

spawnChrome()attach()close()kill()waitForExit()state

Discovery / finder

Отдельные subpath exports для поиска и HTTP discovery.

list()version()createTarget()closeTarget()findChrome()ChromeFinder

Полные сигнатуры, типы и примеры находятся в README и TypeScript declarations исходного репозитория.

Sessions, лимиты и завершение Chrome

Разделяйте время жизни protocol client и принадлежащего приложению процесса браузера.

Закрывайте владельца в finally

Для spawnChrome() используйте browser.close(). Для connect() cdp.close() закрывает только клиент, сохраняя отдельно запущенный Chrome.

Фильтруйте события по sessionId

on() передаёт sessionId вторым аргументом и возвращает unsubscribe. Вызывайте его, когда подписка больше не нужна.

Ограничивайте операции

send() принимает AbortSignal и timeout; protocolTimeout по умолчанию 180 секунд, maxPendingRequests и maxQueueDepth равны 10 000.

Сохраняйте локальную границу

Remote endpoints и DNS-имена отклоняются намеренно. Не публикуйте debugging endpoint браузера во внешнюю сеть.

Подключение к уже запущенному Chrome

Если Chrome уже запущен с debugging endpoint на loopback, connect() создаёт только клиентское соединение. Владелец внешнего процесса отвечает за его остановку.

JavaScriptconnect.js
import connect from '@swarmmachina/swm-cdp'

const cdp = await connect({ host: '127.0.0.1', port: 9222 })

try {
  console.log(await cdp.send('Browser.getVersion'))
} finally {
  await cdp.close()
}
Нужна нагрузка на HTTP или WebSocket вместо управления браузером?Открыть benchkit