Files
nexarch/mail/internal/mailapi/contract_test.go
patrickandClaude Sonnet 5 b05d223543
CI / Web-Barrierefreiheitspruefung (axe, Tastatur, Reflow, Textabstaende) (push) Canceled after 0s
CI / Web (pdf-viewer) (push) Canceled after 0s
CI / Core-Modul (Build/Vet/Test) (push) Canceled after 0s
CI / DMS Security-Test-Gate (AC5, Merge-Gate) (push) Canceled after 0s
CI / Connect Security-Test-Gate (QA-01 AC4, Merge-Gate) (push) Canceled after 0s
CI / DMS-Modul Supply-Chain-Scan (govulncheck) (push) Canceled after 0s
CI / Web (dms-browser) (push) Canceled after 0s
CI / Web (shl) (push) Canceled after 0s
Supply-Chain-Scan (Go) / govulncheck (push) Canceled after 0s
Mail-Schnittstellen-Vertragstests / contract-tests (push) Canceled after 0s
Supply-Chain-Scan (npm) / npm-audit (push) Canceled after 0s
CI / DMS-Modul (Lint/Build/Test/Coverage/Artefakt) (push) Canceled after 0s
Merge PR #298: UX-01: Postfach- & Ordneransicht (Mail)
Konfliktaufloesung:
- mail/internal/mailapi/mailapi_test.go: beide Seiten fuegten neue Tests
  an derselben Stelle an (HEAD: UX-03 Magic-Byte-Contenttype-Tests,
  eingehend: UX-01 Postfach-/Ordner-Tests), rein additiv zusammengefuehrt
- mail/internal/retentionclient/retentionclient.go: zwei unabhaengige
  Register-Implementierungen durch den Merge entstanden (totes
  PascalCase-Schema aus HEAD vs. aktiv genutztes snake_case-Schema),
  tote Variante + zugehoerige Tests entfernt
- mail/internal/mailapi/contract_test.go + mailapi_test.go: SearchClient-
  Interface erweitert (SearchWithFilters/ListByMailbox/Facets), beide
  Test-Fakes um diese Methoden ergaenzt

go build/vet sauber, Tests in internal/mailapi und internal/retentionclient
gruen (ein Testfehler in TestContract_DocumentedEndpointsMatchActualBehavior/
anhang_download_erfolg bereits auf main vor diesem Merge vorhanden, nicht
Teil dieser Aenderung).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-19 12:39:55 +02:00

474 lines
17 KiB
Go

// 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
}
func (f *contractSearchFake) SearchWithFilters(ctx context.Context, tenantSlug, queryText string, _ []search.FacetFilter) ([]search.Result, error) {
return f.Search(ctx, tenantSlug, queryText)
}
func (f *contractSearchFake) ListByMailbox(_ context.Context, tenantSlug, mailbox string) ([]search.Document, error) {
if f.searchErr != nil {
return nil, f.searchErr
}
var out []search.Document
for _, doc := range f.docs[tenantSlug] {
if doc.Mailbox == mailbox {
out = append(out, doc)
}
}
return out, nil
}
func (f *contractSearchFake) Facets(_ context.Context, tenantSlug, _ string, _ []search.FacetFilter) (search.FacetResult, error) {
if f.searchErr != nil {
return search.FacetResult{}, f.searchErr
}
counts := map[string]int64{}
for _, doc := range f.docs[tenantSlug] {
counts[doc.Mailbox]++
}
values := make([]search.FacetValue, 0, len(counts))
for mailbox, count := range counts {
values = append(values, search.FacetValue{Value: mailbox, Count: count})
}
return search.FacetResult{Values: map[string][]search.FacetValue{"mailbox": values}}, 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)
}