Frameworks et Playground
Remarques pour connecter certains frameworks à un navigateur hébergé, et le Playground du tableau de bord pour essayer une tâche ou un script en suivant la vue en direct.
Frameworks
Tout ce qui s’attache à Chrome via CDP fonctionne avec le connectUrl. Comme celui-ci est à usage unique, un framework qui se reconnecte de lui-même a besoin d’une nouvelle session pour chaque connexion. Le navigateur démarre au moment où vous vous connectez, généralement en quelques secondes (voir la remarque sur le délai de connexion plus haut) ; il n’y a aucun statut à interroger au préalable.
// Patchright (optional; a Playwright fork): npm i patchright
import { chromium } from "patchright";
const browser = await chromium.connectOverCDP(connectUrl, { timeout: 120_000 });
const page = browser.contexts()[0].pages()[0];# Browser Use
from browser_use import Agent, Browser
agent = Agent(task="Find the cheapest flight to Lisbon next Friday", llm=llm, browser=Browser(cdp_url=connect_url))
await agent.run()
# Crawl4AI
from crawl4ai import AsyncWebCrawler, BrowserConfig
config = BrowserConfig(browser_mode="custom", cdp_url=connect_url, use_managed_browser=True)
async with AsyncWebCrawler(config=config) as crawler:
result = await crawler.arun("https://example.com")// Stagehand v4
import { localBrowser, Stagehand } from "@browserbasehq/stagehand";
const stagehand = await Stagehand.create({ browser: await localBrowser.connect({ cdpUrl: connectUrl }) });setContent et exposeFunction
Le moteur n’envoie jamais les événements de console au client, car c’est justement leur transmission que mesurent les pages qui cherchent à repérer un client d’automatisation. Les navigateurs hébergés s’en tiennent là : l’option stock_runtime du SDK, qui les rétablit le temps d’une session de débogage sur votre propre machine ou dans Docker, n’est pas appliquée à un lancement cloud. Deux appels du driver en dépendent :
- Dans Playwright,
page.setContent()attend un événement de console qui n’arrive jamais, et finit donc en timeout (dans Puppeteer, il fonctionne). Ouvrez plutôt le HTML sous forme d’URLdata:, ou écrivez-le vous-même dans la page, comme ci-dessous. - Dans Playwright comme dans Puppeteer,
exposeFunction()etexposeBinding()fonctionnent dans la page ouverte au moment de l’appel, et disparaissent dès que cette page navigue. Appelez-les après la dernière navigation, ou faites plutôt remonter les résultats avecevaluate.
// Instead of await page.setContent(html):
// Short HTML: a data: URL (the page gets no origin of its own, so no cookies or storage)
await page.goto("data:text/html," + encodeURIComponent(html));
// Any HTML: write it into a page you have navigated to; it keeps that page's origin
await page.evaluate((html) => {
document.open();
document.write(html);
document.close();
}, html);# Instead of page.set_content(html):
from urllib.parse import quote
page.goto("data:text/html," + quote(html))
# or
page.evaluate("html => { document.open(); document.write(html); document.close(); }", html)Un helper pour démarrer
Création avec les nouvelles tentatives décrites plus haut, connexion et arrêt systématique, dans une seule fonction :
// clearcote-hosted.ts
import { chromium, type Browser } from "playwright"; // or "patchright"
const API = "https://www.clearcotelabs.com/api/v1/browsers";
const AUTH = { authorization: "Bearer " + process.env.CLEARCOTE_API_KEY };
const RETRY_CODES = new Set(["NO_CAPACITY", "NO_WORKER"]);
export async function createSession(options: Record<string, unknown> = {}, attempts = 5) {
for (let i = 0; ; i++) {
const res = await fetch(API, {
method: "POST",
headers: { ...AUTH, "content-type": "application/json" },
body: JSON.stringify(options),
});
const body = await res.json().catch(() => ({}));
if (res.ok) return body as { id: string; connectUrl: string; worker: string };
const retry = RETRY_CODES.has(body.code) || (res.status === 429 && !body.code) || [500, 502, 504].includes(res.status);
if (!retry || i + 1 >= attempts) throw new Error([res.status, body.code, body.error].filter(Boolean).join(" "));
await new Promise((r) => setTimeout(r, Math.min(15_000, 1000 * 2 ** i) * (0.5 + Math.random())));
}
}
export async function withBrowser<T>(options: Record<string, unknown>, work: (browser: Browser) => Promise<T>) {
const session = await createSession(options);
try {
const browser = await chromium.connectOverCDP(session.connectUrl, { timeout: 120_000 });
try {
return await work(browser);
} finally {
await browser.close().catch(() => {});
}
} finally {
// Ends the session if closing the browser did not (a no-op otherwise).
await fetch(API + "/" + session.id, { method: "DELETE", headers: AUTH }).catch(() => {});
}
}
// await withBrowser({ profile: { name: "shop", persist: true }, country: "de" }, async (browser) => {
// const page = browser.contexts()[0].pages()[0];
// await page.goto("https://example.com");
// });Uploader des fichiers
Une page qui demande un fichier — un <input type="file">, un bouton « parcourir », une zone de glisser-déposer — en accepte un de la même façon dans un navigateur hébergé que dans un navigateur local. Le fichier est lu sur votre machine et ses octets transitent par la connexion : le navigateur ne voit donc jamais de chemin sur votre disque, et vous pouvez uploader un fichier qui n’existe que là où s’exécute votre script. La limite est de 50 MB par fichier.
Playwright est le plus simple. setInputFiles place un fichier directement dans l’input, sans aucun clic, et fonctionne même quand l’input est caché — beaucoup de sites masquent le véritable input derrière un bouton stylé, visez donc l’input lui-même plutôt que de cliquer.
// Node.js + Playwright
await page.setInputFiles("input[type=file]", "C:/Users/me/invoice.pdf");
// or build the file in your script, with nothing on disk:
await page.setInputFiles("input[type=file]", {
name: "invoice.pdf",
mimeType: "application/pdf",
buffer: Buffer.from("%PDF-1.4 …"),
});# Python + Playwright
page.set_input_files("input[type=file]", "/home/me/invoice.pdf")Quand un bouton ouvre la boîte de dialogue de fichiers du système et qu’il n’y a aucun input à viser, interceptez plutôt le sélecteur de fichiers :
const [chooser] = await Promise.all([
page.waitForEvent("filechooser"),
page.click("text=Browse"), // the page's own button
]);
await chooser.setFiles("C:/Users/me/invoice.pdf");Puppeteer. elementHandle.uploadFile() et fileChooser.accept() ne sont pas disponibles sur les navigateurs hébergés : ils indiquent un chemin que le serveur doit lire, qui pourrait pointer n’importe où sur le worker, si bien que la passerelle les refuse. Construisez le fichier dans la page à partir des octets que vous envoyez, et transmettez-le à l’input :
// Puppeteer: construct the file in the page
const b64 = fs.readFileSync("invoice.pdf").toString("base64");
await page.evaluate(({ b64, name, type }) => {
const data = Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
const dt = new DataTransfer();
dt.items.add(new File([data], name, { type }));
const input = document.querySelector("input[type=file]");
input.files = dt.files;
input.dispatchEvent(new Event("change", { bubbles: true }));
}, { b64, name: "invoice.pdf", type: "application/pdf" });Le même DataTransfer pilote une zone de glisser-déposer : envoyez-y dragenter, dragover et drop en leur faisant porter cet objet. Un vrai glissement CDP avec un chemin local (Input.dispatchDragEvent avec des fichiers) est refusé pour la même raison que uploadFile().
Télécharger des fichiers
Un fichier que la page télécharge est enregistré sur notre serveur, dans le dossier propre à la session. Vous le récupérez par la connexion que votre script a déjà, avec quatre commandes du domaine Hosted, auxquelles la passerelle hébergée répond elle-même et que vous envoyez sur n’importe quelle session CDP. Le dossier est supprimé à la fin de la session : récupérez donc ce dont vous avez besoin avant de fermer le navigateur.
Playwright enregistre chaque téléchargement sous un identifiant. Hosted.listFiles affiche cet identifiant comme name du fichier et ajoute le nom que le site lui a donné ; comparez donc avec suggestedFilename() :
// Node.js + Playwright
const cdp = await browser.newBrowserCDPSession();
const [download] = await Promise.all([
page.waitForEvent("download"),
page.click("text=Export"), // whatever starts the download
]);
// Wait until the browser has finished writing it.
const isIt = (f) => f.download?.suggestedFilename === download.suggestedFilename() && f.download.state === "completed";
let file;
while (!(file = (await cdp.send("Hosted.listFiles")).files.find(isIt))) {
await new Promise((r) => setTimeout(r, 250));
}
// Read it in chunks (4 MB each unless you pass length, 8 MB at most).
const parts = [];
for (let offset = 0, eof = false; !eof; ) {
const chunk = await cdp.send("Hosted.readFile", { name: file.name, offset });
parts.push(Buffer.from(chunk.data, "base64"));
offset += chunk.bytes;
eof = chunk.eof;
}
fs.writeFileSync(download.suggestedFilename(), Buffer.concat(parts));
await cdp.send("Hosted.deleteFile", { name: file.name }); // frees room in the session's folder# Python + Playwright
import base64, time
cdp = browser.new_browser_cdp_session()
with page.expect_download() as info:
page.click("text=Export")
name = info.value.suggested_filename
def find():
for f in cdp.send("Hosted.listFiles")["files"]:
d = f.get("download") or {}
if d.get("suggestedFilename") == name and d.get("state") == "completed":
return f
file = find()
while not file:
time.sleep(0.25)
file = find()
data, offset = b"", 0
while True:
chunk = cdp.send("Hosted.readFile", {"name": file["name"], "offset": offset})
data += base64.b64decode(chunk["data"])
offset += chunk["bytes"]
if chunk["eof"]:
break
cdp.send("Hosted.deleteFile", {"name": file["name"]})Puppeteer et les autres clients qui ne modifient pas les réglages de téléchargement obtiennent le fichier sous le nom que le site lui a donné. Il apparaît une fois le téléchargement terminé ; d’ici là, le navigateur écrit un fichier .crdownload, listé avec partial: true.
// Puppeteer
const cdp = await page.createCDPSession();
await page.click("#export");
let file;
while (!(file = (await cdp.send("Hosted.listFiles")).files.find((f) => f.name === "report.csv"))) {
await new Promise((r) => setTimeout(r, 250));
}
const { data, eof } = await cdp.send("Hosted.readFile", { name: file.name }); // loop on offset for files over 4 MB| Commande | Prend | Renvoie |
|---|---|---|
Hosted.listFiles | rien | files : name, size, modified (ms), partial et download (suggestedFilename, url, state) pour un téléchargement nommé par Playwright ; plus totalBytes et limits. |
Hosted.readFile | name, offset (0), length (4 MB, 8 MB au plus) | data (base64), offset, bytes, size, eof |
Hosted.deleteFile | name | rien |
Hosted.writeFile | name, data (base64, 8 MB au plus par appel), append | name, size |
Un name est toujours un seul nom de fichier, exactement tel que listFiles le renvoie, jamais un chemin. Le dossier contient au plus 1 GB, téléchargements et fichiers que vous y mettez compris. Un navigateur qui télécharge au-delà met fin à la session (motif max_files_size) : dans une longue session, supprimez donc ce que vous avez récupéré.
Hosted.writeFile place un fichier dans le dossier de la session, pour le relire plus tard dans la même session : jusqu’à 50 MB par fichier, envoyé en appels de 8 MB au plus, avec append: true pour le reste. Les types de fichiers exécutables (.exe, .bat, .ps1 et similaires) sont refusés. Une page ne peut pas ouvrir les fichiers de ce dossier ; pour donner un fichier à une page, utilisez setInputFiles comme dans Uploader des fichiers.
Le Playground
Le Playground du tableau de bord lance l’un de ces navigateurs sous vos yeux, dans la vue en direct. Il s’ouvre sur Task : écrivez ce que le navigateur doit faire, et un agent s’en charge étape par étape. C’est une exécution d’agent, la même qu’avec POST /api/v1/runs, et chaque étape s’affiche sous What it did au fur et à mesure. Vous pouvez prendre la main dans la vue en direct à tout moment. Avec Ask me when it gets stuck activé (c’est le réglage par défaut), l’agent se met en pause quand il a besoin d’une personne, par exemple pour un code de connexion, et reprend dès que vous le marquez comme terminé.
Les pastilles sous la tâche règlent son point de départ (Start at), le pays de son IP résidentielle (Exit), s’il s’agit d’un appareil neuf ou d’un appareil qui revient (Device), et si la réponse est du texte ou du JSON dans la forme que vous indiquez (Output). More réunit toutes les autres options de session, le nombre maximal d’étapes, l’enregistrement vidéo et les secrets : écrivez {{password}} dans la tâche et saisissez sa valeur à cet endroit. Le modèle ne voit que l’espace réservé, et la valeur reste dans votre onglet : elle n’est jamais enregistrée ni intégrée à un lien.
Script exécute plutôt votre propre code. Il tourne dans un cadre isolé (sandbox) de votre onglet et parle CDP au navigateur via son WebSocket. log() écrit sous What it did, et dans More vous pouvez garder le navigateur ouvert pour que le script suivant continue dedans. Son objet page est un petit helper, pas Playwright : un script du Playground est donc une ébauche à transposer, pas un fichier à coller tel quel :
| Helper | Effet |
|---|---|
page.goto(url, { timeout? }) | Navigue et attend l’événement load. |
page.click(sel) · page.type(sel, text) · page.press(key) | Vraies saisies souris et clavier, après avoir fait défiler l’élément jusqu’à ce qu’il soit visible. |
page.evaluate(fn, ...args) | Exécute une fonction dans la page et en renvoie le résultat JSON. |
page.waitForSelector(sel, { timeout? }) · page.waitForNavigation() | Attend un élément, ou le prochain chargement de page. |
page.scroll(px) · page.screenshot({ fullPage? }) | Défilement à la molette ; un JPEG qui s’affiche dans le résultat de l’exécution. |
page.title() · page.url() · page.content() | Le titre, l’adresse et le HTML du document. |
log(...values) · sleep(ms) | Écrit une ligne sous What it did (les objets sont mis en forme) ; met en pause. |
cdp(method, params) | Une commande CDP brute envoyée au navigateur (Target.*, Browser.*, Storage.*). |
page.cdp(method, params) | Une commande CDP brute envoyée à la page (Page.*, Runtime.*, DOM.*, Network.*). |
Les erreurs indiquent la ligne du script dont elles proviennent. Save as… conserve un script dans ce navigateur.
À la fin d’une exécution, son résultat s’affiche en dessous : pour une tâche, la réponse et la page où elle s’est terminée, avec l’enregistrement si vous l’avez demandé et la chronologie complète de l’exécution ; pour un script, ses captures. Le résultat propose la même exécution sous trois autres formes. Use in code l’affiche sous forme de code pour votre propre projet : une tâche comme un appel à l’API des runs en Node, Python ou curl, un script comme le même navigateur et les mêmes options pour Playwright ou Puppeteer. Copy for AI copie un prompt pour un agent de code avec l’API, cette exécution et ses options. Share copie un lien qui transporte la tâche ou le script et ses options dans l’URL : rien n’est donc stocké de notre côté, et quiconque l’ouvre l’exécute sur son propre solde. Aucune des trois ne contient la valeur d’un secret.