Jak napisać pierwszy test automatyczny w Playwright i TypeScript?

Automatyzacja testów może na początku wydawać się skomplikowana. Trzeba wybrać odpowiednie narzędzie, skonfigurować projekt, zainstalować przeglądarki i poznać podstawy programowania.

W przypadku Playwright cały proces jest jednak znacznie prostszy, niż mogłoby się wydawać.

W tym poradniku utworzymy projekt testowy od podstaw, napiszemy pierwszy test automatyczny w TypeScript, uruchomimy go w przeglądarce i sprawdzimy raport z wykonania.

Czym jest Playwright?

Playwright to framework do automatyzacji testów aplikacji internetowych rozwijany przez Microsoft. Pozwala uruchamiać testy między innymi w przeglądarkach:

• Chromium,
• Firefox,
• WebKit.

Na silniku Chromium działają między innymi Google Chrome oraz Microsoft Edge, natomiast WebKit jest silnikiem wykorzystywanym przez Safari.

Playwright Test zawiera nie tylko bibliotekę do sterowania przeglądarką, ale również gotowy runner testów, asercje, obsługę równoległego wykonywania testów, raporty oraz mechanizm izolowania poszczególnych scenariuszy.

Framework dobrze współpracuje z TypeScript. Obsługa TypeScript jest dostępna bez dodatkowej konfiguracji — testy można od razu zapisywać w plikach .ts.

Czego potrzebujesz przed rozpoczęciem?

Do wykonania tego poradnika potrzebujesz:

• zainstalowanego środowiska Node.js,
• edytora kodu, na przykład Visual Studio Code,
• podstawowej znajomości TypeScript lub JavaScript,
• terminala systemowego.

Poprawność instalacji Node.js możesz sprawdzić za pomocą polecenia:

node --version

Następnie sprawdź wersję menedżera pakietów npm:

npm --version

Jeżeli oba polecenia zwrócą numery wersji, możesz przejść do tworzenia projektu.

Tworzenie projektu Playwright

Utwórz nowy katalog, w którym znajdzie się projekt testowy:

mkdir playwright-first-test

Przejdź do utworzonego katalogu:

cd playwright-first-test

Następnie uruchom oficjalny kreator projektu Playwright:

npm init playwright@latest

Podczas instalacji zobaczysz kilka pytań konfiguracyjnych.

Możesz wybrać następujące odpowiedzi:

Do you want to use TypeScript or JavaScript?
TypeScript

Where to put your end-to-end tests?
tests

Add a GitHub Actions workflow?
false

Install Playwright browsers?
true

GitHub Actions możesz również włączyć, jeżeli od razu chcesz przygotować projekt do uruchamiania testów w procesie CI/CD.

Kreator domyślnie proponuje TypeScript, katalog tests oraz instalację wymaganych przeglądarek.

Po zakończeniu instalacji projekt powinien mieć strukturę podobną do poniższej:

playwright-first-test/
├── node_modules/
├── tests/
│   └── example.spec.ts
├── package.json
├── package-lock.json
└── playwright.config.ts

Najważniejsze elementy projektu to:

• tests – katalog zawierający testy,
• playwright.config.ts – główny plik konfiguracyjny,
• package.json – lista zależności oraz skryptów projektu,
• node_modules – zainstalowane biblioteki.

Pierwszy test automatyczny

W katalogu tests utwórz plik:

first-test.spec.ts

Umieść w nim następujący kod:

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

test('strona Playwright wyświetla poprawny tytuł', async ({ page }) => {
  await page.goto('https://playwright.dev/');

  await expect(page).toHaveTitle(/Playwright/);
});

To kompletny, działający test automatyczny.

Przyjrzyjmy się teraz jego poszczególnym elementom.

Import funkcji test i expect

Na początku importujemy dwie funkcje:

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

Funkcja test służy do definiowania scenariusza testowego.

Funkcja expect pozwala tworzyć asercje, czyli sprawdzać, czy rzeczywisty rezultat działania aplikacji jest zgodny z oczekiwanym.

Definicja testu

Test został zdefiniowany w następujący sposób:

test('strona Playwright wyświetla poprawny tytuł', async ({ page }) => {
  // kroki testu
});

Pierwszym argumentem jest nazwa scenariusza:

strona Playwright wyświetla poprawny tytuł

Nazwa powinna jasno opisywać sprawdzane zachowanie. Dzięki temu łatwiej będzie zrozumieć wyniki testów i odnaleźć przyczynę ewentualnego błędu.

Drugi argument to asynchroniczna funkcja zawierająca kroki testowe.

Obiekt page reprezentuje otwartą stronę w przeglądarce. Za jego pomocą możemy między innymi:

• otwierać adresy URL,
• klikać przyciski,
• uzupełniać formularze,
• pobierać tekst,
• sprawdzać widoczność elementów.

Otwarcie strony internetowej

Pierwszy krok testu otwiera stronę Playwright:

await page.goto('https://playwright.dev/');

Słowo await oznacza, że test powinien poczekać na zakończenie operacji przed przejściem do kolejnego kroku.

Bez niego następna instrukcja mogłaby zostać wykonana zbyt wcześnie, zanim strona zdążyłaby się załadować.

Sprawdzenie tytułu strony

Następnie wykonujemy asercję:

await expect(page).toHaveTitle(/Playwright/);

Asercja sprawdza, czy tytuł strony zawiera słowo Playwright.

Zapis:

/Playwright/

jest wyrażeniem regularnym. Dzięki temu test nie wymaga idealnego dopasowania całego tytułu strony, lecz jedynie sprawdza, czy znajduje się w nim wskazany fragment.

Playwright udostępnia asercje przeznaczone specjalnie dla aplikacji webowych. Są one automatycznie ponawiane do momentu spełnienia warunku albo przekroczenia określonego czasu oczekiwania.

Uruchomienie testu

Aby uruchomić wszystkie testy w projekcie, wykonaj polecenie:

npx playwright test

Domyślnie testy są uruchamiane w trybie headless. Oznacza to, że okno przeglądarki nie jest widoczne.

W terminalu powinien pojawić się rezultat podobny do poniższego:

1 passed

Oznacza to, że test zakończył się powodzeniem.

Uruchomienie testu w widocznej przeglądarce

Podczas nauki i debugowania warto obserwować działanie testu.

Uruchom go w trybie headed:

npx playwright test --headed

Playwright otworzy wtedy okno przeglądarki i wykona zapisane operacje.

Możesz również uruchomić tylko jeden plik:

npx playwright test tests/first-test.spec.ts

Albo jeden konkretny test na podstawie jego nazwy:

npx playwright test -g "strona Playwright wyświetla poprawny tytuł"

Uruchamianie testów w trybie UI

Playwright udostępnia również interfejs graficzny do uruchamiania i analizowania testów.

Możesz go otworzyć poleceniem:

npx playwright test --ui

Tryb UI pozwala:

• uruchamiać pojedyncze testy,
• obserwować poszczególne kroki,
• filtrować scenariusze,
• analizować błędy,
• ponownie uruchamiać testy po zmianach w kodzie.

Jest to bardzo wygodne rozwiązanie podczas tworzenia nowych testów.

Test sprawdzający element na stronie

Sprawdzenie tytułu to dobry pierwszy przykład, ale w rzeczywistych projektach najczęściej będziemy wykonywać operacje na elementach strony.

Rozbudujmy test:

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

test('użytkownik może przejść do dokumentacji Playwright', async ({ page }) => {
  await page.goto('https://playwright.dev/');

  await page.getByRole('link', { name: 'Get started' }).click();

  await expect(
    page.getByRole('heading', { name: 'Installation' })
  ).toBeVisible();
});

Test wykonuje trzy działania:

1. Otwiera stronę Playwright.
2. Klika odnośnik Get started.
3. Sprawdza, czy pojawił się nagłówek Installation.

Czym są locatory?

Locator to sposób wskazania elementu na stronie.

W naszym przykładzie użyliśmy:

page.getByRole('link', { name: 'Get started' })

Kod wyszukuje element pełniący rolę odnośnika, którego dostępna nazwa to Get started.

Następnie wywołujemy na nim metodę:

.click()

Do odnajdywania elementów Playwright udostępnia między innymi:

page.getByRole()
page.getByText()
page.getByLabel()
page.getByPlaceholder()
page.getByAltText()
page.getByTitle()
page.getByTestId()

Dokumentacja Playwright zaleca preferowanie locatorów opartych na informacjach widocznych dla użytkownika, szczególnie getByRole(). Takie testy są zazwyczaj bardziej odporne na zmiany struktury kodu HTML niż długie selektory CSS lub XPath.

Przykładowo zamiast:

await page.locator(
  '#content > div:nth-child(2) > div > a'
).click();

lepiej zastosować:

await page.getByRole('link', { name: 'Get started' }).click();

Pierwszy locator jest silnie zależny od struktury dokumentu. Nawet niewielka zmiana w kodzie HTML może spowodować błąd testu.

Drugi opisuje element z perspektywy użytkownika.

Sprawdzenie widoczności elementu

Po kliknięciu odnośnika sprawdzamy widoczność nagłówka:

await expect(
  page.getByRole('heading', { name: 'Installation' })
).toBeVisible();

Metoda toBeVisible() sprawdza, czy element znajduje się na stronie i jest widoczny dla użytkownika.

Playwright automatycznie oczekuje na spełnienie warunku. Zazwyczaj nie trzeba więc dodawać ręcznych opóźnień takich jak:

await page.waitForTimeout(3000);

Stałe oczekiwanie przez określoną liczbę milisekund może niepotrzebnie wydłużać testy i prowadzić do niestabilnych rezultatów.

Jak otworzyć raport HTML?

Po zakończeniu testów możesz otworzyć raport za pomocą polecenia:

npx playwright show-report

Raport zawiera między innymi:

• nazwy wykonanych testów,
• status każdego scenariusza,
• czas wykonania,
• informacje o błędach,
• wykonane kroki,
• załączniki diagnostyczne, jeżeli zostały skonfigurowane.

Raport jest szczególnie przydatny, gdy projekt zawiera więcej testów albo gdy scenariusze są wykonywane w procesie CI/CD.

Najczęstsze błędy początkujących

Brak słowa await

Niepoprawny zapis:

page.goto('https://playwright.dev/');

Poprawny zapis:

await page.goto('https://playwright.dev/');

Większość operacji wykonywanych w przeglądarce jest asynchroniczna i wymaga zastosowania await.

Używanie długich selektorów CSS

Mało odporny locator:

page.locator('div.container > div:nth-child(2) > button')

Czytelniejszy locator:

page.getByRole('button', { name: 'Zaloguj się' })

Dodawanie ręcznych opóźnień

Nie zaleca się regularnego stosowania:

await page.waitForTimeout(5000);

Playwright posiada mechanizmy automatycznego oczekiwania. Przed wykonaniem operacji sprawdza między innymi, czy element jest dostępny i gotowy do interakcji.

Umieszczanie wielu zachowań w jednym teście

Pierwsze testy często rozrastają się do kilkudziesięciu kroków i sprawdzają jednocześnie logowanie, wyszukiwanie, koszyk oraz płatność.

Lepiej tworzyć krótsze scenariusze, z których każdy odpowiada za jedno konkretne zachowanie.

Nieczytelne nazwy testów

Mało czytelna nazwa:

test('test 1', async ({ page }) => {

Lepsza nazwa:

test('użytkownik może przejść do dokumentacji Playwright', async ({ page }) => {

Nazwa testu powinna informować, co dokładnie jest sprawdzane.

Podsumowanie

Napisanie pierwszego testu w Playwright i TypeScript wymaga wykonania tylko kilku kroków:

1. Zainstalowania Node.js.
2. Utworzenia projektu poleceniem npm init playwright@latest.
3. Dodania pliku testowego w katalogu tests.
4. Zdefiniowania testu za pomocą funkcji test.
5. Wykonania operacji na stronie przy użyciu obiektu page.
6. Sprawdzenia rezultatu za pomocą funkcji expect.
7. Uruchomienia testu poleceniem npx playwright test.

Najprostszy test może wyglądać tak:

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

test('strona Playwright wyświetla poprawny tytuł', async ({ page }) => {
  await page.goto('https://playwright.dev/');

  await expect(page).toHaveTitle(/Playwright/);
});

To dopiero początek możliwości Playwright. W kolejnych testach możesz automatyzować formularze, logowanie użytkowników, wyszukiwarki, koszyki zakupowe, zapytania API oraz kompletne procesy biznesowe.

Najważniejsze jest jednak rozpoczęcie od prostego scenariusza, zrozumienie struktury testu i stopniowe rozbudowywanie projektu.