Tests de bout en bout pour les thèmes et les composants de thème

Documentation Guides pour les développeurs
,
1

L’écriture de tests automatisés pour les thèmes est une partie importante du processus de développement de thèmes qui peut aider à garantir que les fonctionnalités introduites par un thème continuent de bien fonctionner au fil du temps avec les fonctionnalités de base de Discourse.

Actuellement, Discourse prend en charge deux façons d’écrire des tests de régression pour les thèmes. La première suit principalement la méthode d’EmberJS et n’implique que le test du code côté client. La seconde consiste à écrire des tests système Rails qui vous permettent de tester à la fois le code côté serveur et le code côté client en même temps. Ce document se concentrera sur l’écriture de tests système Rails pour les thèmes et est ce sur quoi nous recommandons aux auteurs de thèmes de se concentrer lors de l’écriture de tests pour leurs thèmes également.

Tests système Rails pour les thèmes

En interne, Discourse utilise les frameworks de test RSpec et Capybara pour exécuter des tests système Rails. Une connaissance de base de RSpec et Capybara est requise pour commencer, et nous vous recommandons de lire les liens suivants avant de commencer :

Directives et conseils pour l’écriture de tests système de thèmes

Voici quelques directives à suivre lors de l’écriture de tests système :

  • Les tests système doivent être situés dans le répertoire spec/system du répertoire du thème.

  • Chaque fichier dans le répertoire spec/system doit suivre le format \u003cdescription_du_test_système\u003e_spec.rb.

  • Le bloc RSpec describe de niveau supérieur doit contenir la métadonnée system: true. Exemple :

    RSpec.describe "Testing A Theme or Theme Component", system: true do
  it "displays the component" do
    ...
  end
end

  • Les méthodes d’aide upload_theme et upload_theme_component sont disponibles et doivent être appelées avant l’exécution des tests. Exemple :

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

  # ou `upload_theme_component` si votre thème est un composant
  #
  # let!(:theme_component) do
  #   upload_theme_component
  # end

  it "displays the component" do
    ...
  end
end

  • Le paramètre d’un thème peut être modifié dans le test système en appelant la méthode update_setting sur l’objet theme puis en sauvegardant le thème.

    Exemple :

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

  it "does not display the theme when `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

  • Discourse utilise la gem fabrication qui nous permet de configurer facilement les données de test dont nous avons besoin pour chaque test. La liste complète des fabricateurs disponibles dans le cœur de Discourse peut également être utilisée dans le test système du thème.

    Exemple :

    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

  • Utilisez la méthode d’aide sign_in pour tester différents profils d’utilisateur.

    Exemple :

    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

  • Parfois, vous voudrez faciliter et rendre plus réutilisable la requête et l’inspection de parties de la page pour vos tests système. Pour ce faire, vous pouvez utiliser le concept de PageObjects, que vous verrez souvent dans le cœur.

    Exemple :

    # 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

    et vous pouvez ensuite l’utiliser en l’important avec require_relative intégré à Ruby en haut de votre fichier de test système.

    require_relative "page_objects/components/my_custom_component"

Exécution des tests système de thèmes

Les tests système de thèmes peuvent être exécutés à l’aide de la gem discourse_theme CLI et peuvent être installés avec ces instructions.

Une fois que la CLI discourse_theme a été installée, vous pouvez exécuter tous les tests système dans le répertoire de votre thème en exécutant la commande suivante :

discourse_theme rspec .

Lors de la première exécution de la commande rspec pour un nouveau thème, il vous sera demandé si vous souhaitez exécuter les tests système à l’aide d’un environnement de développement Discourse local ou d’un conteneur Docker qui aura l’environnement de développement configuré pour vous. À moins que vous ne soyez un développeur de plugin ou de thème Discourse chevronné, nous vous recommandons de sélectionner n et d’exécuter les tests à l’aide d’un conteneur Docker car tout fonctionnera immédiatement.

La commande discourse_theme rspec prend également en charge l’exécution d’un seul répertoire de spécification, fichier et fichier avec numéros de ligne.

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

Mode avec interface graphique (Headful mode)

Par défaut, les tests système de thèmes sont exécutés à l’aide de Google Chrome en mode sans tête (headless mode). C’est un mode où le navigateur ne rend rien à l’écran, permettant aux exécutions de tests de se terminer plus rapidement. Cependant, il est souvent utile de pouvoir voir ce que fait le test système que vous avez écrit en utilisant Google Chrome en mode avec interface graphique (headful mode). Vous pouvez activer ce mode en passant l’option --headful à la commande discourse_theme rspec.

discourse_theme rspec . --headful

La commande ci-dessus exécutera les tests système en mode avec interface graphique où l’exécution des tests peut être vue visuellement.

Vous pouvez également mettre en pause l’exécution du test dans votre cas de test en utilisant la méthode d’aide pause_test, vous permettant d’inspecter l’état actuel de l’application dans le navigateur.

Exemple :

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

Ce document est contrôlé par version - suggérez des modifications sur github.

18 « J'aime »
6

J’ai remarqué que dans les tests de composants, on utilise généralement let!(:theme) au lieu de let!(:theme_component). Par exemple, dans ce test :

Cependant, le guide suggère d’utiliser let!(:theme_component) pour les composants de thème :

Y a-t-il une raison pour laquelle je devrais utiliser theme_component comme décrit dans ce guide ?

2 « J'aime »