Puppeteer JS - Automatyzacja przeglądarki w Node.js bez pułapek

Puppeteer JS to jedna z najbardziej praktycznych bibliotek do automatyzacji przeglądarki w Node.js. Pozwala sterować Chrome lub Firefox, wykonywać kliknięcia i wpisywanie tekstu, przechwytywać ruch sieciowy oraz generować zrzuty ekranu albo PDF-y bez ręcznej obsługi okna przeglądarki. W tym artykule pokazuję, jak działa w codziennej pracy, kiedy naprawdę się przydaje i jakie pułapki najczęściej zaskakują na starcie.

Czym jest Puppeteer i kiedy daje największy zwrot

Najprościej mówiąc, Puppeteer jest warstwą sterującą nad przeglądarką. Zamiast klikać ręcznie, wysyłasz z Node.js polecenia do przeglądarki i pracujesz na stronie tak, jak robiłby to użytkownik, tylko szybciej i powtarzalnie. To narzędzie wyrasta z ekosystemu Chrome, ale obecnie obsługuje też Firefoxa, więc nie jest już wyłącznie „chromowym” dodatkiem do automatyzacji.

Największą wartość widzę tam, gdzie interfejs webowy jest dynamiczny, zbudowany w JavaScript i trudno go sensownie obsłużyć samym HTTP. Jeśli chcesz wyciągnąć dane z aplikacji SPA, zautomatyzować logowanie, wygenerować raport albo przetestować krytyczny przepływ użytkownika, Puppeteer często daje najlepszy stosunek prostoty do możliwości. Jeśli jednak serwis ma stabilne API, to ja zaczynam od API, a nie od przeglądarki, bo automatyzacja UI jest cięższa i bardziej podatna na zmiany.

Skoro wiadomo już, po co to narzędzie istnieje, przejdźmy do pierwszego sensownego uruchomienia bez zbędnej konfiguracji.

Jak zacząć w Node.js bez zbędnej konfiguracji

Start jest prosty. W typowym projekcie instalujesz bibliotekę, uruchamiasz przeglądarkę, tworzysz kartę i zaczynasz pracę z konkretną stroną. W aktualnym wydaniu Puppeteer po instalacji pobiera dopasowaną wersję Chrome for Testing, więc na początek nie musisz osobno szukać browsera ani ręcznie pilnować zgodności wersji.

Jeśli chcesz tylko prosty, działający przykład, to poniższy wariant jest wystarczający do większości testów i skryptów pomocniczych:

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  headless: true,
});

const page = await browser.newPage();

await page.goto(process.env.TARGET_URL, {
  waitUntil: 'networkidle2',
});

console.log(await page.title());

await page.screenshot({
  path: 'widok.png',
  fullPage: true,
});

await browser.close();

W praktyce nie traktuję `networkidle2` jako jedynego warunku gotowości. Przy nowoczesnych aplikacjach częściej czekam na konkretny selektor, tekst albo stan komponentu, bo sieć może „milknąć” wcześniej niż UI faktycznie będzie gotowe. To drobna różnica, ale właśnie ona odróżnia stabilny skrypt od kruchego.

Gdy start już działa, naturalnie pojawia się pytanie: co konkretnie da się tym narzędziem zrobić na co dzień?

Co da się zautomatyzować bez walki z przeglądarką

Najczęściej używam Puppeteera do czterech rzeczy: zbierania danych z dynamicznych stron, tworzenia zrzutów ekranu, generowania PDF-ów i wykonywania prostych przepływów w aplikacjach webowych. To są zadania, które w teorii da się zrobić ręcznie, ale w praktyce szybko stają się powtarzalne i podatne na pomyłki.

Zrzuty ekranu i raporty PDF

To jeden z najprostszych i najbardziej opłacalnych scenariuszy. Zrzuty ekranu przydają się w monitoringu wizualnym, dokumentacji i raportach błędów, a PDF-y są naturalne tam, gdzie z aplikacji webowej chcesz wyprowadzić fakturę, potwierdzenie albo wydruk raportu.

await page.screenshot({
  path: 'widok.png',
  fullPage: true,
});

await page.pdf({
  path: 'raport.pdf',
  format: 'A4',
  printBackground: true,
});

Jeśli generujesz dokumenty, dopilnuj fontów i stylów drukowania. Sama funkcja zadziała, ale bez przemyślanego CSS efekt bywa słabszy niż oczekujesz. W tym obszarze szczegóły wizualne mają większe znaczenie, niż zwykle się zakłada.

Interakcje z formularzami i UI

Automatyzacja kliknięć i wpisywania tekstu ma sens wtedy, gdy przepływ jest przewidywalny. Zamiast ręcznie przechodzić przez ten sam formularz dziesiątki razy, możesz zbudować jeden skrypt, który robi to za każdym razem tak samo.

await page.type('#search', 'automatyzacja');
await page.click('button[type="submit"]');
await page.waitForSelector('.wyniki');

Najważniejsze nie są tu same metody, tylko selektory. Jeśli oparłeś się na kruchym CSS-ie albo dynamicznych klasach generowanych przez framework, skrypt zacznie się sypać przy pierwszej większej zmianie frontendu. Stabilny selektor to często większa oszczędność czasu niż najbardziej efektowna funkcja API.

Kontrola ruchu sieciowego

Puppeteer daje też dostęp do ruchu sieciowego. To przydaje się, gdy chcesz blokować obrazy, mockować odpowiedzi albo przyspieszyć testy, które nie potrzebują całej zawartości strony. W takich scenariuszach oszczędzasz zarówno transfer, jak i czas ładowania.

await page.setRequestInterception(true);

page.on('request', request => {
  if (request.resourceType() === 'image') {
    request.abort();
    return;
  }

  request.continue();
});

Tu trzeba uważać na jeden detal: po włączeniu przechwytywania każde żądanie musi zostać obsłużone, czyli kontynuowane, odrzucone albo odesłane z odpowiedzią. Jeśli o tym zapomnisz, strona potrafi po prostu stanąć. To jeden z tych błędów, które wyglądają jak „magiczny problem z przeglądarką”, a są zwykłym brakiem obsługi zdarzenia.

Żeby te scenariusze działały stabilnie, trzeba dobrze rozumieć różnicę między pakietem, przeglądarką i trybem uruchomienia. I właśnie do tego teraz przechodzę.

Puppeteer, puppeteer-core i tryby uruchomienia

Tu najczęściej pojawia się nieporozumienie. `puppeteer` i `puppeteer-core` nie są tym samym, a tryb headless to dziś kilka wariantów, nie tylko jeden przełącznik. W praktyce wybór tej opcji wpływa na wygodę pracy, rozmiar instalacji i to, jak skrypt zachowuje się w CI albo Dockerze.

Różnica między `puppeteer` a `puppeteer-core`

Ja traktuję `puppeteer-core` jako wersję dla bardziej świadomego wdrożenia. Jeśli tworzysz skrypt użytkowy, najczęściej wygrywa pełny `puppeteer`. Jeśli budujesz środowisko testowe albo integrację z własną infrastrukturą browserów, wersja core daje większą kontrolę.

Tryb headless, headful i `chrome-headless-shell`

Domyślny tryb headless jest najlepszy do CI, scraperów i zadań wykonywanych w tle. Tryb headful, czyli widoczna przeglądarka, wybieram wtedy, gdy chcę zobaczyć, gdzie dokładnie przepływ się łamie. Z kolei `chrome-headless-shell` przydaje się, gdy bardziej liczy się wydajność niż pełna zgodność z funkcjami zwykłego Chrome.

W aktualnym modelu Puppeteer nie myśl już o headless jak o „ukrytym oknie”. To osobny sposób uruchomienia, a w starszych wersjach stary headless funkcjonował inaczej niż obecny. Jeśli zależy Ci na maksymalnej zgodności z normalnym Chrome, trzymaj się standardowego trybu headless, a `shell` włączaj dopiero wtedy, gdy naprawdę potrzebujesz szybszego działania i akceptujesz ograniczenia.

Przeczytaj również: Pętla for w JavaScript - Pełny przewodnik i przykłady

Chrome, Firefox i protokoły sterowania

Od nowszych wersji Puppeteer wspiera Chrome i Firefox, a to ważne, bo nie każdy scenariusz zachowuje się identycznie w obu przeglądarkach. Chrome domyślnie działa przez CDP, natomiast Firefox korzysta z WebDriver BiDi. To otwiera drogę do większej przenośności, ale wciąż nie oznacza pełnej identyczności API we wszystkich detalach.

Jeśli budujesz coś prostego, to różnica może być dla Ciebie niemal niewidoczna. Jeśli jednak używasz mniej typowych funkcji, testujesz granularnie sieć albo pracujesz na kilku przeglądarkach, warto sprawdzić kompatybilność konkretnej metody. To właśnie ten moment, w którym techniczna dokładność oszczędza godzinę późniejszego debugowania.

Gdy już wiesz, jak dobrać wariant narzędzia, warto zobaczyć, co najczęściej psuje skrypty w praktyce.

Najczęstsze błędy, które psują skrypty

W automatyzacji przeglądarki błędy rzadko są spektakularne. Częściej wyglądają jak „czasem działa, a czasem nie”. Z mojego doświadczenia zwykle winny jest nie sam Puppeteer, tylko sposób, w jaki został użyty.

• Sztywne opóźnienia zamiast warunków. `setTimeout` maskuje problem, ale go nie rozwiązuje. Lepiej czekać na konkretny selektor, tekst lub stan elementu.
• Zbyt kruche selektory. Klasę generowaną przez framework łatwo zmienić przypadkiem. Stabilniejszy jest selektor oparty na semantyce lub atrybucie testowym.
• Brak domykania browsera. Jeśli nie zamykasz instancji, w testach i zadaniach wsadowych zaczynasz kolekcjonować procesy i wycieki zasobów.
• Przekonanie, że `goto` oznacza gotową stronę. Strona może załadować HTML, ale komponenty Reacta albo dane z API nadal będą się renderować.
• Ignorowanie środowiska uruchomieniowego. Docker i CI często potrzebują dodatkowych zależności systemowych, fontów albo odpowiednich flag startowych.
• Nadmierne przechwytywanie żądań. Jeśli filtrujesz ruch bez konsekwentnej obsługi wszystkich przypadków, możesz zatrzymać stronę w połowie ładowania.

Najbardziej kosztowne błędy nie są efektowne, tylko powtarzalne. Jeśli dołożysz do tego brak logów i zrzutów stanu przy awarii, debugowanie staje się niepotrzebnie drogie. Z tego miejsca naturalnie wychodzi pytanie, czy Puppeteer jest najlepszym wyborem, czy tylko wygodnym pierwszym krokiem.

Kiedy wybrać Puppeteera, a kiedy lepiej sięgnąć po inną bibliotekę

W praktyce wybór zależy od tego, co jest dla Ciebie najważniejsze: szybkość wejścia, pokrycie przeglądarek, ergonomia testów czy zgodność z istniejącym stackiem. Ja zwykle zaczynam od prostego pytania: czy potrzebuję przede wszystkim sterować Chrome, czy budować szeroki zestaw testów end-to-end.

Jeśli pracujesz głównie w JavaScript i chcesz szybko przejść od pomysłu do działającego skryptu, Puppeteer zwykle wygrywa prostotą. Jeśli potrzebujesz mocnego ekosystemu testowego i szerokiego pokrycia przeglądarek, wtedy sensownie jest sprawdzić Playwrighta. Gdy zespół jest już mocno osadzony w WebDriverze, Selenium nadal ma swoje miejsce, ale to rzadziej jest mój pierwszy wybór dla nowych projektów.

Na tym etapie zostaje ostatnia rzecz, która w praktyce odróżnia eksperyment od rozwiązania gotowego do użycia w projekcie.

Co sprawdzam przed wdrożeniem w projekcie

Jeśli mam podchodzić do automatyzacji pragmatycznie, zawsze sprawdzam kilka punktów zanim uznam zadanie za zamknięte. To zwykle oszczędza więcej czasu niż późniejsze „naprawianie” skryptu po pierwszym wdrożeniu.

• Środowisko uruchomienia. Czy skrypt działa lokalnie, w CI, w Dockerze czy na serwerze z ograniczonymi zasobami?
• Dobór pakietu. Czy wystarczy pełny `puppeteer`, czy lepiej przejść na `puppeteer-core` i własny browser?
• Stabilność selektorów. Czy elementy mają sensowne atrybuty, które nie zmienią się przy drobnej przebudowie frontendu?
• Warunki oczekiwania. Czy czekasz na konkretny stan aplikacji, a nie tylko na „jakiś czas po załadowaniu”?
• Diagnostyka błędów. Czy w razie awarii zapisujesz log, screenshot albo inne artefakty, które pomogą odtworzyć problem?
• Sprzątanie po sobie. Czy browser i strony są domykane niezależnie od tego, czy krok zakończył się sukcesem, czy wyjątkiem?

Dobrze wdrożony Puppeteer daje dużą kontrolę przy małym narzucie, ale tylko wtedy, gdy traktujesz go jak część systemu, a nie jednorazowy skrypt. Jeśli pilnujesz selektorów, warunków oczekiwania i środowiska uruchomieniowego, przeglądarka przestaje być źródłem losowości, a staje się przewidywalnym komponentem.