Add $first accumulator tests

documentdb_tests/compatibility/tests/core/operator/accumulators/first/test_accumulator_first_errors.py

@@ -0,0 +1,117 @@
+"""Tests for $first accumulator error cases: arity rejection and expression error propagation."""
+
+from __future__ import annotations
+
+import pytest
+
+from documentdb_tests.compatibility.tests.core.operator.accumulators.utils import (
+    AccumulatorTestCase,
+)
+from documentdb_tests.framework.assertions import assertFailureCode
+from documentdb_tests.framework.error_codes import (
+    CONVERSION_FAILURE_ERROR,
+    DIVIDE_BY_ZERO_V2_ERROR,
+    EXPRESSION_OBJECT_MULTIPLE_FIELDS_ERROR,
+    GROUP_ACCUMULATOR_ARRAY_ARGUMENT_ERROR,
+)
+from documentdb_tests.framework.executor import execute_command
+from documentdb_tests.framework.parametrize import pytest_params
+
+# Property [Arity]: $first in accumulator context is a unary operator and
+# rejects array syntax.
+FIRST_ARITY_ERROR_TESTS: list[AccumulatorTestCase] = [
+    AccumulatorTestCase(
+        "arity_empty_array",
+        docs=[{"v": 1}],
+        pipeline=[
+            {"$group": {"_id": None, "result": {"$first": []}}},
+            {"$project": {"_id": 0, "result": 1}},
+        ],
+        error_code=GROUP_ACCUMULATOR_ARRAY_ARGUMENT_ERROR,
+        msg="$first should reject empty array in accumulator context",
+    ),
+    AccumulatorTestCase(
+        "arity_single_element_array",
+        docs=[{"v": 1}],
+        pipeline=[
+            {"$group": {"_id": None, "result": {"$first": [1]}}},
+            {"$project": {"_id": 0, "result": 1}},
+        ],
+        error_code=GROUP_ACCUMULATOR_ARRAY_ARGUMENT_ERROR,
+        msg="$first should reject single-element literal array in accumulator context",
+    ),
+    AccumulatorTestCase(
+        "arity_single_field_ref_array",
+        docs=[{"v": 1}],
+        pipeline=[
+            {"$group": {"_id": None, "result": {"$first": ["$v"]}}},
+            {"$project": {"_id": 0, "result": 1}},
+        ],
+        error_code=GROUP_ACCUMULATOR_ARRAY_ARGUMENT_ERROR,
+        msg="$first should reject single field ref in array in accumulator context",
+    ),
+    AccumulatorTestCase(
+        "arity_multi_element_array",
+        docs=[{"v": 1}],
+        pipeline=[
+            {"$group": {"_id": None, "result": {"$first": [1, 2, 3]}}},
+            {"$project": {"_id": 0, "result": 1}},
+        ],
+        error_code=GROUP_ACCUMULATOR_ARRAY_ARGUMENT_ERROR,
+        msg="$first should reject multi-element array in accumulator context",
+    ),
+    AccumulatorTestCase(
+        "arity_multi_key_expression_object",
+        docs=[{"v": 1}],
+        pipeline=[
+            {
+                "$group": {
+                    "_id": None,
+                    "result": {"$first": {"$add": [1, 2], "$multiply": [3, 4]}},
+                }
+            },
+            {"$project": {"_id": 0, "result": 1}},
+        ],
+        error_code=EXPRESSION_OBJECT_MULTIPLE_FIELDS_ERROR,
+        msg="$first should reject multi-key expression object",
+    ),
+]
+
+# Property [Expression Error Propagation]: errors raised during sub-expression
+# evaluation propagate through the accumulator without being caught.
+FIRST_EXPRESSION_ERROR_TESTS: list[AccumulatorTestCase] = [
+    AccumulatorTestCase(
+        "expr_error_divide_by_zero",
+        docs=[{"v": 1}],
+        pipeline=[
+            {"$group": {"_id": None, "result": {"$first": {"$divide": ["$v", 0]}}}},
+            {"$project": {"_id": 0, "result": 1}},
+        ],
+        error_code=DIVIDE_BY_ZERO_V2_ERROR,
+        msg="$first should propagate $divide by zero error",
+    ),
+    AccumulatorTestCase(
+        "expr_error_to_int_invalid_string",
+        docs=[{"v": "abc"}],
+        pipeline=[
+            {"$group": {"_id": None, "result": {"$first": {"$toInt": "$v"}}}},
+            {"$project": {"_id": 0, "result": 1}},
+        ],
+        error_code=CONVERSION_FAILURE_ERROR,
+        msg="$first should propagate $toInt conversion error from expression",
+    ),
+]
+
+FIRST_ERROR_TESTS = FIRST_ARITY_ERROR_TESTS + FIRST_EXPRESSION_ERROR_TESTS
+
+
+@pytest.mark.parametrize("test_case", pytest_params(FIRST_ERROR_TESTS))
+def test_accumulator_first_errors(collection, test_case):
+    """Test $first accumulator error cases."""
+    if test_case.docs:
+        collection.insert_many(test_case.docs)
+    result = execute_command(
+        collection,
+        {"aggregate": collection.name, "pipeline": test_case.pipeline, "cursor": {}},
+    )
+    assertFailureCode(result, test_case.error_code, msg=test_case.msg)

documentdb_tests/compatibility/tests/core/operator/accumulators/first/test_accumulator_first_null_missing.py

@@ -0,0 +1,139 @@
+"""Tests for $first accumulator null, missing, and edge case behavior."""
+
+from __future__ import annotations
+
+import pytest
+
+from documentdb_tests.compatibility.tests.core.operator.accumulators.utils import (
+    AccumulatorTestCase,
+)
+from documentdb_tests.framework.assertions import assertSuccess
+from documentdb_tests.framework.executor import execute_command
+from documentdb_tests.framework.parametrize import pytest_params
+
+# Property [Null and Missing NOT Excluded]: $first returns whatever the
+# first document has, including null and missing values.
+FIRST_NULL_MISSING_TESTS: list[AccumulatorTestCase] = [
+    AccumulatorTestCase(
+        "null_first_then_value",
+        docs=[{"v": None}, {"v": 5}],
+        pipeline=[{"$group": {"_id": None, "result": {"$first": "$v"}}}],
+        expected=[{"_id": None, "result": None}],
+        msg="$first should return null when first doc has null (first wins)",
+    ),
+    AccumulatorTestCase(
+        "null_missing_first_then_value",
+        docs=[{"x": 1}, {"v": 5}],
+        pipeline=[{"$group": {"_id": None, "result": {"$first": "$v"}}}],
+        expected=[{"_id": None, "result": None}],
+        msg="$first should return null when first doc has missing field",
+    ),
+    AccumulatorTestCase(
+        "null_value_first_then_null",
+        docs=[{"v": 5}, {"v": None}],
+        pipeline=[{"$group": {"_id": None, "result": {"$first": "$v"}}}],
+        expected=[{"_id": None, "result": 5}],
+        msg="$first should return 5 when first doc has value, second is null",
+    ),
+    AccumulatorTestCase(
+        "null_value_first_then_missing",
+        docs=[{"v": 5}, {"x": 1}],
+        pipeline=[{"$group": {"_id": None, "result": {"$first": "$v"}}}],
+        expected=[{"_id": None, "result": 5}],
+        msg="$first should return 5 when first doc has value, second is missing",
+    ),
+    AccumulatorTestCase(
+        "null_all",
+        docs=[{"v": None}, {"v": None}],
+        pipeline=[{"$group": {"_id": None, "result": {"$first": "$v"}}}],
+        expected=[{"_id": None, "result": None}],
+        msg="$first should return null when all docs have null",
+    ),
+    AccumulatorTestCase(
+        "null_missing_all",
+        docs=[{"x": 1}, {"x": 2}],
+        pipeline=[{"$group": {"_id": None, "result": {"$first": "$v"}}}],
+        expected=[{"_id": None, "result": None}],
+        msg="$first should return null when all docs have missing field",
+    ),
+    AccumulatorTestCase(
+        "null_and_missing_mixed",
+        docs=[{"v": None}, {"x": 1}],
+        pipeline=[{"$group": {"_id": None, "result": {"$first": "$v"}}}],
+        expected=[{"_id": None, "result": None}],
+        msg="$first should return null when first is null and second is missing",
+    ),
+]
+
+# Property [Edge Cases]: edge cases unique to the accumulator context.
+FIRST_EDGE_CASE_TESTS: list[AccumulatorTestCase] = [
+    AccumulatorTestCase(
+        "edge_single_doc",
+        docs=[{"v": 42}],
+        pipeline=[{"$group": {"_id": None, "result": {"$first": "$v"}}}],
+        expected=[{"_id": None, "result": 42}],
+        msg="$first of a single document should return that document's value",
+    ),
+    AccumulatorTestCase(
+        "edge_single_null_doc",
+        docs=[{"v": None}],
+        pipeline=[{"$group": {"_id": None, "result": {"$first": "$v"}}}],
+        expected=[{"_id": None, "result": None}],
+        msg="$first of a single null document should return null",
+    ),
+    AccumulatorTestCase(
+        "edge_single_missing_doc",
+        docs=[{"x": 1}],
+        pipeline=[{"$group": {"_id": None, "result": {"$first": "$v"}}}],
+        expected=[{"_id": None, "result": None}],
+        msg="$first of a single document with missing field should return null",
+    ),
+    AccumulatorTestCase(
+        "edge_array_not_traversed",
+        docs=[{"v": [5, 1, 8]}, {"v": [3, 9, 2]}],
+        pipeline=[{"$group": {"_id": None, "result": {"$first": "$v"}}}],
+        expected=[{"_id": None, "result": [5, 1, 8]}],
+        msg="$first should return array as whole value, not traverse it",
+    ),
+    AccumulatorTestCase(
+        "edge_empty_collection",
+        docs=[],
+        pipeline=[{"$group": {"_id": None, "result": {"$first": "$v"}}}],
+        expected=[],
+        msg="$first on empty collection should produce no groups (empty result)",
+    ),
+    AccumulatorTestCase(
+        "edge_order_dependent_asc",
+        docs=[{"v": 3}, {"v": 1}, {"v": 5}, {"v": 2}, {"v": 4}],
+        pipeline=[
+            {"$sort": {"v": 1}},
+            {"$group": {"_id": None, "result": {"$first": "$v"}}},
+        ],
+        expected=[{"_id": None, "result": 1}],
+        msg="$first with ascending sort should return smallest value",
+    ),
+    AccumulatorTestCase(
+        "edge_order_dependent_desc",
+        docs=[{"v": 3}, {"v": 1}, {"v": 5}, {"v": 2}, {"v": 4}],
+        pipeline=[
+            {"$sort": {"v": -1}},
+            {"$group": {"_id": None, "result": {"$first": "$v"}}},
+        ],
+        expected=[{"_id": None, "result": 5}],
+        msg="$first with descending sort should return largest value",
+    ),
+]
+
+FIRST_SUCCESS_TESTS = FIRST_NULL_MISSING_TESTS + FIRST_EDGE_CASE_TESTS
+
+
+@pytest.mark.parametrize("test_case", pytest_params(FIRST_SUCCESS_TESTS))
+def test_accumulator_first_null_missing(collection, test_case: AccumulatorTestCase):
+    """Test $first accumulator null, missing, and edge case behavior."""
+    if test_case.docs:
+        collection.insert_many(test_case.docs)
+    result = execute_command(
+        collection,
+        {"aggregate": collection.name, "pipeline": test_case.pipeline, "cursor": {}},
+    )
+    assertSuccess(result, test_case.expected, msg=test_case.msg)