feat: Added a test tab in awards to test the matching

internal/award/award_test.go

@@ -384,6 +384,65 @@ func TestComputeOrFallbackAfterUnlistedPrimary(t *testing.T) {
 	t.Errorf("BG not worked; refs = %v", refCodes(r))
 }
 
+// Explain must account for the WAIP case exactly: the primary rule produces a
+// candidate that is NOT a province, says so, and the QTH fallback then finds BG.
+func TestExplainAccountsForEveryRule(t *testing.T) {
+	def := Def{
+		Code: "WAIP", Valid: true, Type: TypeReference,
+		Field: "address", MatchBy: "code", ExactMatch: true,
+		OrRules: []OrRule{{Field: "qth", MatchBy: "code"}},
+		Confirm: []string{"lotw"},
+	}
+	metas := []RefMeta{{Code: "BG", Name: "Bergamo", Valid: true}}
+	q := &qso.QSO{Callsign: "I2IFT", Band: "30m", QTH: "SERIATE (BG)", Address: "Seriate (Bg) 24068 Italy"}
+
+	ex := Explain(def, metas, q)
+	if !ex.InScope || len(ex.Steps) != 2 {
+		t.Fatalf("in scope=%v, %d steps, want in scope with 2 (primary + OR 1): %+v", ex.InScope, len(ex.Steps), ex)
+	}
+	// The primary rule LOOKS like it found something. Saying only "no match" here is
+	// what cost hours: the trace has to show the candidate and why it lost.
+	p := ex.Steps[0]
+	if len(p.Candidates) == 0 {
+		t.Error("primary produced no candidate; the whole point is that it produces a bogus one")
+	}
+	if len(p.Kept) != 0 || len(p.Rejected) == 0 {
+		t.Fatalf("primary kept=%v rejected=%v, want nothing kept and a stated reason", p.Kept, p.Rejected)
+	}
+	if !strings.Contains(p.Rejected[0].Reason, "not in the award's reference list") {
+		t.Errorf("reason = %q, want it to name the real cause", p.Rejected[0].Reason)
+	}
+	if or1 := ex.Steps[1]; or1.Skipped || len(or1.Kept) != 1 || or1.Kept[0] != "BG" {
+		t.Errorf("OR 1 = %+v, want it to run and find BG", or1)
+	}
+	if len(ex.Result) != 1 || ex.Result[0] != "BG" {
+		t.Errorf("result = %v, want [BG]", ex.Result)
+	}
+
+	// A trace that disagrees with the matcher is worse than none: it is believed.
+	if got := MatchQSO(def, metas, q); strings.Join(got, ",") != strings.Join(ex.Result, ",") {
+		t.Errorf("Explain says %v but MatchQSO says %v — the trace does not describe the code", ex.Result, got)
+	}
+}
+
+func TestExplainOutOfScopeSaysWhy(t *testing.T) {
+	def := Def{Code: "FFMA", Valid: true, Field: "grid4", MatchBy: "code", ExactMatch: true,
+		ValidBands: []string{"6m"}, ValidFrom: "1983-01-01", Confirm: []string{"lotw"}}
+	q := &qso.QSO{Callsign: "K1ABC", Band: "2m", Grid: "EM00AA",
+		QSODate: time.Date(1990, 1, 1, 0, 0, 0, 0, time.UTC)}
+
+	ex := Explain(def, []RefMeta{{Code: "EM00", Valid: true}}, q)
+	if ex.InScope {
+		t.Fatal("a 2 m QSO is not in scope for a 6 m-only award")
+	}
+	if !strings.Contains(ex.ScopeError, "2m") {
+		t.Errorf("scope error = %q, want it to name the band that fails", ex.ScopeError)
+	}
+	if len(ex.Steps) != 0 {
+		t.Errorf("%d steps ran on an out-of-scope QSO; none should", len(ex.Steps))
+	}
+}
+
 func refCodes(r Result) []string {
 	out := make([]string, 0, len(r.Refs))
 	for _, rf := range r.Refs {