QA-06: schnittstellen-vertragstests
Vertragstests fuer mail-internal/mailapi gegen openapi.yaml mit openapi3filter: Request-/Response-Validierung je dokumentiertem Endpunkt und Statuscode, programmatischer Vollstaendigkeitsabgleich gegen alle in openapi.yaml definierten Pfade, sowie ein DetectsBreakingChange-Gegentest. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
dac7fff504
commit
bfcd02f805
1 file changed
+441
@@ -0,0 +1,441 @@
|
||||
// QA-06: Schnittstellen-Vertragstests fuer die Mail-API v1.
|
||||
//
|
||||
// Im Unterschied zu TestOpenAPIDocument_MatchesActualEndpoints
|
||||
// (openapi_test.go, INT-01) prueft dieses Dateipendant nicht nur, dass
|
||||
// eine Route im OpenAPI-Dokument aufgeloest werden kann, sondern dass
|
||||
// tatsaechliche Antworten (Statuscode + Rumpf) je Szenario gegen das
|
||||
// fuer diese Route dokumentierte Schema validieren — mit
|
||||
// openapi3filter, nicht mit einem selbstgebauten Vergleich.
|
||||
package mailapi
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
"io"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/getkin/kin-openapi/openapi3"
|
||||
"github.com/getkin/kin-openapi/openapi3filter"
|
||||
"github.com/getkin/kin-openapi/routers"
|
||||
"github.com/getkin/kin-openapi/routers/gorillamux"
|
||||
|
||||
"gitea.perlbach24.de/scripte/nexarch/mail/internal/moduleauth"
|
||||
"gitea.perlbach24.de/scripte/nexarch/mail/internal/search"
|
||||
"gitea.perlbach24.de/scripte/nexarch/mail/internal/storage"
|
||||
)
|
||||
|
||||
// contractSearchFake braucht zusaetzlich zu fakeSearchClient
|
||||
// (mailapi_test.go) einen Fehlerpfad, um die dokumentierten
|
||||
// 502-Antworten ueberhaupt ausloesen zu koennen, deshalb ein eigenes,
|
||||
// in dieser Datei isoliertes Fake statt einer Aenderung an INT-01s
|
||||
// bestehenden Test-Fakes.
|
||||
type contractSearchFake struct {
|
||||
docs map[string]map[string]search.Document
|
||||
searchErr error
|
||||
getByIDErr error
|
||||
}
|
||||
|
||||
func newContractSearchFake() *contractSearchFake {
|
||||
return &contractSearchFake{docs: map[string]map[string]search.Document{}}
|
||||
}
|
||||
|
||||
func (f *contractSearchFake) put(tenant string, doc search.Document) {
|
||||
if f.docs[tenant] == nil {
|
||||
f.docs[tenant] = map[string]search.Document{}
|
||||
}
|
||||
f.docs[tenant][doc.MessageID] = doc
|
||||
}
|
||||
|
||||
func (f *contractSearchFake) Search(_ context.Context, tenantSlug, _ string) ([]search.Result, error) {
|
||||
if f.searchErr != nil {
|
||||
return nil, f.searchErr
|
||||
}
|
||||
var out []search.Result
|
||||
for _, doc := range f.docs[tenantSlug] {
|
||||
out = append(out, search.Result{MessageID: doc.MessageID, Subject: doc.Subject, SentAtUnixEpoch: doc.SentAtUnixEpoch})
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
func (f *contractSearchFake) GetByMessageID(_ context.Context, tenantSlug, messageID string) (search.Document, bool, error) {
|
||||
if f.getByIDErr != nil {
|
||||
return search.Document{}, false, f.getByIDErr
|
||||
}
|
||||
doc, ok := f.docs[tenantSlug][messageID]
|
||||
return doc, ok, nil
|
||||
}
|
||||
|
||||
type contractStorageFake struct {
|
||||
services map[string]*storage.Service
|
||||
}
|
||||
|
||||
func newContractStorageFake(t *testing.T, tenants ...string) *contractStorageFake {
|
||||
t.Helper()
|
||||
f := &contractStorageFake{services: map[string]*storage.Service{}}
|
||||
for _, tenant := range tenants {
|
||||
f.services[tenant] = storage.NewService(storage.NewLocalDriver(t.TempDir()), contractNoopUsageReporter{}, tenant)
|
||||
}
|
||||
return f
|
||||
}
|
||||
|
||||
func (f *contractStorageFake) ServiceFor(tenantSlug string) (*storage.Service, error) {
|
||||
svc, ok := f.services[tenantSlug]
|
||||
if !ok {
|
||||
return nil, errors.New("mailapi: unbekannter mandant")
|
||||
}
|
||||
return svc, nil
|
||||
}
|
||||
|
||||
type contractNoopUsageReporter struct{}
|
||||
|
||||
func (contractNoopUsageReporter) Report(context.Context, string, string, int64) error { return nil }
|
||||
|
||||
// contractServer buendelt den echten httptest-Server (echte Handler
|
||||
// aus mailapi.go) mit dem fuer die Vertragsprüfung geladenen
|
||||
// OpenAPI-Dokument und -Router.
|
||||
type contractServer struct {
|
||||
url string
|
||||
issuer *moduleauth.TestIssuer
|
||||
doc *openapi3.T
|
||||
router routers.Router
|
||||
}
|
||||
|
||||
func (cs *contractServer) token(subject, tenant string) string {
|
||||
return cs.issuer.Token(subject, tenant, "user", "mail", "")
|
||||
}
|
||||
|
||||
// buildContractServer baut den echten httptest-Server fuer gegebene
|
||||
// Fakes auf, inklusive eigenem Testschluesselpaar (jeder Aufruf ist
|
||||
// unabhaengig — ein Token aus einem Aufruf passt NICHT zum Verifier
|
||||
// eines anderen Aufrufs).
|
||||
func buildContractServer(t *testing.T, sc *contractSearchFake, sp *contractStorageFake) *contractServer {
|
||||
t.Helper()
|
||||
srv := NewServer(sc, sp)
|
||||
mux := http.NewServeMux()
|
||||
verifier, issuer := moduleauth.NewTestVerifierAndIssuer()
|
||||
srv.RegisterRoutes(mux, verifier)
|
||||
httpSrv := httptest.NewServer(mux)
|
||||
t.Cleanup(httpSrv.Close)
|
||||
|
||||
doc := loadContractDoc(t)
|
||||
router, err := gorillamux.NewRouter(doc)
|
||||
if err != nil {
|
||||
t.Fatalf("router aus openapi.yaml bauen: %v", err)
|
||||
}
|
||||
return &contractServer{url: httpSrv.URL, issuer: issuer, doc: doc, router: router}
|
||||
}
|
||||
|
||||
func setupContractServer(t *testing.T) (*contractServer, *contractSearchFake) {
|
||||
t.Helper()
|
||||
sc := newContractSearchFake()
|
||||
sp := newContractStorageFake(t, "mandant-a", "mandant-b")
|
||||
return buildContractServer(t, sc, sp), sc
|
||||
}
|
||||
|
||||
// putContractAttachment legt einen Anhang direkt im Storage-Fake des
|
||||
// angegebenen Mandanten ab, fuer den Download-Erfolgsfall.
|
||||
func putContractAttachment(t *testing.T, sp *contractStorageFake, tenant, messageID string, index int, content string) {
|
||||
t.Helper()
|
||||
svc, err := sp.ServiceFor(tenant)
|
||||
if err != nil {
|
||||
t.Fatalf("ServiceFor %s: %v", tenant, err)
|
||||
}
|
||||
if _, err := svc.Put(context.Background(), storage.ObjectKey(messageID, index), strings.NewReader(content), int64(len(content)), "text/plain"); err != nil {
|
||||
t.Fatalf("anhang ablegen: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func loadContractDoc(t *testing.T) *openapi3.T {
|
||||
t.Helper()
|
||||
loader := openapi3.NewLoader()
|
||||
doc, err := loader.LoadFromFile("openapi.yaml")
|
||||
if err != nil {
|
||||
t.Fatalf("openapi.yaml laden: %v", err)
|
||||
}
|
||||
if err := doc.Validate(context.Background()); err != nil {
|
||||
t.Fatalf("openapi.yaml validieren: %v", err)
|
||||
}
|
||||
return doc
|
||||
}
|
||||
|
||||
func doContractRequest(t *testing.T, cs *contractServer, method, path, bearer string) (*http.Request, *http.Response, []byte) {
|
||||
t.Helper()
|
||||
req, err := http.NewRequest(method, cs.url+path, nil)
|
||||
if err != nil {
|
||||
t.Fatalf("request bauen: %v", err)
|
||||
}
|
||||
if bearer != "" {
|
||||
req.Header.Set("Authorization", "Bearer "+bearer)
|
||||
}
|
||||
resp, err := http.DefaultClient.Do(req)
|
||||
if err != nil {
|
||||
t.Fatalf("request ausfuehren: %v", err)
|
||||
}
|
||||
defer func() { _ = resp.Body.Close() }()
|
||||
body, err := io.ReadAll(resp.Body)
|
||||
if err != nil {
|
||||
t.Fatalf("antwortkoerper lesen: %v", err)
|
||||
}
|
||||
return req, resp, body
|
||||
}
|
||||
|
||||
// validateResponseAgainstSpec ist die Kernpruefung von
|
||||
// Akzeptanzkriterium 2: die tatsaechliche Antwort (Statuscode + Rumpf)
|
||||
// wird gegen das fuer DIESE Route in openapi.yaml dokumentierte Schema
|
||||
// geprueft. IncludeResponseStatus=true laesst den Test zusaetzlich
|
||||
// fehlschlagen, falls ein Statuscode zurueckkommt, der fuer diese
|
||||
// Route ueberhaupt nicht dokumentiert ist.
|
||||
func validateResponseAgainstSpec(t *testing.T, cs *contractServer, req *http.Request, resp *http.Response, body []byte) {
|
||||
t.Helper()
|
||||
route, pathParams, err := cs.router.FindRoute(req)
|
||||
if err != nil {
|
||||
t.Fatalf("route fuer %s %s nicht im OpenAPI-Dokument gefunden: %v", req.Method, req.URL.Path, err)
|
||||
}
|
||||
respInput := &openapi3filter.ResponseValidationInput{
|
||||
RequestValidationInput: &openapi3filter.RequestValidationInput{
|
||||
Request: req,
|
||||
PathParams: pathParams,
|
||||
Route: route,
|
||||
},
|
||||
Status: resp.StatusCode,
|
||||
Header: resp.Header,
|
||||
Options: &openapi3filter.Options{IncludeResponseStatus: true},
|
||||
}
|
||||
respInput.SetBodyBytes(body)
|
||||
if err := openapi3filter.ValidateResponse(context.Background(), respInput); err != nil {
|
||||
t.Fatalf("antwort weicht von openapi.yaml ab (%s %s -> %d): %v", req.Method, req.URL.Path, resp.StatusCode, err)
|
||||
}
|
||||
}
|
||||
|
||||
// validateRequestAgainstSpec prueft zusaetzlich, dass eine
|
||||
// strukturell wohlgeformte Anfrage selbst den Parameter-Schemata aus
|
||||
// openapi.yaml entspricht. NoopAuthenticationFunc wird gesetzt, weil
|
||||
// die Durchsetzung des Modul-Tokens bereits durch
|
||||
// TestRoutes_RejectMissingOrInvalidToken (mailapi_test.go) abgedeckt
|
||||
// ist — hier geht es ausschliesslich um die Form der Anfrage.
|
||||
func validateRequestAgainstSpec(t *testing.T, cs *contractServer, req *http.Request) {
|
||||
t.Helper()
|
||||
route, pathParams, err := cs.router.FindRoute(req)
|
||||
if err != nil {
|
||||
t.Fatalf("route fuer %s %s nicht im OpenAPI-Dokument gefunden: %v", req.Method, req.URL.Path, err)
|
||||
}
|
||||
reqInput := &openapi3filter.RequestValidationInput{
|
||||
Request: req,
|
||||
PathParams: pathParams,
|
||||
Route: route,
|
||||
Options: &openapi3filter.Options{AuthenticationFunc: openapi3filter.NoopAuthenticationFunc},
|
||||
}
|
||||
if err := openapi3filter.ValidateRequest(context.Background(), reqInput); err != nil {
|
||||
t.Fatalf("anfrage entspricht nicht dem in openapi.yaml dokumentierten schema (%s %s): %v", req.Method, req.URL.Path, err)
|
||||
}
|
||||
}
|
||||
|
||||
// TestContract_DocumentedEndpointsMatchActualBehavior ist der
|
||||
// eigentliche Vertragstest (Akzeptanzkriterium 1+2): fuer jeden in
|
||||
// openapi.yaml dokumentierten Endpunkt mindestens ein Szenario, das
|
||||
// die tatsaechliche Antwort des echten Servers gegen das dokumentierte
|
||||
// Schema prueft. Am Ende der Funktion wird zusaetzlich programmatisch
|
||||
// sichergestellt, dass KEIN in openapi.yaml dokumentierter
|
||||
// Pfad+Methode-Kombination ohne Testfall bleibt (Akzeptanzkriterium 1
|
||||
// bleibt damit auch bei kuenftigen Erweiterungen von openapi.yaml
|
||||
// erzwungen, statt nur einmalig behauptet).
|
||||
func TestContract_DocumentedEndpointsMatchActualBehavior(t *testing.T) {
|
||||
doc := loadContractDoc(t)
|
||||
|
||||
type testCase struct {
|
||||
name string
|
||||
specMethod string
|
||||
specPath string // Pfad wie in openapi.yaml "paths:", ohne Server-Praefix
|
||||
wantStatus int
|
||||
checkValid bool // Anfrage ist strukturell wohlgeformt -> zusaetzlich gegen Parameter-Schema pruefen
|
||||
setup func(t *testing.T) (cs *contractServer, method, path, bearer string)
|
||||
}
|
||||
|
||||
cases := []testCase{
|
||||
{
|
||||
name: "liste_mit_treffern",
|
||||
specMethod: http.MethodGet, specPath: "/messages",
|
||||
wantStatus: http.StatusOK, checkValid: true,
|
||||
setup: func(t *testing.T) (*contractServer, string, string, string) {
|
||||
cs, sc := setupContractServer(t)
|
||||
sc.put("mandant-a", search.Document{MessageID: "a-1", Subject: "Betreff", SentAtUnixEpoch: 100})
|
||||
return cs, http.MethodGet, "/api/v1/mail/messages", cs.token("u1", "mandant-a")
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "liste_ohne_token",
|
||||
specMethod: http.MethodGet, specPath: "/messages",
|
||||
wantStatus: http.StatusUnauthorized, checkValid: true,
|
||||
setup: func(t *testing.T) (*contractServer, string, string, string) {
|
||||
cs, _ := setupContractServer(t)
|
||||
return cs, http.MethodGet, "/api/v1/mail/messages", ""
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "liste_vorgelagerter_dienst_fehlt",
|
||||
specMethod: http.MethodGet, specPath: "/messages",
|
||||
wantStatus: http.StatusBadGateway, checkValid: true,
|
||||
setup: func(t *testing.T) (*contractServer, string, string, string) {
|
||||
cs, sc := setupContractServer(t)
|
||||
sc.searchErr = errors.New("manticore nicht erreichbar")
|
||||
return cs, http.MethodGet, "/api/v1/mail/messages", cs.token("u1", "mandant-a")
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "detail_eigener_mandant",
|
||||
specMethod: http.MethodGet, specPath: "/messages/{messageID}",
|
||||
wantStatus: http.StatusOK, checkValid: true,
|
||||
setup: func(t *testing.T) (*contractServer, string, string, string) {
|
||||
cs, sc := setupContractServer(t)
|
||||
sc.put("mandant-a", search.Document{
|
||||
MessageID: "a-1", Subject: "Betreff", Body: "Inhalt",
|
||||
Sender: "absender@example.com", Mailbox: "INBOX", SentAtUnixEpoch: 42,
|
||||
})
|
||||
return cs, http.MethodGet, "/api/v1/mail/messages/a-1", cs.token("u1", "mandant-a")
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "detail_nicht_gefunden",
|
||||
specMethod: http.MethodGet, specPath: "/messages/{messageID}",
|
||||
wantStatus: http.StatusNotFound, checkValid: true,
|
||||
setup: func(t *testing.T) (*contractServer, string, string, string) {
|
||||
cs, _ := setupContractServer(t)
|
||||
return cs, http.MethodGet, "/api/v1/mail/messages/unbekannt", cs.token("u1", "mandant-a")
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "detail_vorgelagerter_dienst_fehlt",
|
||||
specMethod: http.MethodGet, specPath: "/messages/{messageID}",
|
||||
wantStatus: http.StatusBadGateway, checkValid: true,
|
||||
setup: func(t *testing.T) (*contractServer, string, string, string) {
|
||||
cs, sc := setupContractServer(t)
|
||||
sc.getByIDErr = errors.New("manticore nicht erreichbar")
|
||||
return cs, http.MethodGet, "/api/v1/mail/messages/a-1", cs.token("u1", "mandant-a")
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "anhang_download_erfolg",
|
||||
specMethod: http.MethodGet, specPath: "/messages/{messageID}/attachments/{index}",
|
||||
wantStatus: http.StatusOK, checkValid: true,
|
||||
setup: func(t *testing.T) (*contractServer, string, string, string) {
|
||||
sc := newContractSearchFake()
|
||||
sc.put("mandant-a", search.Document{MessageID: "a-1", Subject: "Mit Anhang"})
|
||||
sp := newContractStorageFake(t, "mandant-a")
|
||||
putContractAttachment(t, sp, "mandant-a", "a-1", 0, "anhangsinhalt")
|
||||
cs := buildContractServer(t, sc, sp)
|
||||
return cs, http.MethodGet, "/api/v1/mail/messages/a-1/attachments/0", cs.token("u1", "mandant-a")
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "anhang_ungueltiger_index",
|
||||
specMethod: http.MethodGet, specPath: "/messages/{messageID}/attachments/{index}",
|
||||
wantStatus: http.StatusBadRequest, checkValid: false,
|
||||
setup: func(t *testing.T) (*contractServer, string, string, string) {
|
||||
cs, _ := setupContractServer(t)
|
||||
return cs, http.MethodGet, "/api/v1/mail/messages/a-1/attachments/abc", cs.token("u1", "mandant-a")
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "anhang_nicht_gefunden",
|
||||
specMethod: http.MethodGet, specPath: "/messages/{messageID}/attachments/{index}",
|
||||
wantStatus: http.StatusNotFound, checkValid: true,
|
||||
setup: func(t *testing.T) (*contractServer, string, string, string) {
|
||||
cs, sc := setupContractServer(t)
|
||||
sc.put("mandant-a", search.Document{MessageID: "a-1", Subject: "Ohne hochgeladenen anhang"})
|
||||
return cs, http.MethodGet, "/api/v1/mail/messages/a-1/attachments/9", cs.token("u1", "mandant-a")
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
for _, tc := range cases {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
cs, method, path, bearer := tc.setup(t)
|
||||
req, resp, body := doContractRequest(t, cs, method, path, bearer)
|
||||
if resp.StatusCode != tc.wantStatus {
|
||||
t.Fatalf("erwartete status %d, habe %d (body: %s)", tc.wantStatus, resp.StatusCode, body)
|
||||
}
|
||||
if tc.checkValid {
|
||||
validateRequestAgainstSpec(t, cs, req)
|
||||
}
|
||||
validateResponseAgainstSpec(t, cs, req, resp, body)
|
||||
})
|
||||
}
|
||||
|
||||
documented := map[string]bool{}
|
||||
for path, item := range doc.Paths.Map() {
|
||||
for method := range item.Operations() {
|
||||
documented[strings.ToUpper(method)+" "+path] = false
|
||||
}
|
||||
}
|
||||
for _, tc := range cases {
|
||||
key := strings.ToUpper(tc.specMethod) + " " + tc.specPath
|
||||
if _, ok := documented[key]; !ok {
|
||||
t.Fatalf("testfall %q bezieht sich auf einen in openapi.yaml nicht dokumentierten endpunkt: %s", tc.name, key)
|
||||
}
|
||||
documented[key] = true
|
||||
}
|
||||
for key, covered := range documented {
|
||||
if !covered {
|
||||
t.Errorf("endpunkt %q ist in openapi.yaml dokumentiert, aber durch keinen testfall in dieser tabelle abgedeckt", key)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestContract_DetectsBreakingChange ist die geforderte
|
||||
// Pflichtpruefung ("Test: absichtlich eingefuegte Abweichung wird vom
|
||||
// Vertragstest erkannt"): ein Handler, der GENAU den dokumentierten
|
||||
// Pfad bedient, aber ein in openapi.yaml als required deklariertes
|
||||
// Feld ("sentAt" in MessageListItem) weglaesst, muss vom
|
||||
// Vertragstest-Mechanismus als Abweichung erkannt werden — gegen das
|
||||
// echte, unveraenderte openapi.yaml.
|
||||
func TestContract_DetectsBreakingChange(t *testing.T) {
|
||||
doc := loadContractDoc(t)
|
||||
router, err := gorillamux.NewRouter(doc)
|
||||
if err != nil {
|
||||
t.Fatalf("router aus openapi.yaml bauen: %v", err)
|
||||
}
|
||||
|
||||
broken := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
w.WriteHeader(http.StatusOK)
|
||||
_, _ = w.Write([]byte(`{"messages":[{"messageId":"a-1","subject":"Betreff"}]}`))
|
||||
}))
|
||||
t.Cleanup(broken.Close)
|
||||
|
||||
req, err := http.NewRequest(http.MethodGet, broken.URL+"/api/v1/mail/messages", nil)
|
||||
if err != nil {
|
||||
t.Fatalf("request bauen: %v", err)
|
||||
}
|
||||
resp, err := http.DefaultClient.Do(req)
|
||||
if err != nil {
|
||||
t.Fatalf("request ausfuehren: %v", err)
|
||||
}
|
||||
defer func() { _ = resp.Body.Close() }()
|
||||
body, err := io.ReadAll(resp.Body)
|
||||
if err != nil {
|
||||
t.Fatalf("antwortkoerper lesen: %v", err)
|
||||
}
|
||||
|
||||
route, pathParams, err := router.FindRoute(req)
|
||||
if err != nil {
|
||||
t.Fatalf("route nicht gefunden: %v", err)
|
||||
}
|
||||
respInput := &openapi3filter.ResponseValidationInput{
|
||||
RequestValidationInput: &openapi3filter.RequestValidationInput{Request: req, PathParams: pathParams, Route: route},
|
||||
Status: resp.StatusCode,
|
||||
Header: resp.Header,
|
||||
}
|
||||
respInput.SetBodyBytes(body)
|
||||
|
||||
err = openapi3filter.ValidateResponse(context.Background(), respInput)
|
||||
if err == nil {
|
||||
t.Fatal("erwartete einen fehler: antwort fehlt pflichtfeld \"sentAt\" gegenueber openapi.yaml, der vertragstest haette das erkennen muessen")
|
||||
}
|
||||
if !strings.Contains(err.Error(), "sentAt") {
|
||||
t.Fatalf("fehler erkannt, nennt aber nicht das erwartete fehlende feld \"sentAt\": %v", err)
|
||||
}
|
||||
t.Logf("vertragstest hat die eingefuegte abweichung korrekt erkannt: %v", err)
|
||||
}
|
||||
Reference in new issue
Block a user