Snippets

Was Snippets sind

Snippets sind wiederverwendbare JavaScript-Bausteine, die Sie einmal definieren und mit require() in Ihre Check-Skripte einbinden. Statt dieselbe Hilfsfunktion, Token-Signierung oder Setup-Logik in jeden Check zu kopieren, speichern Sie sie als Snippet und binden sie über ihren Namen ein. Ändern Sie sie an einer Stelle, und jeder Check, der sie verwendet, übernimmt die Änderung.

Ein Snippet ist einfach ein kleines JavaScript-Modul. Alles, was es mit module.exports exportiert, steht überall dort zur Verfügung, wo Sie es per require einbinden:

require('./snippets/name');

Snippets sind an Ihr Team gebunden, sodass alle im Team dieselben Helfer in ihren Checks verwenden können.

Snippets funktionieren in Setup-, Teardown-, Browser- und Multistep-Skripten. Wenn LoadFocus einen Check ausführt, findet es jedes require('./snippets/<name>') in Ihren Skripten und liefert diese Snippets mit dem Lauf aus. Ein Snippet kann dieselben npm-Module nutzen wie ein Skript (zum Beispiel axios, got und crypto).

Snippets verwalten

Öffnen Sie die Snippets-Seite, um Snippets zu erstellen, zu bearbeiten und zu löschen.

Ein Snippet erstellen

1. Klicken Sie auf New Snippet.
2. Geben Sie einen Snippet-Namen ein. Das ist der Name, den Sie in Ihren Skripten einbinden (zum Beispiel auth oder format-date). Namen dürfen nur Buchstaben, Zahlen, Bindestriche und Unterstriche enthalten.
3. Schreiben Sie Ihr JavaScript im Editor. Exportieren Sie das, was Sie wiederverwenden möchten, mit module.exports.
4. Klicken Sie auf Save Snippet.

Jeder Snippet-Name muss innerhalb Ihres Teams eindeutig sein und darf bis zu 64 Zeichen lang sein. Der Free-Plan enthält bis zu 5 Snippets; kostenpflichtige Pläne bis zu 100. Ein Snippet darf bis zu 100.000 Zeichen lang sein.

Ein Snippet bearbeiten oder löschen

Verwenden Sie die Zeilenaktionen auf der Snippets-Seite, um den Code eines Snippets zu aktualisieren oder es zu entfernen. Wenn ein Snippet aktuell von einem oder mehreren Checks verwendet wird, warnt LoadFocus Sie vor dem Speichern oder Löschen, da sich die Änderung auf jeden Check auswirkt, der es einbindet. Eine Aktualisierung wird beim nächsten Lauf jedes Checks wirksam, der es verwendet.

Ein Snippet in einem Check-Skript verwenden

Binden Sie ein Snippet über seinen Namen aus dem Pfad ./snippets/ innerhalb eines Check-Skripts ein:

const auth = require('./snippets/auth');

Der zurückgegebene Wert ist genau das, was das Snippet exportiert.

Ein Setup- oder Teardown-Skript ist bereits der Rumpf einer Funktion. Schreiben Sie darin also einfache Anweisungen und fügen Sie dem Skript selbst kein module.exports hinzu.

Beispiel

Erstellen Sie ein Snippet namens auth, das einen Authorization-Header erzeugt:

// snippet: auth
module.exports = function bearer(token) {
  return { Authorization: 'Bearer ' + token };
};

Verwenden Sie es dann in einem Check-Skript:

const bearer = require('./snippets/auth');

const headers = bearer(token);
// `token` ist ein Wert, den Ihr Skript bereits hat, zum Beispiel ein Secret
// `headers` an Ihren Request übergeben

Sie können beliebige wiederverwendbare Logik in einem Snippet ablegen: Request-Signierung, Payload-Builder, Datums- und String-Helfer oder gemeinsame Assertions, und es in so vielen Checks einbinden, wie Sie möchten.

Beispiel: Anmeldung aus einem Setup-Skript

Ein Snippet kann auch mit ctx arbeiten. Dieses Snippet namens login holt ein Token und speichert es in ctx.vars.token, damit der Check es lesen kann:

// Snippet: login
const axios = require('axios');

module.exports = async function login(ctx, username, password) {
  const res = await axios.post('https://api.example.com/auth', { username, password });
  ctx.vars.token = res.data.token;
};

Übergeben Sie die Zugangsdaten als Argumente: Eine ctx.secrets-Referenz, die nur innerhalb eines Snippets steht, wird für den Lauf nicht aufgelöst. In einem Setup-Skript eines Browser-Checks:

const login = require('./snippets/login');

await login(ctx, 'ci-user', ctx.secrets.PASSWORD);
// ctx.vars.token ist jetzt für den Check verfügbar

API-Check-Skripte erhalten statt ctx das Objekt request (Setup) beziehungsweise request und response (Teardown). Reichen Sie diese an Ihre Snippet-Funktion weiter.

Hinweise und Einschränkungen

• Nur literaler Pfad. Nur die Form require('./snippets/<name>') wird aufgelöst. Dynamische Pfade wie require('./snippets/' + name) werden nicht unterstützt.
• Keine Snippet-zu-Snippet-Auflösung. Ein Snippet, das ein anderes Snippet einbindet, wird nicht aufgelöst. Legen Sie gemeinsame Logik stattdessen in ein einzelnes Snippet.
• Fehlende Snippets schlagen sofort fehl. Existiert ein eingebundenes Snippet nicht, schlägt der Check-Lauf vor dem Versand fehl, mit einer Fehlermeldung, die das fehlende Snippet nennt.
• Gemeinsame Sandbox. Snippets laufen in derselben Sandbox wie das aufrufende Skript. Ein Snippet sieht ctx, request oder response nur, wenn Ihr Skript es übergibt.

Snippets vs. Variablen und Secrets

Verwenden Sie Snippets für wiederverwendbaren Code: Hilfsfunktionen und Logik, die über mehrere Check-Skripte hinweg geteilt werden.

Verwenden Sie Variablen für wiederverwendbare Werte wie Basis-URLs und Konto-IDs, eingebunden mit ${{VARIABLE_NAME}}.

Verwenden Sie Secrets für sensible Werte wie API-Tokens und Passwörter. Secrets sind in der Oberfläche nur schreibbar und werden mit ${{SECRET_NAME}} eingebunden.

Tipp: Bewahren Sie sensible Werte in Secrets auf, statt sie fest in einem Snippet zu hinterlegen. Übergeben Sie sie stattdessen zur Laufzeit an die Funktionen Ihres Snippets.

Verwandte Anleitungen

• So erstellen Sie einen neuen API-Check
• Variablen
• Multistep-API-Checks
• Setup- und Teardown-Skripte