Einen Modulvertrag testen

Einführung

Eine Konfiguration kann formatiert und strukturell gültig sein und trotzdem eine Berichtsumgebung falsch kennzeichnen. Ihr Team benötigt ausführbare Prüfungen der Eingaben, Ausgabewerte und geplanten Tags eines kleinen Speichermoduls, bevor es einem Auslieferungsplan vertraut.

Sie schreiben einen Modulvertrag, testen zwei unterstützte Umgebungen und eine nicht unterstützte Eingabe und lassen einen tatsächlichen fachlichen Fehler den Job stoppen. Sie sollten Modulvariablen und -ausgabewerte sowie die Formatierungs- und Validierungsprüfungen aus dem vorherigen Lab verstehen. Vorhandener Referenzspeicher muss unverändert bleiben.

Bezug zu Zertifizierungen

Den Eingabevertrag definieren

In diesem Schritt definieren Sie, welche Umgebungseingaben das Speichermodul akzeptiert. Die Eingabevalidierung weist eine nicht unterstützte Anfrage zurück, bevor ein Ressourcenplan erstellt wird.

Wechseln Sie in das bereitgestellte Modul und laden Sie die vorbereiteten Werkzeuge.

cd /home/labex/project/report-module
source environment.sh

Lesen Sie seine Schnittstelle und Ressourcenimplementierung.

cat variables.tf main.tf outputs.tf pipeline.json

environment wählt preview oder review aus; bucket_prefix unterscheidet die Speichernamen eines Aufrufers. Der Bucket-Name kombiniert beide Eingaben, und das Environment-Tag sowie der Ausgabewert müssen die angeforderte Umgebung kennzeichnen. Die bereitgestellten Dateien main.tf, outputs.tf, provider.tf und run-job.py müssen erhalten bleiben: Lassen Sie ihren endgültigen Inhalt unverändert. Ihre Änderungen gehören in variables.tf, tests/ und pipeline.json.

Fügen Sie einen validation-Block zu environment hinzu. contains prüft die Zugehörigkeit zur Liste der unterstützten Werte; eine als falsch ausgewertete condition erzeugt die angegebene Fehlermeldung. Das Here-Dokument mit Anführungszeichen schreibt den HCL-Inhalt unverändert.

cat > variables.tf <<'EOF'
variable "environment" {
  type    = string
  default = "preview"
  validation {
    condition     = contains(["preview", "review"], var.environment)
    error_message = "Choose preview or review."
  }
}
variable "bucket_prefix" {
  type    = string
  default = "delivery-contract"
}
EOF

Formatieren Sie Ihre Änderung.

terraform fmt

Testen Sie eine nicht unterstützte Anfrage. -var liefert einen Wert für diesen Aufruf. Dieser Befehl gibt absichtlich den nativen Exit-Code 1 zurück; er muss Choose preview or review. melden, statt einen Produktions-Bucket vorzuschlagen.

terraform plan -input=false -var=environment=production

Die Validierung definiert die akzeptierte Schnittstelle. Im nächsten Schritt testen Sie beide akzeptierten Werte und diese erwartete Zurückweisung.

Assertions schreiben und einen tatsächlichen Fehler beobachten

In diesem Schritt prüfen Sie mit dem nativen Befehl terraform test das geplante Verhalten des Moduls. Formatierung und Validierung können einen fest kodierten, aber falschen Ausgabewert akzeptieren; eine Assertion vergleicht das berechnete Ergebnis mit der angeforderten Eingabe.

Terraform liest .tftest.hcl-Dateien unter tests/. Jeder run ist ein unabhängiges Testszenario. Ein explizites command = plan wertet einen Plan aus, ohne ihn anzuwenden. Halten Sie Testdateien unter tests/ im Format .tftest.hcl. In diesem Lab muss jeder Lauf den Plan-Modus und das bereitgestellte Modul mit dessen Provider verwenden; alternative Module, Provider-Mocks und Overrides liegen außerhalb der Aufgabe. Übernehmen Sie bucket_prefix unverändert aus der Testsuite-Eingabe: Weisen Sie es nicht in Testvariablen auf Datei- oder Testlaufebene zu, damit ein Aufrufer ein anderes zulässiges Präfix auswählen kann. Diese Tests prüfen bekannte Planwerte und nicht die tatsächliche Erstellung, Laufzeitberechtigungen oder eine bereitgestellte Anwendung.

Erstellen Sie das Testverzeichnis. mkdir -p erstellt es bei Bedarf und akzeptiert ein bereits vorhandenes Verzeichnis.

mkdir -p tests

Schreiben Sie Assertions für die Standardumgebung und die alternative Umgebung. var bezieht sich auf die Eingaben des Testlaufs, Ressourcenreferenzen untersuchen geplante Werte und output bezieht sich auf Modulausgaben. expect_failures verlangt, dass die Validierung der genannten Variablen fehlschlägt; es macht aus beliebigen Provider- oder Netzwerkfehlern keine erfolgreichen Tests.

cat > tests/contract.tftest.hcl <<'EOF'
run "preview_contract" {
  command = plan
  assert {
    condition     = output.environment == var.environment
    error_message = "The output must identify the requested environment."
  }
  assert {
    condition     = aws_s3_bucket.reports.bucket == "${var.bucket_prefix}-${var.environment}"
    error_message = "The bucket name must use the requested prefix and environment."
  }
  assert {
    condition     = aws_s3_bucket.reports.tags.Environment == var.environment
    error_message = "The planned tag must identify the requested environment."
  }
}
run "review_contract" {
  command = plan
  variables { environment = "review" }
  assert {
    condition     = output.environment == var.environment
    error_message = "The alternate environment must not use the default label."
  }
  assert {
    condition     = aws_s3_bucket.reports.bucket == "${var.bucket_prefix}-${var.environment}"
    error_message = "The alternate bucket must use its requested inputs."
  }
  assert {
    condition     = aws_s3_bucket.reports.tags.Environment == var.environment
    error_message = "The alternate environment tag must match its input."
  }
}
run "unsupported_environment" {
  command         = plan
  variables { environment = "production" }
  expect_failures = [var.environment]
}
EOF

Formatieren Sie die Tests und Moduldateien rekursiv.

terraform fmt -recursive

Führen Sie die Testsuite aus.

terraform test

Erwarten Sie drei bestandene Testläufe und eine Erfolgszusammenfassung. Es wird kein Test-Bucket bereitgestellt. Ein- und Ausgabewerte stammen aus einem tatsächlichen Terraform-Plan mit dem konfigurierten Provider.

Weisen Sie nach, dass Ihre Assertions einen plausiblen Fehler erkennen. Ersetzen Sie vorübergehend nur die Umgebungsausgabe durch eine feste Standardbezeichnung; behalten Sie die Bucket-Namensausgabe bei.

cat > outputs.tf <<'EOF'
output "environment" {
  value = "preview"
}
output "bucket_name" {
  value = aws_s3_bucket.reports.bucket
}
EOF

Führen Sie die Suite erneut aus. Dieser Befehl gibt absichtlich den nativen Exit-Code 1 zurück. Die Assertion für die alternative Umgebung sollte fehlschlagen und damit zeigen, dass gültige HCL-Konfiguration dennoch den Modulvertrag verletzen kann.

terraform test

Stellen Sie die bereitgestellte Ausgabeimplementierung aus Git wieder her. Dadurch entfernen Sie Ihren temporären Fehler, während die von Ihnen geschriebene Validierung und die Tests erhalten bleiben.

git restore -- outputs.tf

Lassen Sie die korrigierte Implementierung dieselben Assertions durchlaufen.

terraform test

Alle Läufe sollten wieder bestehen. Tests müssen zulässige Eingaben akzeptieren, statt lediglich einen Standardausgabewert zu erkennen.

Den Auslieferungsjob durch Tests stoppen lassen

In diesem Schritt platzieren Sie Modultests zwischen den statischen Prüfungen und der Planung. Das bereitgestellte Ausführungsprogramm ist Teil der Vorbereitung; bearbeiten Sie die Phasenkonfiguration, statt run-job.py zu ändern.

Fügen Sie test nach fmt/validate und vor plan ein.

cat > pipeline.json <<'EOF'
{"stages":["fmt","validate","test","plan"]}
EOF

Führen Sie den vollständigen Job aus.

python3 run-job.py

Alle vier Phasen sollten bestehen. Der abschließende Plan kann den nativen Code 2 zurückgeben, weil dieses Modul nicht angewendet wurde; der Runner behandelt dies als erfolgreiche Vorschau. Ein fehlgeschlagener Test muss den Job hingegen vor seiner Plan-Phase stoppen. Es gibt keine Apply-Phase.

Führen Sie die Suite mit einem anderen zulässigen Bucket-Präfix aus. Dieses -var ändert die Suite-Eingabe, ohne das Modul oder seine Tests zu bearbeiten.

terraform test -var=bucket_prefix=audit-contract

Dieselben drei Läufe sollten bestehen. Übernehmen Sie für diese Übung bucket_prefix in jedem Lauf unverändert vom Aufrufer: Weisen Sie es nicht in variables-Blöcken der Testdatei oder einzelner Testläufe zu. Solche Zuweisungen überschreiben CLI-Testeingaben und würden verhindern, dass dieser Befehl sein angefordertes Präfix testet. Umgebungsüberschreibungen bleiben notwendig, um beide unterstützten Umgebungen zu testen. Aus den angeforderten Eingaben aufgebaute Assertions funktionieren weiterhin, wenn der Aufrufer einen anderen gültigen Namen wählt.

Lesen Sie den vorhandenen Referenzbericht direkt aus dem Speicher. Diese vorbereiteten Buckets gehören zu einer anderen Umgebung; löschen oder verändern Sie sie nicht.

aws s3   cp s3://delivery-reference-reports/report.txt -

Er sollte weiterhin reference report v1 enthalten. Prüfen Sie auch die benachbarten Daten.

aws s3   cp s3://delivery-reference-neighbor/keep.txt -

Erwarten Sie preserve contract neighbor. Ihre Tests haben keine Speicherressourcen erstellt, daher gibt es keinen zu löschenden Test-Stack. Behalten Sie den Eingabevertrag, die Tests und die Pipeline-Konfiguration für die abschließende Prüfung bei; der temporäre Ausgabefehler wurde bereits entfernt.

Zusammenfassung

Sie haben einen Vertrag für unterstützte Eingaben definiert, mit nativen Terraform-Tests im Plan-Modus geplante Ausgabewerte und Tags mit Eingaben verglichen und einen tatsächlichen Assertion-Fehler beobachtet. Anschließend haben Sie Tests in die Qualitätsprüfung der Auslieferung integriert und dabei vorhandene Daten sowie den Geschäfts-State erhalten.

Tests im Plan-Modus weisen kein bereitgestelltes Laufzeitverhalten nach. Spätere Auslieferungsschritte kombinieren diese Prüfungen mit einem geprüften konkreten Plan und einer tatsächlichen kontrollierten Ausführung des Plans. Informationen zu den hier geübten Mechanismen finden Sie in der offiziellen Terraform-test-Referenz und der Dokumentation zur Testkonfiguration.