ESQL: Updated ToIp tests and generated documentation for map parameters

x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/TestCaseSupplier.java

@@ -1682,9 +1682,17 @@ public static String castToDoubleEvaluator(String original, DataType current) {
     public static List<TestCaseSupplier> mapTestCases(
         Collection<TestCaseSupplier> suppliers,
         Function<TestCaseSupplier.TestCase, TestCaseSupplier.TestCase> mapper
+    ) {
+        return mapTestCases(suppliers, mapper, TestCaseSupplier::types);
+    }
+
+    public static List<TestCaseSupplier> mapTestCases(
+        Collection<TestCaseSupplier> suppliers,
+        Function<TestCaseSupplier.TestCase, TestCaseSupplier.TestCase> mapper,
+        Function<TestCaseSupplier, List<DataType>> typesMapper
     ) {
         return suppliers.stream()
-            .map(supplier -> new TestCaseSupplier(supplier.name(), supplier.types(), () -> mapper.apply(supplier.get())))
+            .map(supplier -> new TestCaseSupplier(supplier.name(), typesMapper.apply(supplier), () -> mapper.apply(supplier.get())))
             .collect(Collectors.toCollection(ArrayList::new));
     }
 

x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToIpErrorTests.java

@@ -7,7 +7,6 @@
 
 package org.elasticsearch.xpack.esql.expression.function.scalar.convert;
 
-import org.elasticsearch.common.collect.Iterators;
 import org.elasticsearch.xpack.esql.core.expression.Expression;
 import org.elasticsearch.xpack.esql.core.tree.Source;
 import org.elasticsearch.xpack.esql.core.type.DataType;
@@ -17,13 +16,14 @@
 
 import java.util.List;
 import java.util.Set;
+import java.util.stream.Stream;
 
 import static org.hamcrest.Matchers.equalTo;
 
 public class ToIpErrorTests extends ErrorsForCasesWithoutExamplesTestCase {
     @Override
     protected List<TestCaseSupplier> cases() {
-        return Iterators.toList(Iterators.map(ToIpTests.parameters().iterator(), p -> (TestCaseSupplier) p[0]));
+        return paramsToSuppliers(ToIpTests.parameters());
     }
 
     @Override
@@ -35,4 +35,10 @@ protected Expression build(Source source, List<Expression> args) {
     protected Matcher<String> expectedTypeErrorMatcher(List<Set<DataType>> validPerPosition, List<DataType> signature) {
         return equalTo(typeErrorMessage(false, validPerPosition, signature, (v, p) -> "ip or string"));
     }
+
+    @Override
+    protected Stream<List<DataType>> testCandidates(List<TestCaseSupplier> cases, Set<List<DataType>> valid) {
+        // Don't test options types, as options are not checked by type. See Options.resolve()
+        return super.testCandidates(cases, valid).filter(sig -> sig.size() == 1 || sig.get(1) == DataType.UNSUPPORTED);
+    }
 }

x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToIpTests.java

@@ -36,19 +36,13 @@
 import static org.hamcrest.Matchers.nullValue;
 
 public class ToIpTests extends AbstractScalarFunctionTestCase {
-    private final ToIp.LeadingZeros leadingZeros;
-
-    public ToIpTests(
-        @Name("TestCase") Supplier<TestCaseSupplier.TestCase> testCaseSupplier,
-        @Name("leading_zeros") ToIp.LeadingZeros leadingZeros
-    ) {
+    public ToIpTests(@Name("TestCase") Supplier<TestCaseSupplier.TestCase> testCaseSupplier) {
         this.testCase = testCaseSupplier.get();
-        this.leadingZeros = leadingZeros;
     }
 
     @ParametersFactory
     public static Iterable<Object[]> parameters() {
-        List<Object[]> parameters = new ArrayList<>();
+        List<TestCaseSupplier> allSuppliers = new ArrayList<>();
         for (ToIp.LeadingZeros leadingZeros : new ToIp.LeadingZeros[] { null, REJECT, OCTAL, DECIMAL }) {
             List<TestCaseSupplier> suppliers = new ArrayList<>();
             // convert from IP to IP
@@ -75,41 +69,65 @@ public static Iterable<Object[]> parameters() {
                 bytesRef -> parseIP(((BytesRef) bytesRef).utf8ToString()),
                 emptyList()
             );
-            suppliers = anyNullIsNull(true, randomizeBytesRefsOffset(suppliers));
-            for (TestCaseSupplier supplier : suppliers) {
-                parameters.add(new Object[] { supplier, leadingZeros });
+
+            // Inject the options param
+            if (leadingZeros != null) {
+                suppliers = TestCaseSupplier.mapTestCases(
+                    suppliers,
+                    tc -> tc.withData(List.of(tc.getData().getFirst(), options(leadingZeros))),
+                    supplier -> List.of(supplier.types().getFirst(), DataType.UNSUPPORTED)
+                );
             }
+
+            // Add nulls cases, only for the first parameter
+            suppliers.add(
+                new TestCaseSupplier(
+                    leadingZeros != null ? List.of(DataType.NULL, DataType.UNSUPPORTED) : List.of(DataType.NULL),
+                    () -> new TestCaseSupplier.TestCase(
+                        leadingZeros != null
+                            ? List.of(TestCaseSupplier.TypedData.NULL, options(leadingZeros))
+                            : List.of(TestCaseSupplier.TypedData.NULL),
+                        "LiteralsEvaluator[lit=null]",
+                        DataType.IP,
+                        nullValue()
+                    )
+                )
+            );
+
+            allSuppliers.addAll(suppliers);
         }
 
-        parameters.add(new Object[] { exampleRejectingLeadingZeros(stringEvaluator(null)), null });
-        parameters.add(new Object[] { exampleRejectingLeadingZeros(stringEvaluator(REJECT)), REJECT });
-        parameters.add(new Object[] { exampleParsingLeadingZerosAsDecimal(stringEvaluator(DECIMAL)), DECIMAL });
-        parameters.add(new Object[] { exampleParsingLeadingZerosAsOctal(stringEvaluator(OCTAL)), OCTAL });
-        return parameters;
+        allSuppliers.add(exampleRejectingLeadingZeros(stringEvaluator(null), true));
+        allSuppliers.add(exampleRejectingLeadingZeros(stringEvaluator(REJECT), false));
+        allSuppliers.add(exampleParsingLeadingZerosAsDecimal(stringEvaluator(DECIMAL)));
+        allSuppliers.add(exampleParsingLeadingZerosAsOctal(stringEvaluator(OCTAL)));
+
+        return parameterSuppliersFromTypedData(randomizeBytesRefsOffset(allSuppliers));
     }
 
-    private static TestCaseSupplier exampleRejectingLeadingZeros(String stringEvaluator) {
-        return new TestCaseSupplier("<ip> with leading 0s", List.of(DataType.KEYWORD), () -> {
+    private static TestCaseSupplier exampleRejectingLeadingZeros(String stringEvaluator, boolean useDefault) {
+        List<DataType> inputTypes = useDefault ? List.of(DataType.KEYWORD) : List.of(DataType.KEYWORD, DataType.UNSUPPORTED);
+        return new TestCaseSupplier("<ip> with leading 0s", inputTypes, () -> {
             BytesRef withLeadingZeros = new BytesRef(randomIpWithLeadingZeros());
-            return new TestCaseSupplier.TestCase(
-                List.of(new TestCaseSupplier.TypedData(withLeadingZeros, DataType.KEYWORD, "ip")),
-                stringEvaluator,
-                DataType.IP,
-                nullValue()
-            ).withWarning("Line 1:1: evaluation of [source] failed, treating result as null. Only first 20 failures recorded.")
+            List<TestCaseSupplier.TypedData> data = useDefault
+                ? List.of(new TestCaseSupplier.TypedData(withLeadingZeros, DataType.KEYWORD, "ip"))
+                : List.of(new TestCaseSupplier.TypedData(withLeadingZeros, DataType.KEYWORD, "ip"), options(REJECT));
+            return new TestCaseSupplier.TestCase(data, stringEvaluator, DataType.IP, nullValue()).withWarning(
+                "Line 1:1: evaluation of [source] failed, treating result as null. Only first 20 failures recorded."
+            )
                 .withWarning(
                     "Line 1:1: java.lang.IllegalArgumentException: '" + withLeadingZeros.utf8ToString() + "' is not an IP string literal."
                 );
         });
     }
 
     private static TestCaseSupplier exampleParsingLeadingZerosAsDecimal(String stringEvaluator) {
-        return new TestCaseSupplier("<ip> with leading 0s", List.of(DataType.KEYWORD), () -> {
+        return new TestCaseSupplier("<ip> with leading 0s", List.of(DataType.KEYWORD, DataType.UNSUPPORTED), () -> {
             String ip = randomIpWithLeadingZeros();
             BytesRef withLeadingZeros = new BytesRef(ip);
             String withoutLeadingZeros = ParseIpTests.leadingZerosAreDecimalToIp(ip);
             return new TestCaseSupplier.TestCase(
-                List.of(new TestCaseSupplier.TypedData(withLeadingZeros, DataType.KEYWORD, "ip")),
+                List.of(new TestCaseSupplier.TypedData(withLeadingZeros, DataType.KEYWORD, "ip"), options(DECIMAL)),
                 stringEvaluator,
                 DataType.IP,
                 equalTo(EsqlDataTypeConverter.stringToIP(withoutLeadingZeros))
@@ -118,12 +136,12 @@ private static TestCaseSupplier exampleParsingLeadingZerosAsDecimal(String strin
     }
 
     private static TestCaseSupplier exampleParsingLeadingZerosAsOctal(String stringEvaluator) {
-        return new TestCaseSupplier("<ip> with leading 0s", List.of(DataType.KEYWORD), () -> {
+        return new TestCaseSupplier("<ip> with leading 0s", List.of(DataType.KEYWORD, DataType.UNSUPPORTED), () -> {
             String ip = randomIpWithLeadingZerosOctal();
             BytesRef withLeadingZeros = new BytesRef(ip);
             String withoutLeadingZeros = ParseIpTests.leadingZerosAreOctalToIp(ip);
             return new TestCaseSupplier.TestCase(
-                List.of(new TestCaseSupplier.TypedData(withLeadingZeros, DataType.KEYWORD, "ip")),
+                List.of(new TestCaseSupplier.TypedData(withLeadingZeros, DataType.KEYWORD, "ip"), options(OCTAL)),
                 stringEvaluator,
                 DataType.IP,
                 equalTo(EsqlDataTypeConverter.stringToIP(withoutLeadingZeros))
@@ -133,20 +151,21 @@ private static TestCaseSupplier exampleParsingLeadingZerosAsOctal(String stringE
 
     @Override
     protected Expression build(Source source, List<Expression> args) {
-        return new ToIp(source, args.getFirst(), options());
+        return new ToIp(source, args.getFirst(), args.size() == 2 ? args.get(1) : null);
     }
 
-    private MapExpression options() {
-        if (leadingZeros == null) {
-            return null;
-        }
-        return new MapExpression(
-            Source.EMPTY,
-            List.of(
-                Literal.keyword(Source.EMPTY, "leading_zeros"),
-                Literal.keyword(Source.EMPTY, leadingZeros.toString().toLowerCase(Locale.ROOT))
-            )
-        );
+    private static TestCaseSupplier.TypedData options(ToIp.LeadingZeros leadingZeros) {
+        return new TestCaseSupplier.TypedData(
+            new MapExpression(
+                Source.EMPTY,
+                List.of(
+                    Literal.keyword(Source.EMPTY, "leading_zeros"),
+                    Literal.keyword(Source.EMPTY, leadingZeros.toString().toLowerCase(Locale.ROOT))
+                )
+            ),
+            DataType.UNSUPPORTED,
+            "options"
+        ).forceLiteral();
     }
 
     private static List<TestCaseSupplier.TypedDataSupplier> validIPsAsStrings() {