Mit der Execution API integrieren

Die Tosca CI/CD-Integration ermöglicht die Integration von Tricentis Tosca in Ihre eigene CI/CD-Pipeline. Sie können sie auch mit anderen Umgebungen kombinieren, z. B. mit Umgebungen, in denen Sie Tosca nicht installiert haben.

Tricentis Tosca bietet verschiedene Möglichkeiten, Tosca CI/CD zu integrieren. Dieses Kapitel erläutert, wie Sie direkt mit der Execution API von Tosca Server integrieren, was Ihnen maximale Flexibilität in Ihrer CI/CD-Pipeline bietet.

Architektur der Execution API

Voraussetzungen

Zur Integration mit der Tosca Server Execution API können Sie entweder die Tosca Distributed Execution with AOS oder die Tosca Cloud-Integration verwenden.
Wenn Sie den Tosca Server mit einer HTTPS-Bindung verwenden, müssen Sie über ein persönliches API-Zugriffstoken von der Tricentis User Administration verfügen. Sie benötigen die Client ID und den geheimen Clientschlüssel des Tokens, um das Execution API-Zugriffstoken abzurufen.

Ereignisse verstehen

Die Integration mit der Tosca Server Execution API funktioniert mit Ereignissen. Ein Ereignis ist eine Sammlung von Testereignissen oder ElasticExecutionGridEvents, die Sie ausführen möchten. Sie können auch Ereignisse mit nur einem Testereignis oder ElasticExecutionGridEvent haben.

Um zu definieren, wie Tosca die Ausführung handhabt, können Sie Ihrem Ereignis Testkonfigurationsparameter und Merkmale hinzufügen.

Testkonfigurationsparameter verwenden

Testkonfigurationsparameter definieren in der Regel Umgebungsinformationen, z. B. welchen Browser Sie für Ihre UI-Tests verwenden möchten. Die Parameter, die Sie in Ihrem Ereignis definieren, überschreiben die Parameter, die Sie für einzelne Tests festgelegt haben. Auf diese Weise können Sie Ihren Testdurchlauf verfeinern, ohne mehrere Tests neu konfigurieren zu müssen.

Nehmen wir an, Ihr Ereignis hat ein Testereignis, das aus zwei Ausführungslisten besteht. Sie haben Testkonfigurationsparameter für beide Ausführungslisten festgelegt: eine sollte in Chrome und die andere in Firefox ausgeführt werden. In diesem speziellen Testdurchlauf möchten Sie jedoch beide Ausführungslisten in Safari ausführen. Anstatt Ihre Ausführungslisten neu zu konfigurieren, können Sie den Browserparameter in Ihrem Ereignis einstellen. Bei der Ausführung wendet Tosca diesen Parameter anstelle der Parameter auf den Ausführungslisten an.

Merkmale verwenden

Merkmale definieren, welche Agents Ihre Tests ausführen.

In einer Tosca Distributed Execution-Umgebung entsprechen diese Merkmale den Parametern, die Sie auf dem Server festgelegt haben, und gelten für die Agents.
In einer Tosca Cloud-Umgebung entsprechen diese Merkmale den Tosca Cloud Agent Characteristics, die Sie in Ihrem ElasticExecutionGridEvent angeben.

Die Merkmale, die Sie in Ihrem Ereignis definieren, überschreiben das, was Sie in Ihren Testereignissen oder ElasticExecutionGridEvents definiert haben. Auf diese Weise können Sie Ihren Testdurchlauf verfeinern, ohne mehrere Tests neu konfigurieren zu müssen.

Nehmen wir an, Ihr Ereignis hat zwei Testereignisse. Eines gibt an, dass jeder ausführende Agent 2 GB Arbeitsspeicher benötigt, der andere gibt an, dass jeder ausführende Agent 4 GB benötigt. Diese Ausführung sollte jedoch nur auf Agents mit 8 GB Arbeitsspeicher ausgeführt werden. Anstatt Ihre Testereignisse neu zu konfigurieren, können Sie das notwendige Merkmal in Ihrem Ereignis einstellen. Bei der Ausführung wendet Tosca dieses Merkmal anstelle derjenigen auf den Testereignissen an.

Request-Übersicht

Sie können die folgenden Requests an die Execution API senden:

Fragen Sie das Execution API-Zugriffstoken an. Wenn Sie den Tosca Server mit einer HTTPS-Bindung verwenden, erlaubt der Server nur authentifizierte Requests. Jeder Request muss das Zugriffstoken im Header haben.
Lösen Sie die Ausführung eines Ereignisses aus. Die Response auf diesen Request gibt Ihnen eine Ausführungs-ID, die Sie für alle weiteren Requests benötigen.
Überprüfen Sie den Status eines Ereignisses, z. B. ob es noch in Bearbeitung oder bereits abgeschlossen ist.
Rufen Sie Ihre Ergebnisse ab. Die Execution API gibt Ergebnisse im JUnit-Format zurück.
Rufen Sie allgemeine Informationen zu den Tests in Ihrem Ereignis ab: wie viele in Bearbeitung, erfolgreich oder fehlgeschlagen sind oder übersprungen wurden, weil Tosca sie nicht verarbeiten konnte.

In Swagger erkunden

Wenn Sie ein wenig experimentieren möchten, bevor Sie sich hineinstürzen, ist das kein Problem. Greifen Sie auf Swagger zu und legen Sie los:

http://<IP-Adresse oder Hostname des Tosca Server-Gateway>:<Gateway-Port>/automationobjectservice/swagger/index.html

Hinweis: Sie können nur über HTTP auf Swagger zugreifen.

Ein Execution API-Zugriffstoken anfragen

Wenn Sie den Tosca Server mit einer HTTPS-Bindung verwenden, müssen Sie Ihre Requests authentifizieren. Jeder Request muss ein Execution API-Zugriffstoken enthalten.

Um das Execution API-Zugriffstoken abzurufen, senden Sie einen Request an http(s)://<IP-Adresse oder Hostname des Tosca Server Gateway>:<Port>/tua/connect/token. Fügen Sie die Client ID und den geheimen Clientschlüssel Ihres persönlichen API-Zugriffstokens von der Tricentis User Administration bei.

Beispiel-Request mit cURL:

Kopieren

curl --location --request POST 'https://111.111.111:443/tua/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<clientId of your TUA personal access token>' \
--data-urlencode 'client_secret=<clientSecret of your TUA personal access token>'

Ausführung auslösen

Senden Sie den folgenden Request, um die Ausführung eines Ereignisses auszulösen:

POST /api/Execution/Enqueue

Stellen Sie sicher, dass Sie Ihrem Request den CSRF-Header X-Tricentis hinzufügen.

Request-Textkörper

Fügen Sie den folgenden Request-Textkörper (Body) hinzu:

Kopieren

{
  "projectName": "string",
  "executionEnvironment": "string",
  "events": [
    {
      "eventId": "string",
      "parameters": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "characteristics": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      }
    }
  ],
  "importResult": true,
  "creator": "string"
}

Fügen Sie die folgenden Werte hinzu:

Parameter	Beschreibung
projectName	Projektwurzelname des Tosca-Projekts, in dem sich das Ereignis befindet.
executionEnvironment	Umgebung, in der Sie Ihr Ereignis ausführen möchten. Sie können Dex oder ElasticExecutionGrid eingeben.
eventId	Name des Testereignisses bzw. des ElasticExecutionGridEvent oder der Wert der Eigenschaft UniqueId. Sie können mehrere Testereignisse/ElasticExecutionGridEvents angeben, die durch Komma getrennt sind.
parameters	Definieren Sie Testkonfigurationsparameter. Beispiel: `"parameters": { "Browser": "Firefox", "SynchronizationTimeout": "1700", "SelfHealing": "Combination" }`
characteristics	Definieren Sie, welche Agents Ihre Tests ausführen sollen. Beispiel: `"characteristics": { "Memory": "2GB", "FirefoxInstalled": "yes", "UseRDP": "True" }`
importResult	Geben Sie an, ob die Ergebnisse zurück in Tosca importiert werden sollen: Geben Sie true ein, um die Ergebnisse in Ihren Ausführungslisten in Tosca anzuzeigen. Geben Sie false ein, um nur JUnit-Ergebnisse zu erhalten.
creator	Name der Person, die die Ausführung ausgelöst hat. Der DEX Monitor zeigt diesen Namen an; die Voreinstellung ist ToscaExecutionClient.

Beispiel-Request mit cURL:

curl --location --request POST 'https://111.111.111:443/automationobjectservice/api/Execution/enqueue' \
--header 'Content-Type: application/json' \
--header 'X-Tricentis: OK' \
--header 'Authorization: Bearer <your Execution API access token>' \
--data-raw '{
    "ExecutionEnvironment": "Dex",
    "ProjectName": "MyProjectRootName",
    "Events": ["TestEvent 1", "TestEvent 2"],
    "ImportResult": true,
    "Creator": "MyClientX"    
}'
                                                    

Erfolgreiche Response

Wenn der Request erfolgreich ist, gibt die Response die Ausführungs-ID zurück. Sie benötigen diese ID für alle weiteren Requests.

Weitere Informationen zu Responses finden Sie in der Swagger-Dokumentation:

http://<IP-Adresse oder Hostname des Tosca Server-Gateway>:<Gateway-Port>/automationobjectservice/swagger/index.html

Aktuellen Status eines Ereignisses überprüfen

Senden Sie den folgenden Request, um den aktuellen Status eines Ereignisses zu überprüfen:

GET /api/Execution/{Ausführungs-ID}/Status

Ersetzen Sie {Execution ID} durch die Ausführungs-ID, die Sie in der Response zu der „Ausführung starten“-Request erhalten haben.

Stellen Sie sicher, dass Sie Ihrem Request den CSRF-Header X-Tricentis hinzufügen.

Beispiel-Request mit cURL:

curl --location --request GET 'https://111.111.111:443/automationobjectservice/api/Execution/1a2b3c/status' \
--header 'X-Tricentis: OK' \
--header 'Authorization: Bearer <your Execution API access token>' \
                                                    

Erfolgreiche Response

Wenn der Request erfolgreich ist, gibt die Response den Status des Ereignisses zurück. Wenn Sie das Testereignis in einer Tosca Cloud-Umgebung ausführen, erhalten Sie auch Unterstatus.

Weitere Informationen zu Responses finden Sie in der Swagger-Dokumentation:

http://<IP-Adresse oder Hostname des Tosca Server-Gateway>:<Gateway-Port>/automationobjectservice/swagger/index.html

Ergebnisse eines Ereignisses abrufen

Senden Sie den folgenden Request, um herauszufinden, ob sich die zu testende Applikation wie erwartet verhalten hat:

GET /api/Execution/{Ausführungs-ID}/Results

Ersetzen Sie {Execution ID} durch die Ausführungs-ID, die Sie in der Response zu der „Ausführung starten“-Request erhalten haben.

Stellen Sie sicher, dass Sie Ihrem Request den CSRF-Header X-Tricentis hinzufügen.

Beispiel-Request mit cURL, um vollständige Ergebnisse zu erhalten:

curl --location --request GET 'https://111.111.111:443/automationobjectservice/api/Execution/1a2b3c/results' \
--header 'X-Tricentis: OK' \
--header 'Authorization: Bearer <your Execution API access token>' \
                                                    

Beispiel-Request mit cURL, um Teilergebnisse zu erhalten, bevor die Ausführung abgeschlossen ist:

curl --location --request GET 'https://111.111.111:443/automationobjectservice/api/Execution/1a2b3c/results?partial=true' \
--header 'X-Tricentis: OK' \
--header 'Authorization: Bearer <your Execution API access token>' \
                                                    

Erfolgreiche Response

Wenn der Request erfolgreich ist, gibt die Response die Ergebnisse im JUnit-Format zurück.

Weitere Informationen zu Responses finden Sie in der Swagger-Dokumentation:

http://<IP-Adresse oder Hostname des Tosca Server-Gateway>:<Gateway-Port>/automationobjectservice/swagger/index.html

Ergebniszusammenfassung für ein Ereignis abrufen

Ein Ereignis kann mehrere Testereignisse/ElasticExecutionGridEvents enthalten. Sie können eine allgemeine Übersicht anfordern: wie viele in Bearbeitung, erfolgreich oder fehlgeschlagen sind oder übersprungen wurden, weil Tosca sie nicht verarbeiten konnte. Senden Sie dazu den folgenden Request:

GET /api/Execution/{Ausführungs-ID}/Results/Summary

Ersetzen Sie {Execution ID} durch die Ausführungs-ID, die Sie in der Response zu der „Ausführung starten“-Request erhalten haben.

Stellen Sie sicher, dass Sie Ihrem Request den CSRF-Header X-Tricentis hinzufügen.

Beispiel-Request mit cURL:

curl --location --request GET 'https://111.111.111:443/automationobjectservice/api/Execution/1a2b3c/results/summary' \
--header 'X-Tricentis: OK' \
--header 'Authorization: Bearer <your Execution API access token>' \
                                                    

Erfolgreiche Response

Wenn der Request erfolgreich ist, gibt die Response die Übersicht zurück.

Weitere Informationen zu Responses finden Sie in der Swagger-Dokumentation:

http://<IP-Adresse oder Hostname des Tosca Server-Gateway>:<Gateway-Port>/automationobjectservice/swagger/index.html