[SYNTH-21264] Add assertions on synthetics tests. (#41271)

### What does this PR do?

Now that we have the result from datadog-traceroute available, we need to code the Assertions evaluation.

### Motivation

### Describe how you validated your changes

### Additional Notes

Author: Fabrice-Matrat

comp/syntheticstestscheduler/common/data.go

@@ -70,7 +70,7 @@ type SyntheticsTestConfig struct {
 	Type    string `json:"type"`
 
 	Config struct {
-		Assertions []interface{} `json:"assertions"`
+		Assertions []Assertion   `json:"assertions"`
 		Request    ConfigRequest `json:"request"`
 	} `json:"config"`
 
@@ -80,6 +80,58 @@ type SyntheticsTestConfig struct {
 	PublicID string `json:"publicID"`
 }
 
+// Operator represents a comparison operator for assertions.
+type Operator string
+
+const (
+	// OperatorIs checks equality.
+	OperatorIs Operator = "is"
+	// OperatorIsNot checks inequality.
+	OperatorIsNot Operator = "isNot"
+	// OperatorMoreThan checks if greater than target.
+	OperatorMoreThan Operator = "moreThan"
+	// OperatorMoreThanOrEquals checks if greater than or equal to target.
+	OperatorMoreThanOrEquals Operator = "moreThanOrEquals"
+	// OperatorLessThan checks if less than target.
+	OperatorLessThan Operator = "lessThan"
+	// OperatorLessThanOrEquals checks if less than or equal to target.
+	OperatorLessThanOrEquals Operator = "lessThanOrEquals"
+)
+
+// AssertionType represents the type of metric being asserted in a network test.
+type AssertionType string
+
+const (
+	// AssertionTypeNetworkHops represents a network hops assertion.
+	AssertionTypeNetworkHops AssertionType = "networkHops"
+	// AssertionTypeLatency represents a latency assertion.
+	AssertionTypeLatency AssertionType = "latency"
+	// AssertionTypePacketLoss represents a packet loss percentage assertion.
+	AssertionTypePacketLoss AssertionType = "packetLossPercentage"
+	// AssertionTypePacketJitter represents a packet jitter assertion.
+	AssertionTypePacketJitter AssertionType = "jitter"
+)
+
+// AssertionSubType represents the aggregation type for an assertion.
+type AssertionSubType string
+
+const (
+	// AssertionSubTypeAverage represents the average value of the metric.
+	AssertionSubTypeAverage AssertionSubType = "avg"
+	// AssertionSubTypeMin represents the minimum value of the metric.
+	AssertionSubTypeMin AssertionSubType = "min"
+	// AssertionSubTypeMax represents the maximum value of the metric.
+	AssertionSubTypeMax AssertionSubType = "max"
+)
+
+// Assertion represents a single condition to be checked in a network test.
+type Assertion struct {
+	Operator Operator         `json:"operator"`
+	Property AssertionSubType `json:"property"`
+	Target   string           `json:"target"`
+	Type     AssertionType    `json:"type"`
+}
+
 // UnmarshalJSON is a Custom unmarshal for SyntheticsTestConfig
 func (c *SyntheticsTestConfig) UnmarshalJSON(data []byte) error {
 	type rawConfig struct {
@@ -88,7 +140,7 @@ func (c *SyntheticsTestConfig) UnmarshalJSON(data []byte) error {
 		Subtype string `json:"subtype"`
 
 		Config struct {
-			Assertions []interface{}   `json:"assertions"`
+			Assertions []Assertion     `json:"assertions"`
 			Request    json.RawMessage `json:"request"`
 		} `json:"config"`
 

comp/syntheticstestscheduler/common/result.go

@@ -5,15 +5,88 @@
 
 package common
 
-import "github.com/DataDog/datadog-agent/pkg/networkpath/payload"
-
-// Assertion represents a validation check comparing expected and actual values.
-type Assertion struct {
-	Operator string      `json:"operator"`
-	Type     string      `json:"type"`
-	Expected interface{} `json:"expected"`
-	Actual   interface{} `json:"actual"`
-	Valid    bool        `json:"valid"`
+import (
+	"fmt"
+	"reflect"
+	"strconv"
+
+	"github.com/DataDog/datadog-agent/pkg/networkpath/payload"
+)
+
+// AssertionResult represents a validation check comparing expected and actual values.
+type AssertionResult struct {
+	Operator Operator         `json:"operator"`
+	Type     AssertionType    `json:"type"`
+	Property AssertionSubType `json:"property"`
+	Expected interface{}      `json:"expected"`
+	Actual   interface{}      `json:"actual"`
+	Valid    bool             `json:"valid"`
+	Failure  APIFailure       `json:"failure"`
+}
+
+// Compare evaluates the assertion result by comparing the actual and expected values.
+// Sets the Valid field based on the comparison and returns an error if parsing fails.
+func (a *AssertionResult) Compare() error {
+	// Special case: Is / IsNot
+	if a.Operator == OperatorIs || a.Operator == OperatorIsNot {
+		// Try numeric comparison first
+		expNum, expErr := parseToFloat(a.Expected)
+		actNum, actErr := parseToFloat(a.Actual)
+
+		if expErr == nil && actErr == nil {
+			// Both numeric → compare as numbers
+			a.Valid = (actNum == expNum)
+		} else {
+			// Otherwise → compare as raw values
+			a.Valid = reflect.DeepEqual(a.Actual, a.Expected)
+		}
+		if a.Operator == OperatorIsNot {
+			a.Valid = !a.Valid
+		}
+		return nil
+	}
+
+	// For numeric operators (<, <=, >, >=)
+	exp, err := parseToFloat(a.Expected)
+	if err != nil {
+		return fmt.Errorf("expected parse error: %w", err)
+	}
+	act, err := parseToFloat(a.Actual)
+	if err != nil {
+		return fmt.Errorf("actual parse error: %w", err)
+	}
+
+	switch a.Operator {
+	case OperatorLessThan:
+		a.Valid = act < exp
+	case OperatorLessThanOrEquals:
+		a.Valid = act <= exp
+	case OperatorMoreThan:
+		a.Valid = act > exp
+	case OperatorMoreThanOrEquals:
+		a.Valid = act >= exp
+	default:
+		return fmt.Errorf("unsupported operator %v", a.Operator)
+	}
+
+	return nil
+}
+
+func parseToFloat(v interface{}) (float64, error) {
+	switch x := v.(type) {
+	case string:
+		if i, err := strconv.ParseInt(x, 10, 64); err == nil {
+			return float64(i), nil
+		}
+		if f, err := strconv.ParseFloat(x, 64); err == nil {
+			return f, nil
+		}
+		return 0, fmt.Errorf("value must be numeric string, got: %q", x)
+	case int, int64, float32, float64:
+		return reflect.ValueOf(v).Convert(reflect.TypeOf(float64(0))).Float(), nil
+	default:
+		return 0, fmt.Errorf("unsupported type: %T", v)
+	}
 }
 
 // Request represents the network request.
@@ -41,7 +114,7 @@ type Result struct {
 	TestFinishedAt  int64               `json:"testFinishedAt"`
 	TestStartedAt   int64               `json:"testStartedAt"`
 	TestTriggeredAt int64               `json:"testTriggeredAt"`
-	Assertions      []Assertion         `json:"assertions"`
+	Assertions      []AssertionResult   `json:"assertions"`
 	Failure         ErrorOrFailure      `json:"failure"`
 	Duration        int64               `json:"duration"`
 	Request         Request             `json:"request"`
@@ -60,6 +133,9 @@ type Test struct {
 
 // TestResult represents the full test execution result including metadata.
 type TestResult struct {
+	Location struct {
+		ID string `json:"id"`
+	} `json:"location"`
 	DD     map[string]interface{} `json:"_dd"` // TestRequestInternalFields
 	Result Result                 `json:"result"`
 	Test   Test                   `json:"test"`

comp/syntheticstestscheduler/common/result_test.go

@@ -0,0 +1,87 @@
+// Unless explicitly stated otherwise all files in this repository are licensed
+// under the Apache License Version 2.0.
+// This product includes software developed at Datadog (https://www.datadoghq.com/).
+// Copyright 2025-present Datadog, Inc.
+
+package common
+
+import (
+	"testing"
+)
+
+func TestAssertionResult_Compare(t *testing.T) {
+	tests := map[Operator][]struct {
+		name     string
+		expected interface{}
+		actual   interface{}
+		want     bool
+		wantErr  bool
+	}{
+		OperatorLessThan: {
+			{"actual less", 10, 5, true, false},
+			{"actual equal", 10, 10, false, false},
+			{"actual more", 10, 20, false, false},
+		},
+		OperatorLessThanOrEquals: {
+			{"less is true", 10, 5, true, false},
+			{"equal is true", 10, 10, true, false},
+			{"more is false", 10, 20, false, false},
+		},
+		OperatorMoreThan: {
+			{"more is true", 10, 20, true, false},
+			{"equal is false", 10, 10, false, false},
+			{"less is false", 10, 5, false, false},
+		},
+		OperatorMoreThanOrEquals: {
+			{"more is true", 10, 20, true, false},
+			{"equal is true", 10, 10, true, false},
+			{"less is false", 10, 5, false, false},
+			{"float equal", 5.5, 5.5, true, false},
+		},
+		OperatorIs: {
+			{"equal ints", "10", "10", true, false},
+			{"not equal", "10", "20", false, false},
+			{"equal numeric different format", "100.0", "100", true, false},
+			{"string equal", "foo", "foo", true, false},
+			{"string not equal", "foo", "bar", false, false},
+		},
+		OperatorIsNot: {
+			{"not equal", 10, 20, true, false},
+			{"equal", 10, 10, false, false},
+		},
+	}
+
+	for op, cases := range tests {
+		t.Run(string(op), func(t *testing.T) {
+			for _, tt := range cases {
+				t.Run(tt.name, func(t *testing.T) {
+					ar := &AssertionResult{
+						Operator: op,
+						Expected: tt.expected,
+						Actual:   tt.actual,
+					}
+					err := ar.Compare()
+					if (err != nil) != tt.wantErr {
+						t.Fatalf("Compare() error = %v, wantErr %v", err, tt.wantErr)
+					}
+					if !tt.wantErr && ar.Valid != tt.want {
+						t.Errorf("Compare() got Valid = %v, want %v", ar.Valid, tt.want)
+					}
+				})
+			}
+		})
+	}
+
+	// Explicit test for unsupported operator
+	t.Run("unsupported operator", func(t *testing.T) {
+		ar := &AssertionResult{
+			Operator: "invalidOperator",
+			Expected: 10,
+			Actual:   10,
+		}
+		err := ar.Compare()
+		if err == nil {
+			t.Fatalf("expected error for unsupported operator")
+		}
+	})
+}

comp/syntheticstestscheduler/impl/assertions.go

@@ -0,0 +1,103 @@
+// Unless explicitly stated otherwise all files in this repository are licensed
+// under the Apache License Version 2.0.
+// This product includes software developed at Datadog (https://www.datadoghq.com/).
+// Copyright 2025-present Datadog, Inc.
+
+package syntheticstestschedulerimpl
+
+import (
+	"fmt"
+
+	"github.com/DataDog/datadog-agent/comp/syntheticstestscheduler/common"
+)
+
+const (
+	incorrectAssertion = "INCORRECT_ASSERTION"
+	invalidTest        = "INVALID_TEST"
+)
+
+func runAssertions(cfg common.SyntheticsTestConfig, result common.NetStats) []common.AssertionResult {
+	assertions := make([]common.AssertionResult, 0)
+	for _, assertion := range cfg.Config.Assertions {
+		assertions = append(assertions, runAssertion(assertion, result))
+	}
+	return assertions
+}
+
+func runAssertion(assertion common.Assertion, stats common.NetStats) common.AssertionResult {
+	var actual float64
+
+	switch assertion.Type {
+	case common.AssertionTypePacketLoss:
+		actual = float64(stats.PacketLossPercentage)
+	case common.AssertionTypePacketJitter:
+		actual = stats.Jitter
+	case common.AssertionTypeLatency:
+		switch assertion.Property {
+		case common.AssertionSubTypeAverage:
+			actual = stats.Latency.Avg
+		case common.AssertionSubTypeMin:
+			actual = stats.Latency.Min
+		case common.AssertionSubTypeMax:
+			actual = stats.Latency.Max
+		default:
+			return common.AssertionResult{
+				Operator: assertion.Operator,
+				Type:     assertion.Type,
+				Property: assertion.Property,
+				Expected: assertion.Target,
+				Failure: common.APIFailure{
+					Code:    invalidTest,
+					Message: fmt.Sprintf("unsupported field: %s.%s", assertion.Type, assertion.Property),
+				},
+			}
+		}
+	case common.AssertionTypeNetworkHops:
+		switch assertion.Property {
+		case common.AssertionSubTypeAverage:
+			actual = stats.Hops.Avg
+		case common.AssertionSubTypeMin:
+			actual = float64(stats.Hops.Min)
+		case common.AssertionSubTypeMax:
+			actual = float64(stats.Hops.Max)
+		default:
+			return common.AssertionResult{
+				Operator: assertion.Operator,
+				Type:     assertion.Type,
+				Property: assertion.Property,
+				Expected: assertion.Target,
+				Failure: common.APIFailure{
+					Code:    invalidTest,
+					Message: fmt.Sprintf("unsupported field: %s.%s", assertion.Type, assertion.Property),
+				},
+			}
+		}
+	default:
+		return common.AssertionResult{
+			Operator: assertion.Operator,
+			Type:     assertion.Type,
+			Property: assertion.Property,
+			Expected: assertion.Target,
+			Failure: common.APIFailure{
+				Code:    invalidTest,
+				Message: fmt.Sprintf("unsupported field: %s", assertion.Type),
+			},
+		}
+	}
+
+	assertionResult := common.AssertionResult{
+		Operator: assertion.Operator,
+		Type:     assertion.Type,
+		Property: assertion.Property,
+		Expected: assertion.Target,
+		Actual:   actual,
+	}
+	if err := assertionResult.Compare(); err != nil {
+		assertionResult.Failure = common.APIFailure{
+			Code:    incorrectAssertion,
+			Message: err.Error(),
+		}
+		return assertionResult
+	}
+	return assertionResult
+}