INTEGRITY Dokumentace

← Browser Run / browser-run

Puppeteer

Puppeteer ↗ patří mezi nejoblíbenější knihovny, které pro vývojáře abstrahují nízkoúrovňový protokol DevTools a poskytují vysokoúrovňové API pro snadné ovládání Chrome/Chromium a automatizaci relací prohlížení. Puppeteer se používá pro úlohy jako vytváření snímků obrazovky, procházení stránek a testování webových aplikací.

Puppeteer se obvykle připojuje k místnímu prohlížeči Chrome nebo Chromium prostřednictvím portu DevTools. Podrobnosti najdete v Dokumentaci k Puppeteer API najdete na Puppeteer.connect() metoda ↗ s dalšími informacemi.

Tým Workers vytvořil fork Puppeteeru a upravil ho tak, aby se místo toho připojoval k rozhraní Workers Browser Run API. Po připojení pak mohou vývojáři využívat celé Puppeteer API ↗ jako by tomu bylo při standardním nastavení.

Naše verze je open source a najdete ji v Fork knihovny Puppeteer od Cloudflare ↗. Npm lze nainstalovat z npmjs ↗ jako @cloudflare/puppeteer ↗:

npm i -D @cloudflare/puppeteer

Použití Puppeteer ve Worker

Jakmile vazba pro prohlížeč je nakonfigurováno a @cloudflare/puppeteer je nainstalovaná, lze Puppeteer použít ve workeru:

import puppeteer from "@cloudflare/puppeteer";

export default {
	async fetch(request, env) {
		const browser = await puppeteer.launch(env.MYBROWSER);
		const page = await browser.newPage();
		await page.goto("https://example.com");
		const metrics = await page.metrics();
		await browser.close();
		return Response.json(metrics);
	},
};
import puppeteer from "@cloudflare/puppeteer";

interface Env {
	MYBROWSER: Fetcher;
}

export default {
	async fetch(request, env): Promise<Response> {
		const browser = await puppeteer.launch(env.MYBROWSER);
		const page = await browser.newPage();
		await page.goto("https://example.com");
		const metrics = await page.metrics();
		await browser.close();
		return Response.json(metrics);
	},
} satisfies ExportedHandler<Env>;

Tento skript spustí se ↗ env.MYBROWSER prohlížeč, otevře nová stránka ↗, přejde na ↗ https://example.com/ ↗, získá načtení stránky metriky ↗, se zavírá ↗ prohlížeč a vypíše metriky ve formátu JSON.

Keep Alive

Pokud uživatelé vynechají browser.close() příkaz, zůstane otevřená, připravená k opětovnému připojení a znovu použité ve výchozím nastavení se však po 1 minutě nečinnosti automaticky uzavře. Uživatelé mohou tuto dobu nečinnosti volitelně prodloužit až na 10 minut pomocí keep_alive nastavenou v milisekundách:

const browser = await puppeteer.launch(env.MYBROWSER, { keep_alive: 600000 });

Při použití výše uvedeného zůstane prohlížeč otevřený až 10 minut, i když je nečinný.

Nastavení vlastního user-agenta

Chcete-li v Puppeteer zadat vlastní user agent, použijte page.setUserAgent() metoda. To se hodí, pokud cílový web zobrazuje různý obsah podle user agenta.

await page.setUserAgent(
	"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36",
);

Místní ladění v režimu headful (experimentální)

Při lokálním vývoji s wrangler dev nebo vite dev, Chrome ve výchozím nastavení běží v režimu headless. Chcete-li spustit Chrome ve viditelném režimu (headful), nastavte X_BROWSER_HEADFUL proměnnou prostředí:

X_BROWSER_HEADFUL=true npx wrangler dev

Nebo pomocí Cloudflare Vite plugin:

X_BROWSER_HEADFUL=true npx vite dev

Tím se otevře okno prohlížeče, takže můžete v reálném čase sledovat svou automatizaci v Puppeteer, což usnadňuje ladění navigace, výběru prvků a interakcí se stránkou.

Výběr prvků

Puppeteer nabízí několik metod pro výběr elementů na stránce. Selektory CSS fungují podle očekávání, selektory XPath ale kvůli bezpečnostním omezením v runtime Workers podporované nejsou.

Místo selektorů Xpath můžete použít selektory CSS nebo page.evaluate() ke spouštění dotazů XPath v kontextu prohlížeče:

const innerHtml = await page.evaluate(() => {
	return (
		// @ts-ignore this runs on browser context
		new XPathEvaluator()
			.createExpression("/html/body/div/h1")
			// @ts-ignore this runs on browser context
			.evaluate(document, XPathResult.FIRST_ORDERED_NODE_TYPE).singleNodeValue
			.innerHTML
	);
});

Správa relací

Abychom usnadnili správu relací prohlížeče, přidali jsme nové metody do puppeteer:

Vypište otevřené relace

puppeteer.sessions() zobrazí aktuálně spuštěné relace. Vrátí výstup podobný tomuto:

[
	{
		"connectionId": "2a2246fa-e234-4dc1-8433-87e6cee80145",
		"connectionStartTime": 1711621704607,
		"sessionId": "478f4d7d-e943-40f6-a414-837d3736a1dc",
		"startTime": 1711621703708
	},
	{
		"sessionId": "565e05fb-4d2a-402b-869b-5b65b1381db7",
		"startTime": 1711621703808
	}
]

Všimněte si, že relace 478f4d7d-e943-40f6-a414-837d3736a1dc má aktivní připojení workeru (connectionId=2a2246fa-e234-4dc1-8433-87e6cee80145), zatímco relace 565e05fb-4d2a-402b-869b-5b65b1381db7 je zdarma. Dokud je připojení aktivní, nemůže se k dané relaci připojit žádný jiný worker.

Vypište nedávné relace

puppeteer.history() zobrazí seznam nedávných relací, otevřených i uzavřených. Je to užitečné pro získání přehledu o vašem aktuálním využití.

[
	{
		"closeReason": 2,
		"closeReasonText": "BrowserIdle",
		"endTime": 1711621769485,
		"sessionId": "478f4d7d-e943-40f6-a414-837d3736a1dc",
		"startTime": 1711621703708
	},
	{
		"closeReason": 1,
		"closeReasonText": "NormalClosure",
		"endTime": 1711123501771,
		"sessionId": "2be00a21-9fb6-4bb2-9861-8cd48e40e771",
		"startTime": 1711123430918
	}
]

Relace 2be00a21-9fb6-4bb2-9861-8cd48e40e771 byla výslovně uzavřena pomocí browser.close() klientem, zatímco relace 478f4d7d-e943-40f6-a414-837d3736a1dc byla uzavřena kvůli dosažení maximální doby nečinnosti (ověřte limity).

Tyto informace byste měli vidět i v dashboardu, i když s mírným zpožděním.

Aktivní limity

puppeteer.limits() zobrazí vaše aktivní limity:

{
	"activeSessions": [
		{ "id": "478f4d7d-e943-40f6-a414-837d3736a1dc" },
		{ "id": "565e05fb-4d2a-402b-869b-5b65b1381db7" }
	],
	"allowedBrowserAcquisitions": 1,
	"maxConcurrentSessions": 2,
	"timeUntilNextAllowedBrowserAcquisition": 0
}

Puppeteer API

Úplné API Puppeteer najdete v Fork knihovny Puppeteer od Cloudflare ↗.