playwright-docs

Playwright Test (JS/TS) da documentação oficial

Visão geral

Este skill contém o que a documentação do Playwright diz que é fácil de errar: regras de auto-wait, strictness, timeouts que não funcionam como esperado, pontos cegos de simulação (mocking), modos de atualização de snapshots, configurações de CI e APIs removidas. Conselhos genéricos de teste foram deixados de lado. Cada afirmação traz a URL da documentação de onde veio, para que possa ser verificada.

Versão coberta

Playwright Test 1.64.1 para Node.js e TypeScript (@playwright/test). O conteúdo para Python, Java e .NET está excluído. Quando a versão instalada for mais antiga, consulte a tabela de versões em references/version-changes.md antes de aplicar uma API mais nova.

Como navegar

1. Leia o início rápido abaixo. Ele cobre as regras que importam na maioria dos testes.
2. Abra o arquivo de referência cujo domínio corresponda à tarefa, a partir da tabela no final.
3. Antes de revisar código antigo ou atualizar, leia "Padrões antigos" abaixo e references/version-changes.md.

Início rápido

Localizadores

• Padrão: page.getByRole(role, { name }). Depois getByLabel, getByText (apenas elementos não interativos), getByTestId como fallback baseado em contrato. CSS ou XPath apenas quando nada voltado ao usuário funciona. https://playwright.dev/docs/locators#quick-guide
• Localizadores são estritos: uma ação em um localizador que corresponde a 2 elementos gera um erro. Reduza com filter({ hasText }), filter({ has }) ou inner.within(outer) em vez de usar first() / nth(). https://playwright.dev/docs/locators#strictness
• O localizador dentro de filter({ has }) é resolvido a partir da correspondência externa, nunca da raiz da página. https://playwright.dev/docs/locators#filter-by-childdescendant
• A correspondência de texto é substring e case-insensitive por padrão, e sempre normalizada por espaços em branco, mesmo com exact: true. https://playwright.dev/docs/locators#locate-by-text

Ações e espera

• As ações aguardam automaticamente pela capacidade de ação. Não adicione waitForTimeout, nem esperas manuais de carregamento antes de um clique. https://playwright.dev/docs/actionability#introduction e https://playwright.dev/docs/navigations#when-is-the-page-loaded
• fill() é o padrão para texto. pressSequentially() apenas para manipulação tecla por tecla. https://playwright.dev/docs/input#type-characters
• Eventos (popup, download, filechooser, response): crie a promessa de espera ANTES do clique, aguarde-a depois.

  const downloadPromise = page.waitForEvent('download');
  await page.getByText('Download file').click();
  const download = await downloadPromise;
  

  https://playwright.dev/docs/downloads#introduction
• Um listener de dialog que nem aceita nem dispensa trava a página. Sem listener, os diálogos são automaticamente dispensados. https://playwright.dev/docs/dialogs#alert-confirm-prompt-dialogs

Asserções

• Sempre await expect(locator).toX(). Nunca expect(await locator.isVisible()).toBe(true), que verifica apenas uma vez. https://playwright.dev/docs/best-practices#use-web-first-assertions
• O timeout de asserção é de 5 s, separado do timeout de teste de 30 s. https://playwright.dev/docs/test-timeouts
• Nenhum matcher correspondente: use expect.poll. expect(...).toPass() NÃO tem timeout por padrão, então passe um. https://playwright.dev/docs/test-assertions#expecttopass
• Use o expect do Playwright, não o do Jest. https://playwright.dev/docs/test-assertions#compatibility-with-expect-library

Estrutura e configuração

• Opções do runner no nível superior de defineConfig, opções de navegador e contexto dentro de use. https://playwright.dev/docs/test-configuration#introduction
• Fixtures em vez de pares de hooks before/after. Os testes importam test do arquivo de fixtures. https://playwright.dev/docs/test-fixtures#with-fixtures
• beforeAll executa uma vez por worker, e um worker reinicia após cada falha, então beforeAll pode executar várias vezes. https://playwright.dev/docs/test-retries#failures
• Faça login uma vez em um projeto de configuração com dependencies, salve storageState após aguardar a URL final, adicione playwright/.auth ao gitignore. https://playwright.dev/docs/auth#basic-shared-account-in-all-tests
• Espalhe um dispositivo primeiro, depois sobrescreva viewport, porque um dispositivo também define seu próprio viewport. https://playwright.dev/docs/emulation#viewport
• Playwright não faz verificação de tipos. Execute tsc --noEmit no CI e faça lint com @typescript-eslint/no-floating-promises. https://playwright.dev/docs/test-typescript#introduction e https://playwright.dev/docs/best-practices#lint-your-tests

Rede

• Registre page.route ANTES de page.goto. Um glob deve corresponder à URL completa, e ? corresponde apenas a um ponto de interrogação literal. https://playwright.dev/docs/mock#mock-api-requests e https://playwright.dev/docs/network#glob-url-patterns
• Rotas perdem requisições atendidas por um service worker. Defina serviceWorkers: 'block'. https://playwright.dev/docs/network#missing-network-events-and-service-workers
• page.request compartilha os cookies do navegador. request.newContext() é isolado e deve ser descartado. https://playwright.dev/docs/api-testing#context-request-vs-global-request

CI

• forbidOnly: !!process.env.CI, retries: process.env.CI ? 2 : 0, workers: process.env.CI ? 1 : undefined, trace: 'on-first-retry', e sempre um globalTimeout, caso contrário uma execução travada não produz relatório. https://playwright.dev/docs/test-configuration#basic-configuration e https://playwright.dev/docs/ci#global-timeout
• npx playwright install --with-deps após npm ci e após cada atualização. Não armazene navegadores em cache. https://playwright.dev/docs/ci#caching-browsers
• Faça sharding com fullyParallel: true e mescle relatórios blob. https://playwright.dev/docs/test-sharding#balancing-shards
• Serialize testes que compartilham um recurso com um lock, não com o modo serial: test('x', { lock: 'db' }, ...). https://playwright.dev/docs/test-parallel#test-locks

Snapshots

• Sem -u, um snapshot ausente é escrito E o teste falha. --update-snapshots=missing escreve e passa. -u significa changed. https://playwright.dev/docs/aria-snapshots#updating-snapshots-with-playwrighttest-and-the---update-snapshots-flag
• As baselines de screenshot são por navegador e SO. Gere-as onde serão comparadas. https://playwright.dev/docs/test-snapshots#introduction

Padrões antigos

Antigo	Atual	Fonte
locator.type(), page.type()	locator.fill(), ou pressSequentially()	https://playwright.dev/docs/release-notes#version-138
page.$(), ElementHandle, page.$eval + expect genérico	Localizador + asserção web-first	https://playwright.dev/docs/handles#locator-vs-elementhandle
expect(await locator.isVisible()).toBe(true)	await expect(locator).toBeVisible()	https://playwright.dev/docs/best-practices#dont-use-manual-assertions
Pseudo-classe :visible	locator.visible()	https://playwright.dev/docs/release-notes#version-163
Seletores text=Log in, id=, data-testid=	getByText, getByTestId	https://playwright.dev/docs/other-locators#legacy-text-locator
Seletores de layout :right-of(), :near()	localizadores visíveis ao usuário	https://playwright.dev/docs/other-locators#css-matching-elements-based-on-layout
Seletores _react, _vue	localizadores padrão	https://playwright.dev/docs/release-notes#version-158
page.accessibility	@axe-core/playwright	https://playwright.dev/docs/release-notes#version-157
globalSetup para login ou seeding	projeto de configuração com dependencies	https://playwright.dev/docs/test-global-setup-teardown#introduction
test.describe.configure({ mode: 'serial' }) para recurso compartilhado	locks de teste	https://playwright.dev/docs/test-parallel#test-locks
webServer.port	webServer.url	https://playwright.dev/docs/test-webserver#configuring-a-web-server
videosPath, videoSize	recordVideo, ou use.video no runner	https://playwright.dev/docs/release-notes#version-160
opção de inicialização devtools: true	args: ['--auto-open-devtools-for-tabs']	https://playwright.dev/docs/release-notes#version-158
flag -gv	--grep-invert ou -G	https://playwright.dev/docs/release-notes#version-154
npx playwright open para gravar	npx playwright codegen	https://playwright.dev/docs/release-notes#version-154
updateSnapshots: 'all' para atualizar os alterados	'changed' ('all' reescreve tudo)	https://playwright.dev/docs/release-notes#version-150
waitUntil: 'networkidle'	auto-waiting e asserções web-first	https://playwright.dev/docs/puppeteer#automation-example
@playwright/experimental-ct-* com JSX mount(<C />)	stories + mount('Story/Id', props) de @playwright/test	https://playwright.dev/docs/test-components#migration-from-the-experimental-packages
navegadores baixados por npm install	npx playwright install --with-deps	https://playwright.dev/docs/release-notes#version-138

Arquivos de referência

Arquivo	Leia para
references/locators.md	prioridade de localizador, correspondência de texto, strictness, filter, within, and / or, visible(), shadow DOM, frames, seletores legados
references/actions-and-events.md	verificações de capacidade de ação por ação, force, entrada, arrastar e soltar, diálogos, downloads, uploads, popups, navegação, hidratação, evaluate, scripts de inicialização, handles
references/assertions.md	matchers web-first versus genéricos, timeouts de asserção, expect.poll, toPass, asserções suaves, matchers personalizados, test.step
references/snapshots-and-accessibility.md	modos de atualização de snapshot, snapshots aria, tolerâncias e nomenclatura de toHaveScreenshot, snapshots não imagem, varreduras axe
references/configuration.md	estrutura de configuração, escopos e padrões de use, projetos e dependências, dispositivos e emulação, tratamento de TypeScript, webServer
references/timeouts-retries-annotations.md	todos os timeouts e seus padrões, repetições e reinicializações de worker, modo serial, skip / fail / fixme, tags, testes parametrizados e projetos
references/fixtures-and-auth.md	isolamento, fixtures personalizadas, escopos, opções, ordem de execução, hooks globais, projetos de configuração, page objects, autenticação storageState, papéis, contas por worker
references/network-and-mocking.md	route, regras glob, cabeçalhos e redirecionamentos que uma rota não pode tocar, gravação e reprodução de HAR, simulações WebSocket, simulações de API do navegador, service workers
references/api-testing-and-clock.md	fixture request, cookies compartilhados versus isolados, descarte de contextos, métodos page.clock e ordenação
references/ci-parallel-sharding.md	linha de base de CI, GitHub Actions e outros provedores, workers, fullyParallel, locks de teste, sharding, fusão de relatórios blob
references/browsers-and-docker.md	instalação e cache de navegadores, canais Chromium, proxies e mirrors, imagem Docker, extensões Chrome, WebView2, Selenium Grid
references/debugging-and-reporting.md	flags CLI, --debug, Inspector, modos trace e vídeo, trace viewer, UI mode, reporters
references/component-testing-and-migration.md	teste de componentes com stories e galeria, migração de pacotes ct experimentais, Testing Library, Protractor, Puppeteer
references/codegen-and-agent-tooling.md	codegen, Library versus Test, canais de release, Agentes de Teste, playwright-cli, Playwright MCP
references/version-changes.md	mudanças de comportamento que quebram compatibilidade, APIs removidas e descontinuadas com substitutos, mudanças de suporte de plataforma

Fontes e detalhes de obtenção estão listados em SOURCES.md.