Testes de sistema ponta a ponta para temas e componentes de tema

Documentação Guias do Desenvolvedor
,
1

A escrita de testes automatizados para temas é uma parte importante do processo de desenvolvimento de temas, o que pode ajudar a garantir que os recursos introduzidos por um tema continuem a funcionar bem ao longo do tempo com os recursos principais do Discourse.

Atualmente, o Discourse suporta duas maneiras de escrever testes de regressão para temas. A primeira segue principalmente a maneira do EmberJS e envolve apenas testar o código do lado do cliente. A segunda maneira é escrever testes de sistema do Rails, que permite testar o código do lado do servidor e o código do lado do cliente ao mesmo tempo. Este documento se concentrará na escrita de testes de sistema do Rails para temas e é no que recomendamos que os autores de temas se concentrem ao escrever testes para seus temas também.

Testes de sistema do Rails para temas

Nos bastidores, o Discourse usa as estruturas de teste RSpec e Capybara para executar testes de sistema do Rails. Conhecimento básico sobre RSpec e Capybara é necessário para começar e recomendamos a leitura dos links a seguir antes de começar:

Diretrizes e dicas para escrever testes de sistema de temas

Estas são algumas diretrizes a serem seguidas ao escrever testes de sistema:

  • Espera-se que os testes de sistema estejam localizados no diretório spec/system no diretório do tema.

  • Espera-se que cada arquivo no diretório spec/system siga o formato \u003cdescrição_do_teste_do_sistema\u003e_spec.rb.

  • O bloco describe de nível superior do RSpec precisa ter a metadados system: true presente. Exemplo:

    RSpec.describe "Testando Um Tema ou Componente de Tema", system: true do
  it "exibe o componente" do
    ...
  end
end

  • Os métodos auxiliares upload_theme e upload_theme_component estão disponíveis e precisam ser chamados antes que os testes sejam executados. Exemplo:

    RSpec.describe "Testando Um Tema ou Componente de Tema", system: true do
  let!(:theme) do
    upload_theme
  end

  # ou `upload_theme_component` se o seu tema for um componente
  #
  # let!(:theme_component) do
  #   upload_theme_component
  # end

  it "exibe o componente" do
    ...
  end
end

  • A configuração de um tema pode ser alterada no teste de sistema chamando o método update_setting no objeto theme e depois salvando o tema.

    Exemplo:

    RSpec.describe "Testando Um Tema", system: true do
  let!(:theme) do
    upload_theme
  end

  it "não exibe o tema quando a configuração do tema `should_render` é falsa" do
    theme.update_setting(:should_render, false)
    theme.save!

    expect(page).not_to have_css("#some-identifier")
  end
end

  • O Discourse usa a gem fabrication, que nos permite configurar facilmente os dados de teste de que precisamos para cada teste. A lista completa de fabricators disponíveis no núcleo do Discourse também pode ser usada no teste de sistema do tema.

    Exemplo:

    RSpec.describe "Testando Um Tema", system: true do
  let!(:theme) do
    upload_theme
  end

  it "exibe o tema" do
    user = Fabricate(:user)
    category = Fabricate(:category)
    topic = Fabricate(:topic)
    topic_2 = Fabricate(:topic, title: "Este é o tópico número 2")

    ...
  end
end

  • Use o método auxiliar sign_in para testar contra diferentes perfis de usuário.

    Exemplo:

    RSpec.describe "Testando Um Tema", system: true do
  let!(:theme) do
    upload_theme
  end

  it "não exibe o tema para um usuário regular" do
    user = Fabricate(:user)
    sign_in(user)

    ...
  end

  it "exibe o tema para um usuário da equipe" do
    admin = Fabricate(:admin)
    sign_in(admin)

    ...
  end
end

  • Às vezes, você desejará facilitar e tornar mais reutilizável a consulta e inspeção de partes da página para seus testes de sistema. Para fazer isso, você pode usar o conceito de PageObjects, que você verá feito com frequência no núcleo.

    Exemplo:

    # frozen_string_literal: true

module PageObjects
  module Components
    class MyCustomComponent < PageObjects::Components::Base
      COMPONENT_SELECTOR = ".my-custom-component"

      def click_action_button
        find("#{COMPONENT_SELECTOR} .action-button").click
      end

      def has_content?(content)
        has_css?("#{COMPONENT_SELECTOR} .content", text: content)
      end
    end
  end
end

    e você pode então usá-lo importando-o com o require_relative integrado do Ruby no topo do seu arquivo de teste de sistema.

    require_relative "page_objects/components/my_custom_component"

Executando testes de sistema de temas

Os testes de sistema de temas podem ser executados usando a gem discourse_theme CLI e podem ser instalados com estas instruções.

Depois que a CLI discourse_theme for instalada, você pode executar todos os testes de sistema no diretório do seu tema executando o seguinte comando:

discourse_theme rspec .

Na primeira execução do comando rspec para um novo tema, você será questionado se gostaria de executar os testes de sistema usando um ambiente de desenvolvimento Discourse local ou um contêiner Docker que terá o ambiente de desenvolvimento configurado para você. A menos que você seja um desenvolvedor experiente de plugins ou temas do Discourse, recomendamos selecionar n e executar os testes usando um contêiner Docker, pois tudo funcionará imediatamente.

O comando discourse_theme rspec também suporta a execução de um diretório de especificação, arquivo e arquivo com números de linha.

discourse_theme rspec /caminho/para/tema/spec/system
discourse_theme rspec /caminho/para/tema/spec/system/meu_sistema_spec.rb
discourse_theme rspec /caminho/para/tema/spec/system/meu_sistema_spec.rb:12

Modo com cabeça (Headful mode)

Por padrão, os testes de sistema de temas são executados usando o Google Chrome no modo sem cabeça (headless mode). Este é um modo em que o navegador não renderiza nada na tela, permitindo que as execuções de teste sejam concluídas mais rapidamente. No entanto, muitas vezes é útil poder ver o que o teste de sistema que você escreveu está fazendo usando o Google Chrome no modo com cabeça. Você pode habilitar este modo passando a opção --headful para o comando discourse_theme rspec.

discourse_theme rspec . --headful

O comando acima executará os testes de sistema no modo com cabeça, onde a execução dos testes pode ser vista visualmente.

Você também pode pausar a execução do teste em seu caso de teste usando o método auxiliar pause_test, permitindo inspecionar o estado atual da aplicação no navegador.

Exemplo:

RSpec.describe "Testando Um Tema", system: true do
  let!(:theme) do
    upload_theme
  end

  it "exibe o tema" do
    visit("/")
    click("#some-button")
    pause_test
    # ...
  end
end

Este documento é controlado por versão - sugira alterações no github.

18 curtidas
6

Notei que, geralmente, nos testes de componentes, let!(:theme) é usado em vez de let!(:theme_component). Por exemplo, neste teste:

No entanto, o guia sugere usar let!(:theme_component) para componentes de tema:

Existe algum motivo pelo qual eu deveria usar theme_component, como descrito neste guia?

2 curtidas