Test dell’interfaccia utente

I test dell’interfaccia utente personalizzati sono una funzione facoltativa che consente di creare ed eseguire automaticamente i test dell’interfaccia utente per le applicazioni.

Panoramica

AEM fornisce una suite integrata di gate di qualità di Cloud Manager per garantire una fluida esperienza di aggiornamento delle applicazioni personalizzate. In particolare, i gate di test IT supportano già la creazione e automazione dei test personalizzati utilizzando le API di AEM.

I test dell’interfaccia utente sono inclusi in un’immagine Docker per consentire un’ampia scelta in termini di linguaggio e framework (come Cypress, Selenium, Java e Maven e JavaScript). Inoltre, un progetto di test dell’interfaccia utente può essere facilmente generato utilizzando l’archetipo del progetto AEM.

Adobe incoraggia l’utilizzo di Cypress, in quanto offre il ricaricamento in tempo reale e l’attesa automatica, che consente di risparmiare tempo e migliora la produttività durante il test. Cypress fornisce anche una sintassi semplice e intuitiva, che lo rende facile da apprendere e utilizzare, anche per coloro che eseguono i test per la prima volta.

I test dell’interfaccia utente vengono eseguiti come parte di un gate di qualità specifico per ogni pipeline di Cloud Manager tramite test personalizzati dell’interfaccia utente nella pipeline di produzione o facoltativamente, nella pipeline non di produzione. Tutti i test dell’interfaccia utente, compresi la regressione e le nuove funzionalità, consentono di rilevare e segnalare gli errori.

A differenza dei test funzionali personalizzati, che rappresentano test HTTP scritti in Java, i test dell’interfaccia utente possono essere un’immagine Docker con test scritti in qualsiasi linguaggio, purché rispettino le convenzioni definite nella sezione Generazione dei test dell’interfaccia utente.

Introduzione ai test dell’interfaccia utente

In questa sezione vengono descritti i passaggi necessari per configurare i test dell’interfaccia utente per l’esecuzione in Cloud Manager.

1. Scegli il linguaggio di programmazione che desideri utilizzare.

   • Per Cypress, utilizza il codice di esempio dell’Archivio degli esempi di test di AEM.

   • Per JavaScript e WDIO, utilizza il codice di esempio generato automaticamente nella cartella ui.tests dell’archivio di Cloud Manager.

     NOTA

     Se l’archivio è stato creato prima della creazione automatica delle cartelle ui.tests di Cloud Manager, puoi anche generare la versione più recente utilizzando l’archetipo di progetto AEM.

   • Per Java e WebDriver, utilizza il codice di esempio dell’Archivio dei test di prova di AEM.

   • Per altri linguaggi di programmazione, consulta la sezione Creazione dei test dell’interfaccia utente di questo documento per configurare il progetto di test.

2. Assicurati che i test dell’interfaccia utente siano attivati come secondo la sezione Consenso del cliente di questo documento.

3. Sviluppa gli esempi di test e eseguili in locale.

4. Salvare il codice nell’archivio di Cloud Manager ed eseguire una pipeline di Cloud Manager.

Creazione dei test dell’interfaccia utente

Un progetto Maven genera un contesto di build Docker. Questo contesto build di Docker descrive come creare un’immagine Docker contenente i test dell’interfaccia utente che Cloud Manager utilizza per generare un’immagine Docker contenente i test effettivi dell’interfaccia utente.

In questa sezione vengono descritti i passaggi necessari per aggiungere un progetto di test dell’interfaccia utente all’archivio.

Generare un contesto build di Docker

Per generare un contesto build Docker è necessario un modulo Maven che:

• Produca un archivio contenente un Dockerfile e tutti gli altri file necessari per generare un’immagine Docker con i testi.
• Aggiunga all’archivio il tag con il classificatore ui-test-docker-context.

Il modo più semplice per eseguire l’operazione è configurare il plug-in Maven Assembly per creare l’archivio di contesto di build Docker e assegnare a questo il classificatore corretto.

Puoi creare i test dell’interfaccia utente con diverse tecnologie e framework, ma questa sezione presuppone che il progetto sia simile al seguente.

├── Dockerfile
├── assembly-ui-test-docker-context.xml
├── pom.xml
├── test-module
│   ├── package.json
│   ├── index.js
│   └── wdio.conf.js
└── wait-for-grid.sh

Il file pom.xml si occupa della build Maven. Aggiungi un’esecuzione simile alla seguente al plug-in Maven Assembly.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-assembly-plugin</artifactId>
    <configuration>
        <descriptors>
            <descriptor>${project.basedir}/assembly-ui-test-docker-context.xml</descriptor>
        </descriptors>
        <tarLongFileMode>gnu</tarLongFileMode>
    </configuration>
    <executions>
        <execution>
            <id>make-assembly</id>
            <phase>package</phase>
            <goals>
                <goal>single</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Questa esecuzione indica al plug-in Maven Assembly di creare un archivio in base alle istruzioni contenute in assembly-ui-test-docker-context.xml, che prende il nome di descrittore assembly nel gergo del plug-in. Il descrittore assembly elenca tutti i file che devono far parte dell’archivio.

<assembly>
    <id>ui-test-docker-context</id>
    <includeBaseDirectory>false</includeBaseDirectory>
    <formats>
        <format>tar.gz</format>
    </formats>
    <fileSets>
        <fileSet>
            <directory>${basedir}</directory>
            <includes>
                <include>Dockerfile</include>
                <include>wait-for-grid.sh</include>
            </includes>
        </fileSet>
        <fileSet>
            <directory>${basedir}/test-module</directory>
            <excludes>
                <exclude>node/**</exclude>
                <exclude>node_modules/**</exclude>
                <exclude>reports/**</exclude>
            </excludes>
        </fileSet>
    </fileSets>
</assembly>

Il descrittore assembly fornisce al plug-in istruzioni per creare un archivio di tipo .tar.gz e assegna a questo il classificatore ui-test-docker-context. Inoltre, elenca i file che devono essere inclusi nell’archivio, compresi quelli riportati di seguito.

• Un Dockerfile, obbligatorio per la generazione dell’immagine Docker
• Lo script wait-for-grid.sh, le cui finalità sono descritte di seguito
• I test effettivi dell’interfaccia utente, implementati da un progetto Node.js nella cartella test-module

Il descrittore assembly esclude inoltre alcuni file che potrebbero essere generati durante l’esecuzione locale dei test dell’interfaccia utente. Questo garantisce un archivio di dimensioni minori e generazioni più veloci.

L’archivio contenente il contesto di build Docker viene automaticamente selezionato da Cloud Manager, che crea l’immagine Docker contenente i test durante le pipeline di distribuzione. Infine, Cloud Manager esegue l’immagine Docker per eseguire i test dell’interfaccia utente per l’applicazione.

La generazione deve produrre zero archivi o un unico archivio. Se non produce archivi, il passaggio di test viene superato per impostazione predefinita. Se la generazione produce più di un archivio, l’archivio selezionato non è deterministico.

Consenso del cliente

Affinché a Cloud Manager possa generare ed eseguire i test dell’interfaccia utente, devi fornire il consenso esplicito alla funzione aggiungendo un file all’archivio.

• Il nome file deve essere testing.properties.
• Il contenuto del file deve essere ui-tests.version=1.
• Il file deve trovarsi nel modulo secondario Maven per i test dell’interfaccia utente accanto al file pom.xml del modulo secondario dei test dell’interfaccia utente.
• Il file deve trovarsi nella radice del file tar.gz integrato.

Se il file non è presente, la build e le esecuzioni dei test dell’interfaccia utente vengono ignorate.

Per includere un file testing.properties nell’artefatto della build, aggiungi un’istruzione include nel file assembly-ui-test-docker-context.xml.

[...]
<includes>
    <include>Dockerfile</include>
    <include>wait-for-grid.sh</include>
    <include>testing.properties</include> <!-- opt-in test module in Cloud Manager -->
</includes>
[...]

Se utilizzi gli esempi forniti da Adobe:

• Per la cartella ui.tests basata su JavaScript generata in base all’archetipo progetto AEM, puoi eseguire il comando seguente per aggiungere la configurazione richiesta.

  echo "ui-tests.version=1" > testing.properties
  
  if ! grep -q "testing.properties" "assembly-ui-test-docker-context.xml"; then
    awk -v line='                <include>testing.properties</include>' '/<include>wait-for-grid.sh<\/include>/ { printf "%s\n%s\n", $0, line; next }; 1' assembly-ui-test-docker-context.xml > assembly-ui-test-docker-context.xml.new && mv assembly-ui-test-docker-context.xml.new assembly-ui-test-docker-context.xml
  fi
  

• Per gli esempi di test Cypress e Java Selenium forniti da Adobe è già impostato il flag di consenso.

Scrittura dei test dell’interfaccia utente

Questa sezione descrive le convenzioni da seguire per l’immagine Docker contenente i test dell’interfaccia utente. L’immagine Docker viene generata in base al contesto di build Docker descritto nella sezione precedente.

Variabili di ambiente

In fase di esecuzione, all’immagine Docker vengono passate le seguenti variabili di ambiente a seconda del framework.

Gli esempi di test di Adobe forniscono funzioni di supporto per accedere ai parametri di configurazione:

• Cypress: utilizza la funzione standard Cypress.env('VARIABLE_NAME')
• JavaScript: vedi il modulo lib/config.js
• Java: vedi la classe Config

Generazione dei rapporti sui test

L’immagine Docker deve generare rapporti sui test in formato JUnit XML e salvarli nel percorso specificato dalla variabile di ambiente REPORTS_PATH. Il formato JUnit XML è ampiamente utilizzato per la generazione di rapporti sui risultati dei test. Se l’immagine Docker utilizza Java e Maven, i moduli di test standard come Maven Surefire Plug-in e Maven Failsafe Plug-in possono generare tali rapporti in modo preconfigurato.

Se implementi l’immagine Docker con altri linguaggi di programmazione o esecuzione di test, consulta la documentazione relativa agli strumenti scelti per sapere come generare rapporti JUnit XML.

Prerequisiti

• I test in Cloud Manager sono eseguiti utilizzando un utente amministratore tecnico.

• L'infrastruttura a contenitori per il test funzionale è limitata dai seguenti vincoli:

Dettagli specifici per Selenium

Attesa del servizio Selenium

Prima dell’avvio dei test, l’immagine Docker verifica che il server Selenium sia in esecuzione. L’attesa del servizio Selenium è un processo a due fasi.

1. È possibile leggere l’URL del servizio Selenium dalla variabile di ambiente SELENIUM_BASE_URL.
2. Utilizza il polling a intervalli regolari dell’endpoint di stato esposto dall’API Selenium.

Dopo aver ricevuto una risposta positiva dall’endpoint di stato di Selenium è possibile avviare i test.

Gli esempi di test dell’interfaccia utente di Adobe eseguono questa funzione con lo script wait-for-grid.sh, che viene eseguito all’avvio di Docker e lancia l’esecuzione effettiva del test solo quando la griglia è pronta.

Acquisire schermate e video

L’immagine Docker può generare un output di test aggiuntivo (ad esempio schermate o video) e salvarlo nel percorso specificato dalla variabile di ambiente REPORTS_PATH. Qualsiasi file trovato sotto REPORTS_PATH è incluso nell’archivio dei risultati del test.

Gli esempi di test forniti da Adobe per impostazione predefinita creano screenshot per tutti i test non riusciti.

Puoi utilizzare le funzioni di assistenza per creare screenshot tramite i test.

• JavaScript: comando takeScreenshot
• Java: Comandi

Se durante l’esecuzione di un test dell’interfaccia utente viene creato un archivio dei risultati del test, puoi scaricarlo da Cloud Manager utilizzando il pulsante Download Details sotto il passaggio Test interfaccia utente personalizzato .

Caricamento dei file

I test a volte richiedono il caricamento di file nell’applicazione sottoposta a test. Al fine di mantenere la distribuzione di Selenium flessibile rispetto ai test, non è possibile caricare direttamente una risorsa in Selenium. Per caricare un file è necessario seguire la procedura riportata di seguito.

1. Carica il file nell’URL specificato dalla variabile di ambiente UPLOAD_URL.
   • Il caricamento deve essere eseguito in un’unica richiesta POST con modulo multipart.
   • Il modulo multipart deve presentare un singolo campo di file.
   • Questo equivale a curl -X POST ${UPLOAD_URL} -F "data=@file.txt".
   • Per informazioni su come eseguire una tale richiesta HTTP, consulta la documentazione e le librerie del linguaggio di programmazione utilizzato nell’immagine Docker.
   • Gli esempi di test di Adobe forniscono funzioni di supporto per il caricamento dei file:
     • JavaScript: vedi il comando getFileHandleForUpload.
     • Java: vedi la classe FileHandler.
2. Se il caricamento ha esito positivo, la richiesta restituisce una risposta 200 OK di tipo text/plain.
   • Il contenuto della risposta è un handle di file opaco.
   • È possibile utilizzare questo handle al posto del percorso file in un elemento <input> per i test del caricamento dei file nell’applicazione.

Esecuzione locale dei test dell’interfaccia utente

Prima di attivare i test dell’interfaccia utente in una pipeline di Cloud Manager, si consiglia di eseguire i test dell’interfaccia utente localmente per l’SDK di AEM as a Cloud Service o per un’istanza reale di AEM as a Cloud Service.

Esempio di prova Cypress

1. Apri una shell e passa alla cartella ui.tests/test-module nell’archivio

2. Installa Cypress e altri prerequisiti

   npm install
   

3. Imposta le variabili di ambiente necessarie per l’esecuzione dei test

   export AEM_AUTHOR_URL=https://author-<program-id>-<environment-id>.adobeaemcloud.com
   export AEM_AUTHOR_USERNAME=<user>
   export AEM_AUTHOR_PASSWORD=<password>
   export AEM_PUBLISH_URL=https://publish-<program-id>-<environment-id>.adobeaemcloud.com
   export AEM_PUBLISH_USERNAME=<user>
   export AEM_PUBLISH_PASSWORD=<password>
   export REPORTS_PATH=target/
   

4. Esegui i test con uno dei seguenti comandi

   npm test              # Using default Cypress browser
   npm run test-chrome   # Using Google Chrome browser
   npm run test-firefox  # Using Firefox browser
   

Esempio di test WebdriverIO JavaScript

1. Apri una shell e passa alla cartella ui.tests nell’archivio

2. Esegui il comando seguente per avviare i test utilizzando Maven

   mvn verify -Pui-tests-local-execution \
    -DAEM_AUTHOR_URL=https://author-<program-id>-<environment-id>.adobeaemcloud.com \
    -DAEM_AUTHOR_USERNAME=<user> \
    -DAEM_AUTHOR_PASSWORD=<password> \
    -DAEM_PUBLISH_URL=https://publish-<program-id>-<environment-id>.adobeaemcloud.com \
    -DAEM_PUBLISH_USERNAME=<user> \
    -DAEM_PUBLISH_PASSWORD=<password>
   

Esempio di test Java Selenium WebDriver

1. Apri una shell e passa alla cartella ui.tests/test-module nell’archivio

2. Esegui i comandi seguenti per avviare i test utilizzando Maven

   # Start selenium docker image (for x64 CPUs)
   docker run --platform linux/amd64 -d -p 4444:4444 selenium/standalone-chrome-debug:latest
   
   # Start selenium docker image (for ARM CPUs)
   docker run -d -p 4444:4444 seleniarm/standalone-chromium
   
   # Run the tests using the previously started Selenium instance
   mvn verify -Pui-tests-local-execution -DSELENIUM_BASE_URL=http://<server>:4444