Marketplace Magento 2

Soumission d'un module et stratégie de tests

Introduction

Pour mettre à disposition un module sur la Marketplace Magento 2, il faut se plier à certaines règles dont on pourra trouver tous les détails ici.

En résumé, la validation se fait en deux étapes qu'on peut tout à fait découpler : une revue marketing et une revue technique. Une fois ces deux revues passées avec succès, votre module sera disponible sur la Marketplace à la date que vous aurez indiquée.

De mon point de vue, il y a trois situations qui peuvent vous amener à soumettre un module :

• vous souhaitez mettre à disposition un nouveau module.
• vous avez mis à jour un module et vous souhaitez soumettre une nouvelle version.
• une nouvelle version de Magento 2 a été publiée et vous devez publier une version compatible.

Cet article est un retour d'expérience sur les quelques soumissions de modules Magento 2 que j'ai pu effectuer. Après avoir rapidement repris les différents éléments nécessaires à la validation d'un module, je parlerai de la stratégie de tests que j'ai adoptée. Dans tout ce qui suit, je prendrai pour exemple un module simple appelé CategoryCode dont vous pouvez trouver le code source ici. Ce module en lui-même importe peu ; je l'ai soumis en juillet 2022, mais j'essaie ici de généraliser mon approche concernant la soumission de n'importe quel module.

Vue d'ensemble

Vous pouvez commencer par la revue technique, par la revue marketing ou soumettre les deux en parallèles, selon ce qui vous parait le plus judicieux. À titre personnel, je commence généralement par la revue technique, car c'est elle qui pourrait poser le plus de problèmes.

Ici, je préfère commencer par parler de la revue marketing :

Revue Marketing

Pour une description complète, vous pouvez vous référer à la documentation officielle.

Il s'agit essentiellement de rédiger des contenus (description du module et documents PDF pour les utilisateurs finaux) auquel s'ajoute un travail sur la création d'images.

Pour mettre toutes ces chances de son côté, mieux vaut suivre à la lettre les recommandations. En particulier, vous devez fournir les éléments suivants :

Description longue

La description longue doit respecter un certain formalisme. Elle doit mettre en exergue les fonctionnalités principales du module et donner quelques cas d'usage.

Dans le cas d'un module aussi simple que celui pris en exemple ici, voici un aperçu de ce qui a été accepté :

Logo

En tant que développeur, créer un logo n'est pas une tâche que j'avais l'habitude de faire et mes premières tentatives se sont soldées par des échecs avec pour explication :

it must look professional and be a clear representation of the extension

Le seul conseil que je pourrai donner : dès que votre logo est accepté, sauvegardez son modèle précieusement et vous pourrez le réutiliser en changeant simplement le nom du module concerné.

Le résultat tant attendu :

Documents et ressources

Il est obligatoire de fournir au moins un des trois documents suivants au format PDF :

• Guide de l'utilisateur
• Manuel de référence
• Guide d'installation

Afin d'optimiser le temps de travail sur cette tâche, j'utilise deux fichiers Markdown qui sont déjà présents dans le code source : Installation_Guide.md et User_Guide.md . Pour la soumission marketing, il ne me reste plus qu'à utiliser un outil pour convertir les fichiers Markdown en PDF.

Vous pouvez voir les fichiers PDF du module exemple ici : Installation Guides et User Guides

Voilà pour ce que je peux dire de la revue marketing. Parlons maintenant de la partie technique.

Revue technique

Pour une description complète, vous pouvez vous référer à la documentation officielle.

Les étapes sont les suivantes :

• choix des versions Magento 2 compatibles
• envoi d'un fichier zip contenant le code source de votre module
• série de tests automatisés
• tests manuels.

Compatibilité

Avant de pouvoir soumettre un module, vous devez d'abord déterminer les versions de Magento 2 pour lesquelles vous allez assurer sa compatibilité :

Nous verrons plus tard que ce choix impactera bien sûr les tests à mettre en place pour assurer le bon fonctionnement de votre module sur toutes les plateformes choisies.

Concernant le module exemple, j'ai choisi d'assurer une compatibilité avec Magento Open Source (CE) 2.3 et 2.4.

Zip du code

Vous devez ensuite fournir un fichier zip contenant son code source. Il vous faudra adapter ce type de ligne de commande :

zip -r vendor-name_package-name-1.0.0.zip package-path/ -x 'package-path/.git/*'

Une fois votre fichier zip validé, une série de tests automatisés sera lancée.

Code Sniffer

Il s'agit d'un test statique sur le respect des standards Magento 2 avec l'outil phpcs .

La commande suivante sera exécutée :

phpcs --standard=Magento2 --extensions=php,phtml --error-severity=10 --ignore-annotations --report=json --report-file=report.json <path-to-extension>

Si ce test détecte une anomalie de type Error, alors votre module sera rejeté et vous devrez corriger les erreurs avant de le soumettre à nouveau.

Installation & Varnish Test

Ce test s'effectue en deux parties :

• Installation du module et activation du mode production
  • Ajout de l'extension avec Composer (composer require <extension_package_name>)
  • Test d'activation du module (bin/magento module:enable <extension_name>
  • Test de compilation du code (bin/magento setup:di:compile)
  • Test de déploiement du contenu statique (bin/magento setup:static-content:deploy -f)
  • Activation du mode "production" (bin/magento deploy:mode:set production)
  • Test de réindexation (bin/magento indexer:reindex)
• Vérification du bon fonctionnement du cache Varnish
  • Double accès à certaines pages produit et catégorie : le premier accès doit donner un miss et le deuxième accès un hit.
  • Accès au même page produit suite à l'édition d'un produit : l'accès doit donner un miss.
  • Même vérification après un nettoyage du cache FPC.

Si ce test ne passe pas, votre module sera rejeté et vous devrez corriger les erreurs avant de le soumettre à nouveau.

Autres tests

Il existe d'autres tests que je ne traiterai pas en détail ici :

• Malware scan : pas de virus dans votre fichier zip (validation requise)
• MFTF Commerce-supplied tests : tests fonctionnels (validation non requise à ce jour)
• MFTF Vendor-supplied tests : tests fonctionnels (validation non requise à ce jour)
• Copy paste detector : Vérification que votre code ne contient pas trop de "copié/collé" du code Magento 2 (validation requise)
• Semantic version check : vérification que le numéro de version soumis et les changements de code par rapport à la précédente version sont cohérents (validation requise)

Une fois ces tests automatisés passés, une revue manuelle (Manual QA) sera effectuée.

Revue manuelle

Je ne sais pas exactement comment cette revue manuelle se passe. J'ai déjà eu des retours pertinents (un vrai bug avait été détecté par le testeur) mais, la plupart du temps, je n'ai aucun retour et je me demande parfois ce qui est testé réellement.

Stratégie de tests

Nous venons d'avoir un aperçu des étapes du processus de validation d'un module pour la Marketplace. Concrètement, ce qui suit devrait vous donner une idée de la méthodologie que j'utilise pour tester mes développements en amont de la soumission.

En réalité, vous verrez que je rajoute d'autres tests à ceux imposés par la Marketplace. Mais tout dépend de vos exigences : est ce que vous souhaitez simplement faire en sorte que votre module soit accepté par la Marketplace ou bien souhaitez vous mettre en place d'autres tests, pour diminuer un maximum le nombre de bugs à traiter par la suite.

Autrement dit, il nous faut tout d'abord définir ce qu'il faut tester, selon nos exigences. C'est l'objet de la partie suivante. Ensuite, il faudra se poser la question : comment tester ?

Plans de test

Un plan de test dépend des objectifs que l'on se fixe.

Versions de Magento 2 compatibles

Avant tout, on doit se demander sur quelles versions de Magento 2 on souhaite tester notre module.

Durant le processus de validation de la Marketplace, on nous propose plusieurs versions, mais les tests n'auront lieu que sur la toute dernière publication d'une version. En effet, voici ce qui est mentionné sur la Marketplace :

All tests were conducted on the latest versions of Adobe Commerce that existed for the compatible release lines at the moment of the extension submission. Latest versions of all other software were used, as applicable.

Ainsi, si on choisit 2.4, les tests s'effectueront sur une version 2.4.4 (à ce jour). Personnellement, quand on dit "compatible 2.4", il me semble qu'on sous-entend "compatible 2.4.0, 2.4.1, 2.4.2, 2.4.3 et 2.4.4".

De même pour la compatibilité 2.3 : les tests seront joués sur une version 2.3.7 mais ne devrait-on pas assurer une compatibilité avec toutes les versions allant de 2.3.0 à 2.3.7 ?

Types de test

Une fois les versions de Magento choisies, on peut s'intéresser aux types de test en eux-mêmes.

Tests statiques

Le test Code Sniffer utilisé pour la revue technique est un test statique. Pour passer la validation, il suffit qu'il ne détecte pas d'anomalie de type Error. Pour ma part, j'essaie aussi de faire en sorte qu'il n'y ait aucune anomalie, même de type Warning.

Pour consolider ces tests statiques, j'ajoute une aussi des tests avec les outils phpmd et phpstan .

Tests unitaires et d'intégration

La validation Marketplace ne demande aucun test unitaire ou d'intégration. Si le module en contient, j'ajoute aussi des tests de validation avec PHPUNIT.

Tests fonctionnels

En quelque sorte, le test Installation & Varnsh Test est un test fonctionnel : on s'assure que l'installation du module ne casse pas certains processus importants.

Je n'ai pas mis en place les tests fonctionnels de type MTFT (voir MTFT Magento et MTFT vendor), car ils sont encore en version beta et ne sont pas obligatoires. C'est clairement quelque chose qu'il faudra faire dans le futur..

Cependant, j'ai mis en place des tests fonctionnels avec d'autres outils : jest et playwright . Ces librairies JS me permettent de simuler des interactions avec un navigateur (clics divers, navigation) et de tester les affichages obtenus (présence de certains éléments du DOM, de textes, etc). Pouvant fonctionner en mode headless, ces tests sont parfaitement adaptés aux actions GitHub que l'on verra plus tard. Autre point non négligeable, ils sont facilement adaptables pour des développements hors Magento 2 (WordPress, Laravel ou autres).

Compatibilité avec les dépendances du système

Enfin, on peut se demander quelles seront les versions de chaque élément qui composeront l'environnement Magento 2 de test : la version de PHP, la version de Varnish, la version d'ElasticSearch, etc.

En effet, selon les versions de Magento 2, vous devez en théorie tester votre module avec des versions potentiellement différentes de chaque élément. Par exemple, la documentation fournit ce type de tableau :

Je ne parlerai ici que des versions PHP qu'il faut tester avec votre module, car dans mon cas, il me semble que c'était le seul élément qui pouvait poser problème. Tout dépend des fonctionnalités assurées par votre module : si vous pensez que votre module peut être impacté par des versions différentes d'ElasticSearch, Varnish ou autres, il faudrait faire le même type de travail pour chaque élément.

Minimum requis pour PHP

Comme la validation ne regarde que la version la plus à jour de chaque élément, cela signifie que les vérifications ont eu lieu sur Magento 2.3.7 avec PHP 7.4 et sur Magento 2.4.4 avec PHP 8.1.

Ceci peut être représentée par la liste des combinaisons suivante :

Compatibilité PHP exhaustive

De mon point de vue, cette liste n'est pas tout à fait complète, car elle ne donne que les combinaisons officiellement supportées par Adobe :

Adobe only supports the combination of system requirements described in the following table

En réalité, l'ensemble des combinaisons possibles est bien plus grand. Par exemple, Magento 2.4.4 est officiellement supporté avec PHP 8.1 mais il est en fait tout à fait compatible avec PHP 7.4, comme on peut le voir dans la partie require de son composer.json .

Ainsi, il est tout à fait possible que votre module soit utilisé sur une version de Magento ou de PHP qui n'aura pas été testé par la Marketplace. Et s'il n'a pas été testé, rien ne dit qu'il est fonctionnel. Aussi, pour éviter toute mauvaise surprise, on pourrait se lancer dans des tests plus complets.

La liste exhaustive des combinaisons "version de Magento 2 / version de PHP" est la suivante :

Soit un total de 30 combinaisons.

Plan de test "minimum requis"

Finalement, si on ne cherche qu'à passer la validation, on pourra se contenter du plan de test suivant :

• test statique Code Sniffer sur Magento 2.3.7 avec PHP 7.4 et sur Magento 2.4.4 avec PHP 8.1
• test fonctionnel Installation & Varnish Test avec les mêmes combinaisons.

Plan de test "personnalisé"

Personnellement, je n'ai pas souhaité assurer la compatibilité avec PHP 7.1, et je n'ai pas jugé pertinent de tester toutes les combinaisons possibles.

Finalement, mon plan de test est le suivant :

• tests statiques (Code Sniffer, phpmd et phpstan) : pour Magento 2.3.0, 2.3.7, 2.4.0 et 2.4.4 avec PHP 7.2, 7.3, 7.4 et 8.1 (7 combinaisons au total)
• tests unitaires pour les mêmes combinaisons que le plan de test "Minimum requis".
• tests Installation & Varnish Test pour les mêmes combinaisons que le plan de test "Minimum requis".
• tests fonctionnels End-to-end pour toutes les versions de Magento 2.3.7 à 2.4.4 et PHP 7.3 , 7.4 et 8.1 (12 combinaisons possibles)

Méthodologie

Se pose alors la question : comment tester ?

Quand on voit la liste des tests du plan de test "personnalisé", on comprend qu'il n'est pas envisageable de les faire manuellement, à chaque nouvelle validation. En réalité, même dans le cas du plan de test "minimum requis", l'automatisation me semblerait un bon choix.

Concrètement, pour pouvoir tester un module Magento 2 de manière automatisé, on peut se baser sur des outils de type Docker afin de simuler un environnement Magento 2 et on aura essentiellement besoin des services suivants :

• un service web avec nginx ou apache et une certaine version de PHP
• un service db avec MariaDB par exemple
• un service elasticsearch car il est obligatoire depuis quelque temps
• un service varnish si on doit tester la compatibilité Varnish.

Une fois cet environnement monté, il faut pouvoir :

• créer un projet Magento 2 avec composer.
• lancer l'installation de Magento 2 avec son outil CLI bin/magento.
• ajouter son module en tant que dépendance composer.
• lancer les commandes pour activer le module.
• lancer diverses commandes pour exécuter d'autres scripts (composer, phpcs, scripts personnalisés, etc.).

Toutes ces actions peuvent se résumer à un enchainement de lignes de commande et sont donc tout à fait automatisables.

De mon point de vue, on a besoin deux types d'outils :

• un outil pour créer et manipuler des environnements de test.
• un outil pour gérer de l'automatisation.

Personnellement, j'ai choisi DDEV pour la gestion des environnements et les actions GitHub pour la partie automatisation.

Gestion des environnements : DDEV

Dans un de mes précédents articles, j'expliquais pourquoi et comment j'utilise DDEV.

En résumé, DDEV permet de se baser sur quelques fichiers de configurations pour monter des environnements de travail basé sur des conteneurs Docker. Il suffira donc de modifier un simple fichier pour pouvoir lancer des environnements web avec des versions de PHP différentes. On pourra aussi créer des containers dédiés à d'autres services avec des versions spécifiques de ces derniers : ElasticSearch, Varnish, etc.

Avant tout, un des intérêts de DDEV est qu'on peut s'en servir sur sa propre machine : je peux donc tout à fait lancer les environnements localement, tester le module localement, et me servir des mêmes lignes de commandes pour implémenter des actions GitHub.

Automatisation: Actions GitHub

Difficile de décrire toute la force des actions GitHub. Dans le cas particulier qui m'intéresse ici, je voudrais simplement parler de la possibilité de lancer plusieurs tests en parallèles grâce à une directive appelée matrix. Par exemple, lorsque je souhaite lancer les tests fonctionnels End-to-end du module exemple, j'utilise ce type d'instructions :

matrix:
    m2-version: [ "2.3.7", "2.4.0", "2.4.1", "2.4.2", "2.4.3", "2.4.4" ]
    php-version: [ "7.2", "7.3", "7.4", "8.1" ]
    exclude:
        - { php-version: "7.2", m2-version: "2.3.7" }
        - { php-version: "8.1", m2-version: "2.3.7" }
        - { php-version: "7.2", m2-version: "2.4.0" }
        - { php-version: "8.1", m2-version: "2.4.0" }
        - { php-version: "7.2", m2-version: "2.4.1" }
        - { php-version: "8.1", m2-version: "2.4.1" }
        - { php-version: "7.2", m2-version: "2.4.2" }
        - { php-version: "8.1", m2-version: "2.4.2" }
        - { php-version: "7.2", m2-version: "2.4.3" }
        - { php-version: "8.1", m2-version: "2.4.3" }
        - { php-version: "7.2", m2-version: "2.4.4" }
        - { php-version: "7.3", m2-version: "2.4.4" }

Ceci me permet de tester, en parallèle, la compatibilité du module pour les versions de Magento allant de 2.3.7 à 2.4.4 avec les versions de PHP allant de 7.2 à 8.1 :

Actions GitHub

Pour terminer, je souhaite ici partager les actions GitHub finalisées, qui permettent de répondre aux critères de mon plan de test.

Code Sniffer et autres tests statiques

Vous pouvez voir le détail de l'action GitHub ici : Tests statiques

Finalement, la ligne qui nous intéresse le plus et qui simule le test Code Sniffer est celle-ci :

ddev phpcs vendor/${ { env.EXTENSION_PACKAGE_NAME } }

Installation & Varnish Test

La préparation nécessaire à ce test, ainsi que les tests effectivement lancés, est décrite ici.

On note qu'il faudra :

• modifier l'acl Varnish afin de rajouter un header X-EQP-CACHE.
• installer des produits et catégories de tests avec la commande setup:performance:generate-fixtures.
• appeler différentes urls plusieurs fois afin de vérifier que le header X-EQP-CACHE vaut bien HIT ou MISS selon les cas.

Afin d'appeler les différentes urls et de vérifier la conformité des retours, j'ai créé un script sh qui fait des appels curl.

Vous pouvez voir le détail de l'action GitHub ici : Tests Installation & Varnish

Les tests Varnish sont réalisés dans les étapes Varnish MISS and HIT test, Varnish product update test et Varnish FPC clean test. Le test d'installation est fait à l'étape Installation tests.

Tests fonctionnels

Vous pouvez voir le détail de l'action GitHub ici : Tests End-to-end (voir les étapes Config test et Update layout handle test).

Encore une fois, ce module n'est donné qu'à titre d'exemple. L'idée est de tester un maximum de fonctionnalité de bout en bout : configuration du module et vérification de la conformité des résultats réels avec ceux attendus.

Tests unitaires et d'intégration

Les tests associés au module exemple sont quasi inexistants, mais la structure de base est là.

Vous pouvez voir le détail de l'action GitHub ici : Tests Unitaires

Zip du code

Enfin, pour m'assurer de la validité du zip fourni, j'ai mis en place une action GitHub me permettant de créer une release et d'obtenir le zip conforme associé. J'utilise une copie d'un projet GitHub qui, pour une raison inconnue, n'existe plus : voir ici. Jusqu'à présent, les fichiers validés par cet outil ont été validés par la Marketplace.

Vous pouvez voir le détail de l'action GitHub ici : Release et zip

Une fois ma release publiée sur GitHub, je peux récupérer le zip et le soumettre directement.

Conclusion

J'espère que cette présentation vous en aura appris un peu plus sur la mise à disposition d'un module sur la Marketplace et que vous pourrez piocher quelques idées pour mettre en place votre propre méthodologie de test.

De mon côté, j'ai en tête beaucoup d'axes d'amélioration et continue à rester curieux de ce qui se fait ailleurs. J'imagine par exemple qu'une action Github utilisant l'API Marketplace EQP ou que des approches comme celle-ci sont à étudier plus en détail.