command-line.md

Linha de comando

O que você vai aprender

- Como executar o Cypress na linha de comando
- Como especificar quais arquivos de especificação executar
- Como iniciar em outros navegadores
- Como registrar seus testes no Dashboard

Instalação

Este guia assume que você já leu nosso guia Instalando o Cypress e instalou o Cypress como um módulo npm. Após a instalação, você poderá executar todos os comandos neste documento a partir da raiz do seu projeto.

Como executar comandos

Como alternativa, você pode executar o Cypress como um modulo usando nossa módulo API.

Para resumir, omitimos o caminho completo para o executável cypress na documentação de cada comando.

Para executar um comando, você precisará prefixa-los afim de localizar corretamente o executável do cypress.

$(npm bin)/cypress run

...ou...

./node_modules/.bin/cypress run

...ou... (requer [email protected] ou superior)

npx cypress run

...ou usando Yarn...

yarn open

Você pode achar mais fácil adicionar o comando cypress ao objeto scripts em seu arquivo package.json e chamá-lo a partir de um script npm run.

Ao chamar um comando usando npm run, você precisa passar os argumentos do comando usando a string --. Por exemplo, se você tiver o seguinte comando definido em seu package.json.

{
  "scripts": {
    "cy:run": "cypress run"
  }
}

...e desejar executar testes a partir de um único arquivo de especificações e registrar os resultados no painel, o comando deve ser:

npm run cy:run -- --record --spec "cypress/integration/my-spec.js"

Se você estiver usando a ferramenta npx, poderá invocar o Cypress instalado localmente:

npx cypress run --record --spec "cypress/integration/my-spec.js"

Leia como normalmente organizamos e executamos scripts npm na postagem do blog Como organizo meus scripts npm.

Comandos

cypress run

Executa os testes Cypress até a conclusão. Por padrão, cypress run executará todos os testes sem controle.

cypress run [options]

Opções

Opção	Descrição
--browser, -b	Executa o Cypress no navegador com o nome fornecido. Se um caminho do sistema de arquivos for fornecido, o Cypress tentará usar o navegador nesse caminho.
--ci-build-id	Especifique um identificador exclusivo para uma execução para permitir agrupamento ou paralelização.
--config, -c	Especifique a configuração
--config-file, -C	Especifique o arquivo de configuração
--env, -e	Especifique as variáveis de ambiente
--group	Testes gravados em grupo em uma única execução
--headed	Exibe o navegador em vez de funcionar sem controle
--headless	Oculta o navegador em vez de executar o cabeçalho (padrão durante cypress run)
--help, -h	Informações de uso de saída
--key, -k	Especifique sua chave de registro secreto
--no-exit	Mantenha o Cypress Test Runner aberto após os testes em um arquivo de especificação executado
--parallel	Execute especificações gravadas em paralelo em várias máquinas
--port,-p	Substituir porta padrão
--project, -P	Caminho para um projeto específico
--quiet, -q	Se aprovado, a saída do Cypress não será impressa para o stdout. Apenas a saída do repórter Mocha configurado será impressa.
--record	Caso queira registrar a execução do teste
--reporter, -r	Especifique um repórter Mocha
--reporter-options, -o	Especifique as opções do repórter Mocha
--spec, -s	Especifique os arquivos de especificação a serem executados
--tag, -t	Identifique uma execução com uma etiqueta ou etiquetas

cypress run --browser <browser-name-or-path>

cypress run --browser chrome

O argumento "browser" pode ser definido como chrome, chromium, edge, electron, firefox para iniciar um navegador instalado em seu sistema. O Cypress tentará encontrar automaticamente o navegador instalado para você.

Para iniciar navegadores não estáveis, adicione dois pontos e o canal de lançamento desejado. Por exemplo, para iniciar o Chrome Canary, use chrome:canary.

Você também pode escolher um navegador, fornecendo um caminho:

cypress run --browser /usr/bin/chromium

Problemas com a detecção do navegador? Confira nosso guia de solução de problemas

cypress run --ci-build-id <id>

Este valor deve ser detectado automaticamente pela maioria dos provedores de CI e não é necessário defini-lo, a menos que o Cypress não seja capaz de determiná-lo.

Normalmente, isso é definido como uma variável de ambiente dentro de seu provedor de CI, definindo um único "build" ou "run".

cypress run --ci-build-id BUILD_NUMBER

Válido apenas ao fornecer um sinalizador --group ou --parallel. Leia nossa documentação de paralelização para saber mais.

cypress run --config <config>

Defina os valores de configuração. Separe vários valores com uma vírgula. Os valores definidos aqui substituem quaisquer valores definidos em seu arquivo de configuração.

cypress run --config pageLoadTimeout=100000,watchForFileChanges=false

Exemplo do mundo real

O Cypress Real World App (RWA) usa o sinalizador --config para especificar facilmente o tamanho das janelas de visualização para testes responsivos localmente e em trabalhos de CI dedicados. Exemplos:

• Scripts npm para executar o Cypress na janela de visualização móvel.

• Configuração do trabalho do ciclo de CI para executar suítes de teste na janela de visualização móvel.

cypress run --config-file <config-file>`

Você pode especificar um caminho para um arquivo JSON onde os valores de configuração são definidos. O padrão é cypress.json.

cypress run --config-file tests/cypress-config.json

Você pode passar false para desabilitar totalmente o uso de um arquivo de configuração.

cypress run --config-file false

cypress run --env <env>

Defina as variáveis de ambiente do Cypress.

cypress run --env host=api.dev.local

Passe diversas variáveis usando vírgulas e sem espaços. Os números são convertidos automaticamente para strings.

cypress open --env host=api.dev.local,port=4222

Passe um objeto como JSON em uma string.

cypress open --env flags='{"feature-a":true,"feature-b":false}'

cypress run --group <name>

Testes gravados em grupo em uma única execução.

cypress run --group develop-env

Você pode adicionar vários grupos à mesma execução, passando um nome diferente. Isso pode ajudar a distinguir grupos de especificações uns dos outros.

cypress run --group admin-tests --spec 'cypress/integration/admin/**/*'

cypress run --group user-tests --spec 'cypress/integration/user/**/*'

Especificar --ci-build-id também pode ser necessário.

Leia mais sobre agrupamento.

cypress run --headed

Por padrão, o Cypress irá executar testes sem controle durante o cypress run.

Passar --headed forçará o navegador a ser mostrado. Corresponde à forma como você executa qualquer navegador por meio do cypress open.

cypress run --headed

cypress run --no-exit

Para evitar que o Cypress Test Runner saia após a execução de testes em um arquivo de especificação, use --no-exit.

Você pode passar --headed --no-exit para ver o log de comando ou ter acesso às ferramentas do desenvolvedor após a execução de uma spec.

cypress run --headed --no-exit

cypress run --parallel

Execute especificações gravadas em paralelo em várias máquinas.

cypress run --record --parallel

Além disso, você pode passar um sinalizador --group para que ele apareça como um grupo nomeado.

cypress run --record --parallel --group e2e-staging-specs

Leia nossa documentação de paralelização para saber mais.

cypress run --port <port>

cypress run --port 8080

cypress run --project <project-path>

Para ver isso em ação, configuramos um repositório de exemplo para demonstração.

cypress run --project ./some/nested/folder

cypress run --record --key <record-key>

Grave o vídeo dos testes em execução após configurar seu projeto para gravação. Depois de configurar seu projeto, você receberá uma chave de registro.

cypress run --record --key <record_key>

Se você definir a chave de registro como a variável de ambiente CYPRESS_RECORD_KEY, poderá omitir o sinalizador --key.

Você normalmente definiria essa variável de ambiente ao executar em integração contínua.

export CYPRESS_RECORD_KEY=abc-key-123

Agora você pode omitir o sinalizador --key.

cypress run --record

Você pode ler mais sobre a gravação de execuções aqui.

cypress run --reporter <reporter>

Você pode fazer testes especificando um repórter Mocha.

cypress run --reporter json

Você pode especificar opções de repórter usando o sinalizador --reporter-options <reporter-options>.

cypress run --reporter junit --reporter-options mochaFile=result.xml,toConsole=true

cypress run --spec <spec>

Execute testes especificando um único arquivo de teste a ser executado em vez de todos os testes. O caminho de especificação deve ser um caminho absoluto ou relativo ao diretório de trabalho atual.

cypress run --spec "cypress/integration/examples/actions.spec.js"

Execute testes dentro da pasta que corresponde ao glob (Observação: o uso de aspas duplas é altamente recomendado).

cypress run --spec "cypress/integration/login/**/*"

Execute testes especificando vários arquivos de teste a serem executados.

cypress run --spec "cypress/integration/examples/actions.spec.js,cypress/integration/examples/files.spec.js"

Use em combinação com o parâmetro --project. Imagine que os testes Cypress estão em uma subpasta tests/e2e do projeto atual:

app/
  node_modules/
  package.json
  tests/
    unit/
    e2e/
      cypress/
        integration/
          spec.js
      cypress.json

Se estivermos na pasta app, podemos executar as especificações usando o seguinte comando

cypress run --project tests/e2e --spec ./tests/e2e/cypress/integration/spec.js

cypress run --tag <tag>

Adicione uma ou mais tags à execução registrada. Isso pode ser usado para ajudar a identificar uma execução separada quando exibida no painel.

cypress run  --record --tag "staging"

Faça uma execução com várias tags.

cypress run --record --tag "production,nightly"

O painel exibirá todas as tags enviadas com a execução apropriada.

Código de saída

Quando o Cypress termina a execução dos testes, ele sai. Se não houver testes com falha, o código de saída será 0.

## Todos os testes passam
$ cypress run
...
                                        Tests  Passing  Failing
    ✔  All specs passed!      00:16       17       17        0

## imprimir código de saída no Mac ou Linux
$ echo $?
0

Se houver alguma falha de teste, o código de saída corresponderá ao número de testes que falharam.

## Especificação com dois testes de falha
$ cypress run
...
                                        Tests  Passing  Failing
    ✖  1 of 1 failed (100%)   00:22       17       14        2

## imprimir código de saída no Mac ou Linux
$ echo $?
2

Se o Cypress não puder ser executado por algum motivo (por exemplo, se nenhum arquivo de especificação for encontrado), o código de saída será 1.

## Nenhum arquivo de especificação encontrado
$ cypress run --spec not-found.js
...
Can t run because no spec files were found.

We searched for any files matching this glob pattern:

not-found.js

## imprimir código de saída no Mac ou Linux
$ echo $?
1

cypress open

Abre o Cypress Test Runner.

cypress open [options]

Opções

As opções passadas para cypress open serão aplicadas automaticamente ao projeto que você abrir. Eles persistem em todos os projetos até que você saia do Cypress Test Runner. Essas opções também substituirão os valores em seu arquivo de configuração (cypress.json por padrão).

Opção	Descrição
--browser, -b	Caminho para um navegador personalizado a ser adicionado à lista de navegadores disponíveis no Cypress
--config, -c	Especifique a configuração
--config-file, -C	Especifique o arquivo de configuração
--detached, -d	Abra o Cypress em modo independente
--env, -e	Especifique as variáveis de ambiente
--global	Executar em modo global
--help, -h	Informações do uso de saída
--port, -p	Substituir porta padrão
--project, -P	Caminho para um projeto específico

cypress open --browser <browser-path>

Por padrão, o Cypress encontrará automaticamente e permitirá que você use os navegadores instalados em seu sistema.

A opção "browser" permite que você especifique o caminho para um navegador personalizado para usar com o Cypress:

cypress open --browser /usr/bin/chromium

Se encontrado, o navegador especificado será adicionado à lista de navegadores disponíveis no Cypress Test Runner.

Atualmente, apenas navegadores da família Chrome (incluindo o novo Microsoft Edge e Brave baseado em Chromium) e Firefox são suportados.

Está tendo problemas para iniciar um navegador? Confira nosso guia de solução de problemas

cypress open --config <config>

Defina os valores de configuração. Separe vários valores com uma vírgula. Os valores definidos aqui substituem quaisquer valores definidos em seu arquivo de configuração.

cypress open --config pageLoadTimeout=100000,watchForFileChanges=false

cypress open --config-file <config-file>

Você pode especificar um caminho para um arquivo JSON onde os valores de configuração são definidos. O padrão é cypress.json.

cypress open --config-file tests/cypress-config.json

Você pode passar false para desabilitar totalmente o uso de um arquivo de configuração.

cypress open --config-file false

cypress open --env <env>

Defina as variáveis de ambiente do Cypress.

cypress open --env host=api.dev.local

Passe várias variáveis usando vírgulas e sem espaços. Os números são convertidos automaticamente para strings.

cypress open --env host=api.dev.local,port=4222

Passe um objeto como JSON em uma string.

cypress open --env flags='{"feature-a":true,"feature-b":false}'

cypress open --global

Abrir o Cypress no modo global é útil se você tiver vários projetos aninhados, mas quiser compartilhar uma única instalação global do Cypress. Neste caso, você pode adicionar cada projeto aninhado ao Cypress no modo global, dando a você uma bela UI para alternar entre eles.

cypress open --global

cypress open --port <port>

cypress open --port 8080

cypress open --project <project-path>

Para ver isso em ação, configuramos um repositório de exemplo para demonstração.

cypress open --project ./some/nested/folder

cypress info

Imprime informações sobre o Cypress e o ambiente atual, como:

• Uma lista de navegadores Cypress detectados na máquina.
• Quaisquer variáveis de ambiente que controlam a configuração do proxy.
• Quaisquer variáveis de ambiente que começam com o prefixo CYPRESS (com variáveis confidenciais, como chave de registro mascarada para segurança).
• O local onde os dados de tempo de execução são armazenados.
• O local onde o binário do Cypress está armazenado em cache.
• Informações do sistema operacional.
• Memória do sistema incluindo espaço livre.

cypress info
Displaying Cypress info...

Detected 2 browsers installed:

1. Chrome
  - Name: chrome
  - Channel: stable
  - Version: 79.0.3945.130
  - Executable: /path/to/google-chrome
  - Profile: /user/profile/folder/for/google-chrome

2. Firefox Nightly
  - Name: firefox
  - Channel: nightly
  - Version: 74.0a1
  - Executable: /path/to/firefox

Note: to run these browsers, pass <name>:<channel> to the '--browser' field

Examples:
- cypress run --browser firefox:nightly
- cypress run --browser chrome

Learn More: https://on.cypress.io/launching-browsers

Proxy Settings: none detected
Environment Variables: none detected

Application Data: /path/to/app/data/cypress/cy/development
Browser Profiles: /path/to/app/data/cypress/cy/development/browsers
Binary Caches: /user/profile/path/.cache/Cypress

Cypress Version: 4.1.0
System Platform: darwin (19.2.0)
System Memory: 17.2 GB free 670 MB

Dica: defina a variável de ambiente DEBUG como cypress:launcherao executar cypress info para solucionar problemas de detecção do navegador.

cypress verify

Verifica se o Cypress está instalado corretamente e é executável.

cypress verify
✔  Verified Cypress! /Users/jane/Library/Caches/Cypress/3.0.0/Cypress.app

cypress version

Imprime a versão binária do Cypress instalada, a versão do pacote do Cypress, a versão do Electron usada para construir o Cypress e a versão do Node agrupada.

Na maioria dos casos, as versões do binário e do pacote serão iguais, mas podem ser diferentes se você tiver instalado uma versão diferente do pacote e por algum motivo não tiver instalado a versão binária correspondente.

cypress version
Cypress package version: 6.0.0
Cypress binary version: 6.0.0
Electron version: 10.1.5
Bundled Node version: 12.14.1

Você também pode imprimir o número da versão de cada componente individualmente.

cypress version --component package
6.0.0
cypress version --component binary
6.0.0
cypress version --component electron
10.1.5
cypress version --component node
12.14.1

cypress cache [command]

Comandos para gerenciar o cache global do Cypress. O cache do Cypress se aplica a todas as instalações do Cypress em sua máquina, globais ou não.

cypress cache path

Imprime o path para a pasta de cache do Cypress. Você pode alterar o caminho onde o cache do Cypress está localizado seguindo estas instruções.

cypress cache path
/Users/jane/Library/Caches/Cypress

cypress cache list

Imprima todas as versões existentes do Cypress instaladas. A saída será uma tabela com versões em cache e a última vez que o binário foi usado pelo usuário, determinada a partir do momento de acesso ao arquivo.

cypress cache list
┌─────────┬──────────────┐
│ version │ last used    │
├─────────┼──────────────┤
│ 3.0.0   │ 3 months ago │
├─────────┼──────────────┤
│ 3.0.1   │ 5 days ago   │
└─────────┴──────────────┘

Você pode calcular o tamanho de cada pasta de versão do Cypress adicionando o argumento --size ao comando. Observe que o cálculo do tamanho do disco pode ser lento.

cypress cache list --size
┌─────────┬──────────────┬─────────┐
│ version │ last used    │ size    │
├─────────┼──────────────┼─────────┤
│ 5.0.0   │ 3 months ago │ 425.3MB │
├─────────┼──────────────┼─────────┤
│ 5.3.0   │ 5 days ago   │ 436.3MB │
└─────────┴──────────────┴─────────┘

cypress cache clear

Limpa o conteúdo do cache do Cypress. Isso é útil quando você deseja que o Cypress limpe todas as versões instaladas do Cypress que podem estar armazenadas em cache em sua máquina. Depois de executar este comando, você precisará executar cypress install antes de executar o Cypress novamente.

cypress cache clear

cypress cache prune

Exclui todas as versões Cypress instaladas do cache, exceto a versão atualmente instalada.

cypress cache prune

Comandos de depuração

Habilitar registros de depuração

O Cypress é construído usando o módulo de depuração. Isso significa que você pode receber resultados de depuração úteis executando Cypress com ele ativado antes de executar cypress open ou cypress run.

No Mac ou Linux

DEBUG=cypress:* cypress open

DEBUG=cypress:* cypress run

No Windows

set DEBUG=cypress:*

cypress run

Cypress é um projeto bastante grande e complexo envolvendo uma dúzia ou mais de submódulos, e a saída padrão pode ser muito pesada.

Para filtrar a saída de depuração para um módulo específico

DEBUG=cypress:cli cypress run

DEBUG=cypress:launcher cypress run

...ou mesmo um submódulo profundo de 3º nível

DEBUG=cypress:server:project cypress run

História

Versão	Alterar
5.4.0	Adicionado o subcomando prune ao cypress cache
5.4.0	Adicionada a sinalização --size ao subcomando cypress cache list
4.9.0	Adicionada o sinalizador --quiet ao cypress run

Voltar para o topo