Test de système de bout en bout pour thèmes et composants de thèmes

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 méthodes d’écriture de tests de régression pour les thèmes. La première suit principalement la méthode d’EmberJS et implique uniquement le test du code côté client. La seconde méthode consiste à écrire des tests système Rails qui vous permettent de tester simultanément le code côté serveur et le code côté client. Ce document se concentrera sur l’écriture de tests système Rails pour les thèmes et c’est 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. Des connaissances de base sur RSpec et Capybara sont nécessaires pour commencer et nous vous recommandons de lire les liens suivants avant de commencer :

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

Voici quelques lignes directrices à 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 <description_du_test_système>_spec.rb.

  • Le bloc RSpec describe de niveau supérieur doit contenir les métadonnées 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’assistance 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 réglage 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 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

  • 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 les tests 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’assistance sign_in pour tester différents profils d’utilisateurs.

    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 rendre la requête et l’inspection de parties de la page plus faciles et plus réutilisables pour vos tests système. Pour ce faire, vous pouvez utiliser le concept de PageObjects, que vous verrez souvent dans le noyau.

    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é de 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 CLI discourse_theme 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. Sauf si vous êtes un développeur expérimenté de plugins ou de thèmes Discourse, 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écifications, d’un fichier et d’un fichier avec des 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 headful

Par défaut, les tests système de thèmes sont exécutés à l’aide de Google Chrome en mode sans tête. C’est un mode où le navigateur ne rend rien à l’écran, ce qui permet 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 headful. 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 headful où l’exécution des tests peut être vue visuellement.

Vous pouvez également interrompre l’exécution du test dans votre cas de test en utilisant la méthode d’assistance 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 »