Teste de sistema de ponta a ponta para temas e componentes de temas

Documentação Guias do Desenvolvedor
,
1 
<div data-theme-toc="true"> </div>

Escrever testes automatizados para temas é uma parte importante do processo de desenvolvimento de temas, pois 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 o teste do código do lado do cliente. A segunda maneira é escrever testes de sistema Rails, que permitem testar o código do lado do servidor e o código do lado do cliente ao mesmo tempo. Este documento se concentrará em escrever testes de sistema Rails para temas e é o que recomendamos que os autores de temas também se concentrem ao escrever testes para seus temas.

Testes de sistema Rails para temas

Por baixo dos panos, o Discourse usa os frameworks de teste RSpec e Capybara para executar testes de sistema Rails. Conhecimento básico sobre RSpec e Capybara é necessário para começar e recomendamos a leitura dos seguintes links 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_de_sistema\u003e_spec.rb.

  • O bloco describe RSpec de nível superior precisa ter os metadados system: true presentes. Exemplo:

    RSpec.describe "Testing A Theme or Theme Component", system: true do
  it "displays the component" 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 "Testing A Theme or Theme Component", 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 "displays the component" do
    ...
  end
end

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

    Exemplo:

    RSpec.describe "Testing A Theme", system: true do
  let!(:theme) do
    upload_theme
  end

  it "does not display the theme when the `should_render` theme setting is false" do
    theme.update_setting(:should_render, false)
    theme.save!

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

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

    Exemplo:

    RSpec.describe "Testing A Theme", system: true do
  let!(:theme) do
    upload_theme
  end

  it "displays the theme" do
    user = Fabricate(:user)
    category = Fabricate(:category)
    topic = Fabricate(:topic)
    topic_2 = Fabricate(:topic, title: "This is topic number 2")

    ...
  end
end

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

    Exemplo:

    RSpec.describe "Testing A Theme", system: true do
  let!(:theme) do
    upload_theme
  end

  it "does not display the theme for a regular user" do
    user = Fabricate(:user)
    sign_in(user)

    ...
  end

  it "displays the theme for a staff user" do
    admin = Fabricate(:admin)
    sign_in(admin)

    ...
  end
end

  • Às vezes, você vai querer tornar a consulta e a inspeção de partes da página mais fáceis e reutilizáveis para seus testes de sistema. Para fazer isso, você pode usar o conceito de PageObjects, que você verá frequentemente no core.

    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 o rubygem CLI discourse_theme e podem ser instalados com estas instruções.

Depois que a CLI discourse_theme for instalada, você poderá 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á perguntado se deseja 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 único diretório de spec, arquivo e arquivo com números de linha.

discourse_theme rspec /path/to/theme/spec/system
discourse_theme rspec /path/to/theme/spec/system/my_system_spec.rb
discourse_theme rspec /path/to/theme/spec/system/my_system_spec.rb:12

Modo Headful

Por padrão, os testes de sistema de temas são executados usando o Google Chrome no modo headless. Este é um modo onde o navegador não renderiza nada na tela, permitindo que as execuções de teste terminem 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 headful. 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 em modo headful, 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 que você inspecione o estado atual da aplicação no navegador.

Exemplo:

RSpec.describe "Testing A Theme", system: true do
  let!(:theme) do
    upload_theme
  end

  it "displays the theme" do
    visit("/")
    click("#some-button")
    pause_test
    # ...
  end
end

Este documento é versionado - 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