You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@flink.apache.org by "autophagy (via GitHub)" <gi...@apache.org> on 2026/04/14 14:02:18 UTC

[PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

autophagy opened a new pull request, #27928:
URL: https://github.com/apache/flink/pull/27928

   <!--
   *Thank you very much for contributing to Apache Flink - we are happy that you want to help us improve Flink. To help the community review your contribution in the best possible way, please go through the checklist below, which will get the contribution into a shape in which it can be best reviewed.*
   
   *Please understand that we do not do this to make contributions to Flink a hassle. In order to uphold a high standard of quality for code contributions, while at the same time managing a large number of contributions, we need contributors to prepare the contributions well, and give reviewers enough contextual information for the review. Please also understand that contributions that do not follow this guide will take longer to review and thus typically be picked up with lower priority by the community.*
   
   ## Contribution Checklist
   
     - Make sure that the pull request corresponds to a [JIRA issue](https://issues.apache.org/jira/projects/FLINK/issues). Exceptions are made for typos in JavaDoc or documentation files, which need no JIRA issue.
     
     - Name the pull request in the form "[FLINK-XXXX] [component] Title of the pull request", where *FLINK-XXXX* should be replaced by the actual issue number. Skip *component* if you are unsure about which is the best component.
     Typo fixes that have no associated JIRA issue should be named following this pattern: `[hotfix] [docs] Fix typo in event time introduction` or `[hotfix] [javadocs] Expand JavaDoc for PuncuatedWatermarkGenerator`.
   
     - Fill out the template below to describe the changes contributed by the pull request. That will give reviewers the context they need to do the review.
     
     - Make sure that the change passes the automated tests, i.e., `mvn clean verify` passes. You can set up Azure Pipelines CI to do that following [this guide](https://cwiki.apache.org/confluence/display/FLINK/Azure+Pipelines#AzurePipelines-Tutorial:SettingupAzurePipelinesforaforkoftheFlinkrepository).
   
     - Each pull request should address only one issue, not mix up code from multiple issues.
     
     - Each commit in the pull request has a meaningful commit message (including the JIRA id)
   
     - Once all items of the checklist are addressed, remove the above text and this checklist, leaving only the filled out template below.
   
   
   **(The sections below can be removed for hotfixes of typos)**
   -->
   
   ## What is the purpose of the change
   
   This change introduces an initial implementation of a test harness for PTFs, according to [FLIP-567](https://cwiki.apache.org/confluence/display/FLINK/FLIP-567%3A+Introduce+a+ProcessTableFunction+Test+Harness), for use in unit tests that do not require a running Flink cluster.
   
   At a basic level, the harness allows users to set up test conditions with a builder API, which on build performs both test and PTF validation, and provides an auto-closable harness (that manages open/close). With this harness, users are able to pipe input rows into their PTF, and observe the collected output.
   
   It currently supports:
   
     - Row-semantic tables (ROW_SEMANTIC_TABLE)
     - Set-semantic tables (SET_SEMANTIC_TABLE) with partition-by configuration
     - Scalar arguments (including scalar-only PTFs via invoke())
     - Multi-table PTFs with per-table element routing
     - Inline type annotations via @ArgumentHint(type = ...)
     - Supports PTFs that use Rows and structured types as their input and output types.
     - `PASS_COLUMNS_THROUGH ` and `OPTIONAL_PARTITION_BY` argument traits.
   
   The harness currently *does not support* the following, which will be added in subsequent PRs:
   
   - State with @StateHint
   - Timers (and the use of Context in general)
   - Update traits like `SUPPORTS_UPDATES`, `REQUIRE_UPDATE_BEFORE`
   
   The missing feature set has been documented, along with some quickstart examples.
   
   ## Brief change log
   
   *(for example:)*
     - *Added `ProcessTableFunctionTestHarness`
     - Added tests to validate behaviour of PTF test harness
     - Added initial user facing documentation
   
   
   ## Verifying this change
   
   This change added tests and can be verified as follows:
   
   - Added behaviour tests via `ProcessTableFunctionTestHarnessTest`.
   - 
   ## Does this pull request potentially affect one of the following parts:
   
     - Dependencies (does it add or upgrade a dependency): (no)
     - The public API, i.e., is any changed class annotated with `@Public(Evolving)`: (yes)
     - The serializers: (no)
     - The runtime per-record code paths (performance sensitive): (no)
     - Anything that affects deployment or recovery: JobManager (and its components), Checkpointing, Kubernetes/Yarn, ZooKeeper: (yes / no / don't know)
     - The S3 file system connector: (no)
   
   ## Documentation
   
     - Does this pull request introduce a new feature? (yes)
     - If yes, how is the feature documented? (docs / JavaDocs)
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "autophagy (via GitHub)" <gi...@apache.org>.
autophagy commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3219906108


##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            LogicalType logicalType = dataType.getLogicalType();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                int index = 0;
+                for (RowType.RowField field : rowType.getFields()) {
+                    if (field.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                int index = 0;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    if (attr.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a table argument without an explicit schema.
+         *
+         * <p>Use this for structured type arguments where the type can be inferred from the PTF's
+         * eval() signature. For Row arguments, use {@link #withTableArgument(String,
+         * AbstractDataType)} with an explicit schema.
+         *
+         * @param argumentName The table argument name
+         */
+        public Builder<OUT> withTableArgument(String argumentName) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName) || tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException("Argument already configured: " + argumentName);
+            }
+
+            ScalarArgumentConfiguration config = new ScalarArgumentConfiguration(value);
+            scalarArgs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Partitioning
+        // ---------------------------------------------------------------------
+
+        /**
+         * Specifies partition columns for a set semantic table.
+         *
+         * @param argumentName The table argument name
+         * @param columnNames The partition column names
+         * @return This builder
+         */
+        public Builder<OUT> withPartitionBy(String argumentName, String... columnNames) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(columnNames, "columnNames must not be null");
+            checkArgument(columnNames.length > 0, "Must specify at least one column");
+
+            if (partitionConfigs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Partition config already exists for: " + argumentName);
+            }
+
+            PartitionConfiguration config = new PartitionConfiguration(columnNames);
+            partitionConfigs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Build
+        // ---------------------------------------------------------------------
+
+        /**
+         * Builds the test harness.
+         *
+         * <p>This instantiates the PTF, validates configuration via type inference, creates the
+         * FunctionContext, and opens the function.
+         *
+         * @return The configured test harness
+         * @throws Exception If instantiation or opening fails
+         */
+        public ProcessTableFunctionTestHarness<OUT> build() throws Exception {
+            ProcessTableFunction<OUT> function = instantiateFunction();
+
+            List<ArgumentInfo> arguments = extractAndValidateTypeInference(function);
+
+            FunctionContext functionContext =
+                    new FunctionContext(null, Thread.currentThread().getContextClassLoader(), null);
+
+            Method evalMethod = findEvalMethod();
+
+            validateEvalMethodSupported(evalMethod, arguments);
+            validatePartitionConsistency(arguments);
+
+            // In cases where PTFs have only a single table argument, set it as a default
+            // and mark as a single table function so that processElement without specifying
+            // a table argument can be used.
+            String defaultTableArg = null;
+            boolean isSingleTableFunction = false;
+
+            List<ArgumentInfo> tableArguments = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    tableArguments.add(arg);
+                }
+            }
+
+            if (tableArguments.size() == 1) {
+                defaultTableArg = tableArguments.get(0).name;
+                isSingleTableFunction = true;
+            }
+
+            Map<String, DataStructureConverter<Object, Object>> inputConverters = new HashMap<>();
+            Map<String, DataStructureConverter<Object, Object>> outputConverters = new HashMap<>();
+            createConverters(arguments, inputConverters, outputConverters);
+
+            Map<String, ArgumentInfo> argumentsByName = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    argumentsByName.put(arg.name, arg);
+                }
+            }
+
+            return new ProcessTableFunctionTestHarness<>(
+                    function,
+                    functionContext,
+                    defaultTableArg,
+                    evalMethod,
+                    arguments,
+                    argumentsByName,
+                    isSingleTableFunction,
+                    extractScalarValues(arguments),
+                    inputConverters,
+                    outputConverters);
+        }
+
+        /** Extracts scalar values from configs, creating a map keyed by argument name. */
+        private Map<String, Object> extractScalarValues(List<ArgumentInfo> arguments) {
+            Map<String, Object> values = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    ScalarArgumentConfiguration config = scalarArgs.get(arg.name);
+                    if (config != null) {
+                        values.put(arg.name, config.value);
+                    }
+                }
+            }
+            return values;
+        }
+
+        /**
+         * Creates and initializes data structure converters for all table arguments.
+         *
+         * <p>For Row types, both input and output converters are the same (between Row and
+         * RowData).
+         *
+         * <p>For structured types, input converter uses Row types (Row to RowData), and the output
+         * converter uses the structured type.
+         */
+        private void createConverters(
+                List<ArgumentInfo> arguments,
+                Map<String, DataStructureConverter<Object, Object>> inputConverters,
+                Map<String, DataStructureConverter<Object, Object>> outputConverters) {
+            ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    String converterKey = arg.name;
+
+                    LogicalType logicalType = arg.dataType.getLogicalType();
+                    boolean isStructuredType =
+                            logicalType instanceof StructuredType
+                                    && ((StructuredType) logicalType)
+                                            .getImplementationClass()
+                                            .isPresent();
+
+                    if (isStructuredType) {
+                        StructuredType structuredType = (StructuredType) logicalType;
+                        List<RowType.RowField> rowFields = new ArrayList<>();
+                        for (StructuredType.StructuredAttribute attr :
+                                structuredType.getAttributes()) {
+                            rowFields.add(new RowType.RowField(attr.getName(), attr.getType()));
+                        }
+                        RowType rowType = new RowType(logicalType.isNullable(), rowFields);
+                        DataType rowDataType = TypeConversions.fromLogicalToDataType(rowType);
+
+                        DataStructureConverter<Object, Object> inputConverter =
+                                DataStructureConverters.getConverter(rowDataType);
+                        inputConverter.open(classLoader);
+
+                        DataStructureConverter<Object, Object> outputConverter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        outputConverter.open(classLoader);
+
+                        inputConverters.put(converterKey, inputConverter);
+                        outputConverters.put(converterKey, outputConverter);
+                    } else {
+                        DataStructureConverter<Object, Object> converter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        converter.open(classLoader);
+
+                        inputConverters.put(converterKey, converter);
+                        outputConverters.put(converterKey, converter);
+                    }
+                }
+            }
+        }
+
+        private Method findEvalMethod() throws NoSuchMethodException {
+            Method[] methods = functionClass.getMethods();
+            Method evalMethod = null;
+            int evalMethodCount = 0;
+
+            for (Method method : methods) {
+                if (method.getName().equals("eval")) {
+                    evalMethod = method;
+                    evalMethodCount++;
+                }
+            }
+
+            if (evalMethodCount == 0) {
+                throw new NoSuchMethodException(
+                        "No eval() method found in " + functionClass.getSimpleName());
+            } else if (evalMethodCount > 1) {
+                throw new IllegalStateException(
+                        "Multiple eval() methods found in "
+                                + functionClass.getSimpleName()
+                                + ". ProcessTableFunction must have exactly one eval() method.");
+            } else {
+                return evalMethod;
+            }
+        }
+
+        /**
+         * Validates that the eval() method doesn't use unsupported features. Temporary, until state
+         * and context is supported.
+         */
+        private void validateEvalMethodSupported(Method evalMethod, List<ArgumentInfo> arguments) {
+            Parameter[] parameters = evalMethod.getParameters();
+
+            for (int i = 0; i < parameters.length; i++) {
+                Parameter param = parameters[i];
+                Class<?> paramType = param.getType();
+
+                if (ProcessTableFunction.Context.class.isAssignableFrom(paramType)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support Context parameters. "
+                                            + "Found Context parameter at position %d in eval() method. ",
+                                    i));
+                }
+
+                if (param.isAnnotationPresent(StateHint.class)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support state parameters. "
+                                            + "Found @StateHint parameter at position %d in eval() method. ",
+                                    i));
+                }
+            }
+
+            // Parameter count should also match our arguments list
+            if (parameters.length != arguments.size()) {
+                throw new IllegalStateException(
+                        String.format(
+                                "Parameter count mismatch: eval() has %d parameters but only %d arguments were extracted. "
+                                        + "This may indicate missing @ArgumentHint annotations.",
+                                parameters.length, arguments.size()));
+            }
+        }
+
+        /**
+         * Validates that all SET_SEMANTIC_TABLE arguments with partitioning use consistent
+         * partitioning. All such arguments must have the same number of partition columns with
+         * matching data types.
+         */
+        private void validatePartitionConsistency(List<ArgumentInfo> arguments) {
+            List<ArgumentInfo> partitionedTables = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    partitionedTables.add(arg);
+                }
+            }
+
+            if (partitionedTables.size() <= 1) {
+                return;
+            }
+
+            ArgumentInfo first = partitionedTables.get(0);
+            int expectedPartitionColumnCount = first.partitionColumnNames.length;
+
+            for (int i = 1; i < partitionedTables.size(); i++) {
+                ArgumentInfo current = partitionedTables.get(i);
+
+                if (current.partitionColumnNames.length != expectedPartitionColumnCount) {
+                    throw new IllegalArgumentException(
+                            String.format(
+                                    "Inconsistent partitioning: Table argument '%s' has %d partition column(s), "
+                                            + "but table argument '%s' has %d partition column(s). "
+                                            + "All SET_SEMANTIC_TABLE arguments must use consistent partitioning "
+                                            + "(same number of columns and matching data types).",
+                                    first.name,
+                                    expectedPartitionColumnCount,
+                                    current.name,
+                                    current.partitionColumnNames.length));
+                }
+
+                // Check that partition column types match
+                for (int colIdx = 0; colIdx < expectedPartitionColumnCount; colIdx++) {
+                    String firstColName = first.partitionColumnNames[colIdx];
+                    String currentColName = current.partitionColumnNames[colIdx];
+                    DataType firstColType = extractPartitionColumnType(first, firstColName);
+                    DataType currentColType = extractPartitionColumnType(current, currentColName);
+
+                    if (!firstColType.getLogicalType().equals(currentColType.getLogicalType())) {
+                        throw new IllegalArgumentException(
+                                String.format(
+                                        "Inconsistent partitioning: Partition column '%s' of table argument '%s' "
+                                                + "has type %s, but partition column '%s' of table argument '%s' "
+                                                + "has type %s. All SET_SEMANTIC_TABLE arguments must use "
+                                                + "consistent partitioning (same number of columns and matching data types).",
+                                        firstColName,
+                                        first.name,
+                                        firstColType,
+                                        currentColName,
+                                        current.name,
+                                        currentColType));
+                    }
+                }
+            }
+        }
+
+        private DataType extractPartitionColumnType(ArgumentInfo arg, String columnName) {
+            if (arg.dataType instanceof FieldsDataType) {
+                FieldsDataType fieldsDataType = (FieldsDataType) arg.dataType;
+                LogicalType logicalType = fieldsDataType.getLogicalType();
+                List<DataType> fieldDataTypes = fieldsDataType.getChildren();
+
+                if (logicalType instanceof RowType) {
+                    RowType rowType = (RowType) logicalType;
+                    int fieldIndex = 0;
+                    for (RowType.RowField field : rowType.getFields()) {
+                        if (field.getName().equals(columnName)) {
+                            return fieldDataTypes.get(fieldIndex);
+                        }
+                        fieldIndex++;
+                    }
+                } else if (logicalType instanceof StructuredType) {
+                    StructuredType structuredType = (StructuredType) logicalType;
+                    int attrIndex = 0;
+                    for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                        if (attr.getName().equals(columnName)) {
+                            return fieldDataTypes.get(attrIndex);
+                        }
+                        attrIndex++;
+                    }
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format(
+                            "Cannot extract data type for partition column '%s' of argument '%s'",
+                            columnName, arg.name));
+        }
+
+        // ---------------------------------------------------------------------
+        // Type Inference
+        // ---------------------------------------------------------------------
+
+        /**
+         * Extracts type inference from the PTF and validates builder configuration.
+         *
+         * <p>Uses SystemTypeInference to validate things like reserved argument names, multiple
+         * table argument rules, static argument trait validation, etc.
+         */
+        private List<ArgumentInfo> extractAndValidateTypeInference(
+                ProcessTableFunction<OUT> function) {
+
+            DataTypeFactory dataTypeFactory = createDataTypeFactory();
+            TypeInference baseTypeInference = function.getTypeInference(dataTypeFactory);
+            TypeInference systemTypeInference =
+                    SystemTypeInference.of(FunctionKind.PROCESS_TABLE, baseTypeInference);
+
+            Optional<List<StaticArgument>> staticArgsOpt = systemTypeInference.getStaticArguments();
+            if (staticArgsOpt.isEmpty()) {
+                throw new IllegalStateException(
+                        "PTF does not provide static argument information. "
+                                + "Ensure @ArgumentHint annotations are present on all eval() parameters.");
+            }
+
+            List<StaticArgument> allArgs = staticArgsOpt.get();
+            List<StaticArgument> userArgs = new ArrayList<>();
+            for (StaticArgument arg : allArgs) {
+                if (!isSystemArgument(arg.getName())) {
+                    userArgs.add(arg);
+                }
+            }
+
+            List<ArgumentInfo> arguments = new ArrayList<>();
+
+            for (StaticArgument staticArg : userArgs) {
+                boolean isScalar = staticArg.getTraits().contains(StaticArgumentTrait.SCALAR);
+                boolean isTableArg =
+                        staticArg.getTraits().contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)
+                                || staticArg
+                                        .getTraits()
+                                        .contains(StaticArgumentTrait.SET_SEMANTIC_TABLE);
+
+                if (isScalar || isTableArg) {
+                    ArgumentInfo argInfo = buildArgumentInfo(staticArg);
+                    arguments.add(argInfo);
+                } else {
+                    throw new IllegalStateException(
+                            "Unknown argument type for StaticArgument. "
+                                    + "Expected SCALAR, ROW_SEMANTIC_TABLE, or SET_SEMANTIC_TABLE trait.");
+                }
+            }
+
+            validateArgumentConfiguration(arguments);
+
+            return arguments;
+        }
+
+        /** Checks if an argument name is a system-reserved argument. */
+        private boolean isSystemArgument(String argName) {
+            return SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_ON_TIME.equals(argName)
+                    || SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_UID.equals(argName);
+        }
+
+        private DataTypeFactory createDataTypeFactory() {
+            return new TestHarnessDataTypeFactory();
+        }
+
+        private ArgumentInfo buildArgumentInfo(StaticArgument staticArg) {
+
+            String name = staticArg.getName();
+            ArgumentTrait primaryTrait = extractPrimaryTrait(staticArg.getTraits());
+
+            DataType dataType;
+            if (primaryTrait == ArgumentTrait.SCALAR) {
+                Optional<DataType> dataTypeOpt = staticArg.getDataType();
+                if (dataTypeOpt.isPresent()) {
+                    dataType = dataTypeOpt.get();
+                } else {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "Cannot determine data type for scalar argument '%s'", name));
+                }
+            } else {
+                // For table arguments, check both annotation and builder config
+                Optional<DataType> annotationTypeOpt = staticArg.getDataType();
+                TableArgumentConfiguration config = tableArgs.get(name);
+
+                if (annotationTypeOpt.isPresent()
+                        && config != null
+                        && config.explicitType != null) {
+                    // Both specified - validate they match
+                    DataTypeFactory factory = createDataTypeFactory();
+                    DataType builderType = factory.createDataType(config.explicitType);
+                    DataType annotationType = annotationTypeOpt.get();
+
+                    if (!annotationType.equals(builderType)) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Type mismatch for table argument '%s': "
+                                                + "annotation declares type %s but builder declares type %s. "
+                                                + "Use either @ArgumentHint(type = ...) OR .withTableArgument(...), not both.",
+                                        name, annotationType, builderType));
+                    }
+                    dataType = annotationType;
+                } else if (annotationTypeOpt.isPresent()) {
+                    dataType = annotationTypeOpt.get();
+                } else if (config != null && config.explicitType != null) {
+                    DataTypeFactory factory = createDataTypeFactory();
+                    dataType = factory.createDataType(config.explicitType);
+                } else {
+                    // Try to infer from Java parameter class (for structured types)
+                    Optional<Class<?>> conversionClassOpt = staticArg.getConversionClass();
+                    if (conversionClassOpt.isPresent()) {
+                        DataTypeFactory factory = createDataTypeFactory();
+                        dataType = factory.createDataType(conversionClassOpt.get());
+                    } else {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Table argument '%s' requires explicit type configuration. "
+                                                + "Use @ArgumentHint(type = @DataTypeHint(\"ROW<...>\")) or "
+                                                + ".withTableArgument(\"%s\", DataTypes.of(\"ROW<...>\"))",
+                                        name, name));
+                    }
+                }
+            }
+
+            String[] partitionColumnNames = null;
+            if (primaryTrait == ArgumentTrait.SET_SEMANTIC_TABLE) {
+                boolean hasOptionalPartitionBy =
+                        staticArg.getTraits().contains(StaticArgumentTrait.OPTIONAL_PARTITION_BY);
+                partitionColumnNames =
+                        extractAndValidatePartitionColumns(name, dataType, hasOptionalPartitionBy);
+            }
+
+            boolean hasPassColumnsThrough =
+                    staticArg.getTraits().contains(StaticArgumentTrait.PASS_COLUMNS_THROUGH);
+
+            return new ArgumentInfo(
+                    name, dataType, primaryTrait, partitionColumnNames, hasPassColumnsThrough);
+        }
+
+        private ArgumentTrait extractPrimaryTrait(EnumSet<StaticArgumentTrait> staticTraits) {
+            if (staticTraits.contains(StaticArgumentTrait.SCALAR)) {
+                return ArgumentTrait.SCALAR;
+            }
+            if (staticTraits.contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)) {
+                return ArgumentTrait.ROW_SEMANTIC_TABLE;
+            }
+            if (staticTraits.contains(StaticArgumentTrait.SET_SEMANTIC_TABLE)) {
+                return ArgumentTrait.SET_SEMANTIC_TABLE;
+            }

Review Comment:
   I just ran a quick test of this, a PTF with multiple primary traits (like both ROW_SEMANTIC_TABLE and SET_SEMANTIC_TABLE) are rejected during harness build because the system type inference fails with a `org.apache.flink.table.api.ValidationException`, so it should be fine



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "autophagy (via GitHub)" <gi...@apache.org>.
autophagy commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3256962122


##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -309,26 +354,84 @@ private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Excep
 
         try {
             evalMethod.invoke(function, args);
+        } catch (IllegalArgumentException e) {

Review Comment:
   I think its unnecessary there too actually, as passing in a table argument means its chained through InputType -> RowData -> Defined Table Argument Type. The type mismatch would be found there, not during the invoke



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "autophagy (via GitHub)" <gi...@apache.org>.
autophagy commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3217411510


##########
docs/content.zh/docs/dev/table/functions/ptfs.md:
##########
@@ -2034,3 +2034,336 @@ Limitations
 PTFs are in an early stage. The following limitations apply:
 - PTFs cannot run in batch mode.
 - Broadcast state
+
+Testing Process Table Functions
+-------------------------------
+
+The `ProcessTableFunctionTestHarness` provides a lightweight unit testing framework for Process Table
+Functions (PTFs). It is useful for unit testing and validating PTF business logic, multi-table PTF
+behaviour and validating errors.
+
+For end-to-end integration testing with the full Flink planner and runtime, use integration tests
+instead.
+
+{{< top >}}
+
+### Quick Start
+
+{{< tabs "quickstart" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.*;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.runtime.functions.ProcessTableFunctionTestHarness;
+import org.apache.flink.types.Row;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+// PTF under test
+@DataTypeHint("ROW<doubled INT>")
+public class DoublePTF extends ProcessTableFunction<Row> {
+  public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+    int value = input.getFieldAs("value");
+    collect(Row.of(value * 2));
+  }
+}
+
+// Test
+@Test
+void testDoublePTF() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(DoublePTF.class)
+          .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+          .build()) {
+
+    harness.processElement(Row.of(5));
+    harness.processElement(Row.of(10));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).hasSize(2);
+    assertThat(output.get(0)).isEqualTo(Row.of(10));
+    assertThat(output.get(1)).isEqualTo(Row.of(20));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+{{< top >}}
+
+### Common Testing Scenarios
+
+#### Testing Row-Semantic Tables
+
+Use `.withTableArgument()` to configure the input table schema:
+
+{{< tabs "row-semantic" >}}
+{{< tab "Java" >}}
+```java
+public class PassthroughPTF extends ProcessTableFunction<Integer> {
+  public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+    collect(input.getFieldAs("value"));
+  }
+}
+
+@Test
+void testPassthrough() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+          .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+          .build()) {
+
+    harness.processElement(Row.of(42));
+    harness.processElement(Row.of(100));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).containsExactly(42, 100);
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Testing Set-Semantic Tables with Partitioning
+
+For `SET_SEMANTIC_TABLE`, use `.withPartitionBy()` to configure partition columns:
+
+{{< tabs "set-semantic" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<doubled INT>")
+public class PartitionedPTF extends ProcessTableFunction<Row> {
+  public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+    int value = input.getFieldAs("value");
+    collect(Row.of(value * 2));
+  }
+}
+
+@Test
+void testPartitionedPTF() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+          .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+          .withPartitionBy("input", "key")
+          .build()) {
+
+    harness.processElement(Row.of("A", 10));
+    harness.processElement(Row.of("B", 20));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+    assertThat(output.get(1)).isEqualTo(Row.of("B", 40));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Testing Multiple Table Arguments
+
+Use `processElementForTable()` to specify which table receives each row:
+
+{{< tabs "multi-table" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<output STRING>")
+public class JoinPTF extends ProcessTableFunction<Row> {
+  public void eval(
+      @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row left,
+      @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row right) {
+    if (left != null) {
+      collect(Row.of("LEFT: " + left));
+    }
+    if (right != null) {
+      collect(Row.of("RIGHT: " + right));
+    }
+  }
+}
+
+@Test
+void testMultiTable() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(JoinPTF.class)
+          .withTableArgument("left", DataTypes.of("ROW<id INT, name STRING>"))
+          .withPartitionBy("left", "id")
+          .withTableArgument("right", DataTypes.of("ROW<id INT, city STRING>"))
+          .withPartitionBy("right", "id")
+          .build()) {
+
+    // Use processElementForTable() to target specific tables
+    harness.processElementForTable("left", Row.of(1, "Alice"));
+    harness.processElementForTable("right", Row.of(1, "Berlin"));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output.get(0)).isEqualTo(Row.of(1, null, "LEFT: +I[1, Alice]"));
+    assertThat(output.get(1)).isEqualTo(Row.of(null, 1, "RIGHT: +I[1, Berlin]"));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Testing with Scalar Arguments
+
+Use `.withScalarArgument()` to configure scalar parameter values:
+
+{{< tabs "scalar-args" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<value INT>")
+public class FilterPTF extends ProcessTableFunction<Row> {
+  public void eval(
+      @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+      int threshold) {
+    int value = input.getFieldAs("value");
+    if (value > threshold) {
+      collect(Row.of(value));
+    }
+  }
+}
+
+@Test
+void testFilter() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+          .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+          .withScalarArgument("threshold", 50)  // Configure scalar value
+          .build()) {
+
+    harness.processElement(Row.of(30));
+    harness.processElement(Row.of(70));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).containsExactly(Row.of(70));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+**Scalar-Only PTFs**: For PTFs with only scalar arguments, use `process()` to trigger evaluation:
+
+{{< tabs "scalar-only" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<sum INT>")
+public class AddPTF extends ProcessTableFunction<Row> {
+  public void eval(int a, int b) {
+    collect(Row.of(a + b));
+  }
+}
+
+@Test
+void testScalarOnly() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(AddPTF.class)
+          .withScalarArgument("a", 5)
+          .withScalarArgument("b", 7)
+          .build()) {
+
+    harness.process();  // Use process() instead of processElement()
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).containsExactly(Row.of(12));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Configuring Table Argument Types
+
+The harness supports two ways to specify table argument types:
+
+{{< tabs "type-config" >}}
+{{< tab "Java" >}}
+```java
+// Option 1: Inline type annotation using DataTypeHint
+@DataTypeHint("ROW<doubled INT>")
+public class InlineTypePTF extends ProcessTableFunction<Row> {
+  public void eval(
+      @ArgumentHint(
+        value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+        type = @DataTypeHint("ROW<value INT>")
+      ) Row input) {
+    int value = input.getFieldAs("value");
+    collect(Row.of(value * 2));
+  }
+}
+
+@Test
+void testInlineType() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class).build()) {
+
+    harness.processElement(Row.of(5));
+    assertThat(harness.getOutput()).containsExactly(Row.of(10));
+  }
+}
+
+// Option 2: Builder configuration
+@Test
+void testBuilderType() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(DoublePTF.class)
+          .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+          .build()) {
+
+    harness.processElement(Row.of(5));
+    assertThat(harness.getOutput()).containsExactly(Row.of(10));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+**Structured Types**: The harness supports structured POJO types in addition to `Row`, both as PTF inputs
+and outputs:
+
+{{< tabs "pojo-types" >}}
+{{< tab "Java" >}}
+```java
+public static class Customer {
+  public String name;
+  public int age;
+}
+
+public class CustomerPTF extends ProcessTableFunction<Customer> {
+  public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Customer c) {
+    collect(c);
+  }
+}
+
+@Test
+void testPOJO() throws Exception {
+  try (ProcessTableFunctionTestHarness<Customer> harness =
+      ProcessTableFunctionTestHarness.ofClass(CustomerPTF.class)
+          .withTableArgument("input", DataTypes.of(Customer.class))
+          .build()) {
+
+    harness.processElement(Row.of("Alice", 30));
+
+    List<Customer> output = harness.getOutput();
+    assertThat(output.get(0).name).isEqualTo("Alice");
+    assertThat(output.get(0).age).isEqualTo(30);
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+{{< top >}}
+
+### Unsupported Features

Review Comment:
   Oops, thank you for the pointer 😅 Yeah, a silly mistake from merging the independent testing page into the general PTF page



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "autophagy (via GitHub)" <gi...@apache.org>.
autophagy commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3217494790


##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {

Review Comment:
   > are pass-through columns and partitioning columns mutually exclusive?
   
   I'm not sure about exclusive? Pass-through cols are only valid on PTFs taking a single table argument, and the system type inference will throw an error on harness build if this isn't the case. I guess exclusive in the sense that pass through will already contain the partition column.
   
   > If no, wouldn't we need to add the partitioning columns of the other table inputs as well?
   
   I don't think so, since pass through is only valid on single table argument PTFs



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "spuru9 (via GitHub)" <gi...@apache.org>.
spuru9 commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3084960571


##########
docs/content/docs/dev/table/testing/ptf_test_harness.md:
##########
@@ -0,0 +1,361 @@
+---

Review Comment:
   The testing/ directory is missing an _index.md (needed to show the section in the sidebar). Could you add one following the pattern of the sibling directories like functions/?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "autophagy (via GitHub)" <gi...@apache.org>.
autophagy commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3257322962


##########
flink-table/flink-table-test-utils/src/test/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarnessTest.java:
##########
@@ -0,0 +1,1021 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.api.ValidationException;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class ProcessTableFunctionTestHarnessTest {
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PassthroughPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** Filter PTF for testing scalar argument handling. */
+    @DataTypeHint("ROW<value INT>")
+    public static class FilterPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer threshold) {
+            // Use named field access - converter enriches Row with field names
+            int value = input.getFieldAs("value");
+            if (value >= threshold) {
+                collect(input);
+            }
+        }
+    }
+
+    /** PTF for testing transformation of output types. */
+    @DataTypeHint("ROW<doubled INT, original INT>")
+    public static class DoublePTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2, value));
+        }
+    }
+
+    /** PTF with for testing table argument names set via argument hints. */
+    @DataTypeHint("ROW<value INT>")
+    public static class ExplicitNamePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "customName")
+                        Row actualParamName) {
+            collect(actualParamName);
+        }
+    }
+
+    /** PTF with inline type annotation - no builder config needed. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class InlineTypePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(
+                                value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+                                type = @DataTypeHint("ROW<value INT>"))
+                        Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PartitionedPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+            collect(Row.of((Integer) input.getFieldAs("value")));
+        }
+    }
+
+    /**
+     * PTF with PASS_COLUMNS_THROUGH for validating that all input columns are prepended to output.
+     */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class PassColumnsThroughPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** PTF with OPTIONAL_PARTITION_BY for validating that partition setup can be omitted. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class OptionalPartitionPTF extends ProcessTableFunction<Row> {
+
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.OPTIONAL_PARTITION_BY
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** Simple POJO for testing structured type input/output. */
+    public static class User {
+        public String name;
+        public int age;
+
+        public User() {}
+
+        public User(String name, int age) {
+            this.name = name;
+            this.age = age;
+        }
+
+        @Override
+        public String toString() {
+            return "User{name='" + name + "', age=" + age + '}';
+        }
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o) {
+                return true;
+            }
+            if (o == null || getClass() != o.getClass()) {
+                return false;
+            }
+            User user = (User) o;
+            return age == user.age && java.util.Objects.equals(name, user.name);
+        }
+
+        @Override
+        public int hashCode() {
+            return java.util.Objects.hash(name, age);
+        }
+    }
+
+    /** PTF for testing structured type inputs. */
+    @DataTypeHint("ROW<name STRING, age INT>")
+    public static class UserPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            if (user.age >= 18) {
+                collect(Row.of(user.name, user.age));
+            }
+        }
+    }
+
+    /** PTF that transforms structured type inputs and outputs. */
+    public static class UserTransformPTF extends ProcessTableFunction<User> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            User transformed = new User(user.name, user.age + 1);
+            collect(transformed);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "on_time". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgOnTimePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "on_time")
+                        Row input) {
+            collect(input);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "uid". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgUidPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) String uid) {
+            collect(input);
+        }
+    }
+
+    /** Multi-table PTF for validating multi-input processing. */
+    @DataTypeHint("ROW<output STRING>")
+    public static class MultiTableUnionPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /**
+     * Multi-table PTF with one POJO and one Row argument, for testing partitioning with structured
+     * types.
+     */
+    @DataTypeHint("ROW<source STRING, age INT>")
+    public static class MixedTypeMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) User userTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rowTable) {
+            if (userTable != null) {
+                collect(Row.of("USER", userTable.age));
+            }
+            if (rowTable != null) {
+                collect(Row.of("ROW", rowTable.getFieldAs("age")));
+            }
+        }
+    }
+
+    /**
+     * Invalid PTF - uses PASS_COLUMNS_THROUGH with multiple table arguments (not allowed per Flink
+     * docs).
+     */
+    @DataTypeHint("ROW<output STRING>")
+    public static class InvalidPassColumnsThroughMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /** PTF with only scalar arguments, no tables. */
+    @DataTypeHint("ROW<sum INT>")
+    public static class ScalarOnlyPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer a,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer b) {
+            collect(Row.of(a + b));
+        }
+    }
+
+    /** PTF with Context parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithContext extends ProcessTableFunction<Row> {
+        public void eval(Context ctx, @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** PTF with State parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithState extends ProcessTableFunction<Row> {
+        public static class CountState {
+            public long counter = 0L;
+        }
+
+        public void eval(
+                @StateHint CountState state,
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Builder Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testBuilderRejectsDuplicateScalarArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("threshold", 50)
+                                    .withScalarArgument("threshold", 100);
+                        });
+
+        assertThat(exception.getMessage()).contains("threshold");
+    }
+
+    @Test
+    void testBuilderRejectsDuplicateTableArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableUnionPTF.class)
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, value INT>"));
+                        });
+
+        assertThat(exception.getMessage()).contains("leftTable");
+    }
+
+    @Test
+    void testBuilderRejectsMixedDuplicateArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("input", 42);
+                        });
+
+        assertThat(exception.getMessage()).contains("input");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentOnTime() {
+        // We should reject PTFs that use reserved argument name "on_time"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgOnTimePTF.class)
+                        .withTableArgument("on_time", DataTypes.of("ROW<id INT>"));
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("on_time");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentUid() {
+        // We should reject PTFs that use reserved argument name "uid"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgUidPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<id INT>"))
+                        .withScalarArgument("uid", "my-id");
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("uid");
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testExplicitNameTakesPrecedence() throws Exception {
+        // Verify that @ArgumentHint(name="customName") takes precedence over actual parameter
+        // name when processing elements and calling eval.
+
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ExplicitNamePTF.class)
+                        .withTableArgument("customName", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(42));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0).getField(0)).isEqualTo(42);
+            assertThat(output.get(1).getField(0)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testScalarOnlyPTF() throws Exception {
+        // Test scalar-only PTF with no table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ScalarOnlyPTF.class)
+                        .withScalarArgument("a", 10)
+                        .withScalarArgument("b", 20)
+                        .build()) {
+
+            harness.process();
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0).getField(0)).isEqualTo(30);
+        }
+    }
+
+    @Test
+    void testInvokeRejectsTableArguments() throws Exception {
+        // Verify that invoke() rejects PTFs with table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50)
+                        .build()) {
+
+            Exception exception =
+                    assertThrows(
+                            IllegalStateException.class,
+                            () -> {
+                                harness.process();
+                            });
+
+            assertThat(exception.getMessage()).contains("process() is only for scalar-only PTFs");
+        }
+    }
+
+    @Test
+    void testTableProcessingWithScalarArgument() throws Exception {
+        // Test a PTF that uses a scalar parameter
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50) // Scalar argument: threshold = 50
+                        .build()) {
+
+            harness.processElement(Row.of(25));
+            harness.processElement(Row.of(75));
+            harness.processElement(Row.of(50));
+            harness.processElement(Row.of(10));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0).getField(0)).isEqualTo(75);
+            assertThat(output.get(1).getField(0)).isEqualTo(50);
+            assertThat(output.get(2).getField(0)).isEqualTo(100);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Trait Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testProcessElementWithRowKind() throws Exception {
+        // Verify RowKind is preserved through processing (ROW_SEMANTIC_TABLE)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(RowKind.INSERT, 10);
+            harness.processElement(RowKind.UPDATE_BEFORE, 15);
+            harness.processElement(RowKind.UPDATE_AFTER, 20);
+            harness.processElement(RowKind.DELETE, 30);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+            assertThat(output.get(0).getKind()).isEqualTo(RowKind.INSERT);
+            assertThat(output.get(0).getField(0)).isEqualTo(10);
+            assertThat(output.get(1).getKind()).isEqualTo(RowKind.UPDATE_BEFORE);
+            assertThat(output.get(1).getField(0)).isEqualTo(15);
+            assertThat(output.get(2).getKind()).isEqualTo(RowKind.UPDATE_AFTER);
+            assertThat(output.get(2).getField(0)).isEqualTo(20);
+            assertThat(output.get(3).getKind()).isEqualTo(RowKind.DELETE);
+            assertThat(output.get(3).getField(0)).isEqualTo(30);
+        }
+    }
+
+    @Test
+    void testPassColumnsThroughTrait() throws Exception {
+        // Verify PASS_COLUMNS_THROUGH prepends ALL input columns (not just partition keys)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassColumnsThroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 10, 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("B", 20, 40));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithoutPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY allows omitting partition configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+            harness.processElement(Row.of("C", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of(20));
+            assertThat(output.get(1)).isEqualTo(Row.of(40));
+            assertThat(output.get(2)).isEqualTo(Row.of(60));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY still works when partition is configured
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("A", 5));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("A", 10));
+            assertThat(output.get(2)).isEqualTo(Row.of("B", 40));
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Data Type Conversion Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testNamedRowFieldOrdering() throws Exception {
+        // Test what happens when Row field order differs from DataType schema order
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row rowA = Row.withNames();
+            rowA.setField("value", 100);
+            rowA.setField("user", "Alice");
+
+            harness.processElement(rowA);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+
+            // Positional access follows schema order
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testPositionalRowWithWrongTypeOrder() throws Exception {
+        // Verify that type mismatches are caught when Row values don't match schema types
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row wrongOrderRow = Row.of(10, "Alice");
+
+            Exception exception =
+                    assertThrows(
+                            ClassCastException.class, () -> harness.processElement(wrongOrderRow));
+
+            assertThat(exception.getMessage()).contains("Integer");
+            assertThat(exception.getMessage()).contains("String");
+            assertThat(exception.getMessage()).contains("cannot be cast");
+        }
+    }
+
+    @Test
+    void testStructuredTypeInput() throws Exception {
+        // Test that a PTF can declare an input type as a structured type,
+        // and that the harness can handle the conversion from Row into
+        // that type.
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+            harness.processElement(Row.of("Bob", 17));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(25);
+        }
+    }
+
+    @Test
+    void testStructuredTypeInputAndOutput() throws Exception {
+        // Test PTF with structured type inputs and outputs
+        try (ProcessTableFunctionTestHarness<User> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserTransformPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+
+            List<User> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            User result = output.get(0);
+            assertThat(result.getClass()).isEqualTo(User.class);
+            assertThat(result.name).isEqualTo("Alice");
+            assertThat(result.age).isEqualTo(26);
+        }
+    }
+
+    @Test
+    void testInlineTypeAnnotation() throws Exception {
+        // Verify that PTFs can declare table argument types via @ArgumentHint(type = ...)
+        // without needing .withTableArgument() configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class).build()) {
+
+            harness.processElement(Row.of(5));
+            harness.processElement(Row.of(10));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0)).isEqualTo(Row.of(10));
+            assertThat(output.get(1)).isEqualTo(Row.of(20));
+        }
+    }
+
+    @Test
+    void testInlineTypeMatchesBuilderConfig() throws Exception {
+        // Verify that when both inline annotation and builder config are provided with matching
+        // types, the harness builds successfully
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(7));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0)).isEqualTo(Row.of(14));
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Partitioning Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testSetSemanticWithPartitionByName() throws Exception {
+        // Verify set-semantic table with partition configuration by column name
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key") // Partition by "key" column name
+                        .build()) {
+
+            harness.processElement(Row.of("X", 10));
+            harness.processElement(Row.of("Y", 20));
+            harness.processElement(Row.of("X", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0)).isEqualTo(Row.of("X", 10));
+            assertThat(output.get(1)).isEqualTo(Row.of("Y", 20));
+            assertThat(output.get(2)).isEqualTo(Row.of("X", 30));
+        }
+    }
+
+    @Test
+    void testSetSemanticWithMultiplePartitionColumns() throws Exception {
+        // Verify composite partition key (multiple columns)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument(
+                                "input",
+                                DataTypes.of("ROW<region STRING, country STRING, value INT>"))
+                        .withPartitionBy("input", "region", "country")
+                        .build()) {
+
+            harness.processElement(Row.of("EU", "DE", 100));
+            harness.processElement(Row.of("EU", "DE", 200));
+            harness.processElement(Row.of("EU", "FR", 300));
+            harness.processElement(Row.of("US", "NY", 400));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+            assertThat(output.get(0)).isEqualTo(Row.of("EU", "DE", 100));
+            assertThat(output.get(1)).isEqualTo(Row.of("EU", "DE", 200));
+            assertThat(output.get(2)).isEqualTo(Row.of("EU", "FR", 300));
+            assertThat(output.get(3)).isEqualTo(Row.of("US", "NY", 400));
+        }
+    }
+
+    @Test
+    void testSetSemanticWithSelectivePartitioning() throws Exception {
+        // Verify that only partition columns are automatically included in output
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument(
+                                "input",
+                                DataTypes.of(
+                                        "ROW<id INT, region STRING, country STRING, city STRING, value INT>"))
+                        .withPartitionBy("input", "region")
+                        .build()) {
+
+            harness.processElement(Row.of(1, "EU", "DE", "Berlin", 100));
+            harness.processElement(Row.of(4, "US", "CA", "LA", 200));
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output.get(0)).isEqualTo(Row.of("EU", 100));
+            assertThat(output.get(1)).isEqualTo(Row.of("US", 200));
+        }
+    }
+
+    @Test
+    void testMultipleSetSemanticTablesWithMatchingPartitionKeys() throws Exception {
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(MultiTableUnionPTF.class)
+                        .withTableArgument("leftTable", DataTypes.of("ROW<name STRING, score INT>"))
+                        .withPartitionBy("leftTable", "name")
+                        .withTableArgument(
+                                "rightTable", DataTypes.of("ROW<name STRING, city STRING>"))
+                        .withPartitionBy("rightTable", "name")

Review Comment:
   Actually digging into this further, I think I misunderstood the test (that the column names were just for the sink schema). In the collector used for PTFs in the actual runtime, it just collects `RowData` which is purely positional I think. So I believe our behaviour here is correct



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "twalthr (via GitHub)" <gi...@apache.org>.
twalthr commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3093175093


##########
docs/content/docs/dev/table/testing/ptf_test_harness.md:
##########
@@ -0,0 +1,361 @@
+---
+title: "Testing Process Table Functions"
+weight: 10
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Testing Process Table Functions

Review Comment:
   Can we move this to:
   https://nightlies.apache.org/flink/flink-docs-master/docs/dev/table/functions/ptfs/
   
   I know this page is already long, but it is also very nice to everything you need to know around PTFs in one page.



##########
docs/content/docs/dev/table/testing/ptf_test_harness.md:
##########
@@ -0,0 +1,361 @@
+---
+title: "Testing Process Table Functions"
+weight: 10
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Testing Process Table Functions
+
+The `ProcessTableFunctionTestHarness` provides a lightweight unit testing framework for Process Table
+Functions (PTFs). It allows you to test PTF logic without starting a full Flink cluster. It is useful
+for testing and validating PTF business logic, multi-table PTF behaviour and validating errors.
+
+For end-to-end integration testing with the full Flink planner and runtime, use integration tests
+instead.
+
+{{< top >}}
+
+## Quick Start
+
+{{< tabs "quickstart" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.*;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.runtime.functions.ProcessTableFunctionTestHarness;
+import org.apache.flink.types.Row;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+// PTF under test
+@DataTypeHint("ROW<doubled INT>")
+public class DoublePTF extends ProcessTableFunction<Row> {
+    public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+        int value = input.getFieldAs("value");
+        collect(Row.of(value * 2));
+    }
+}
+
+// Test
+@Test
+void testDoublePTF() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(DoublePTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                    .build()) {
+
+        harness.processElement(Row.of(5));
+        harness.processElement(Row.of(10));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output).hasSize(2);
+        assertThat(output.get(0)).isEqualTo(Row.of(10));
+        assertThat(output.get(1)).isEqualTo(Row.of(20));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+{{< top >}}
+
+## Common Testing Scenarios
+
+### Testing Row-Semantic Tables
+
+Use `.withTableArgument()` to configure the input table schema:
+
+{{< tabs "row-semantic" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<value INT>")
+public class PassthroughPTF extends ProcessTableFunction<Row> {
+    public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+        collect(input);
+    }
+}
+
+@Test
+void testPassthrough() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)

Review Comment:
   nit: use two spaces in examples to keep the page readable and lines short



##########
docs/content/docs/dev/table/testing/ptf_test_harness.md:
##########
@@ -0,0 +1,361 @@
+---
+title: "Testing Process Table Functions"
+weight: 10
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Testing Process Table Functions
+
+The `ProcessTableFunctionTestHarness` provides a lightweight unit testing framework for Process Table
+Functions (PTFs). It allows you to test PTF logic without starting a full Flink cluster. It is useful
+for testing and validating PTF business logic, multi-table PTF behaviour and validating errors.
+
+For end-to-end integration testing with the full Flink planner and runtime, use integration tests
+instead.
+
+{{< top >}}
+
+## Quick Start
+
+{{< tabs "quickstart" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.*;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.runtime.functions.ProcessTableFunctionTestHarness;
+import org.apache.flink.types.Row;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+// PTF under test
+@DataTypeHint("ROW<doubled INT>")
+public class DoublePTF extends ProcessTableFunction<Row> {
+    public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+        int value = input.getFieldAs("value");
+        collect(Row.of(value * 2));
+    }
+}
+
+// Test
+@Test
+void testDoublePTF() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(DoublePTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                    .build()) {
+
+        harness.processElement(Row.of(5));
+        harness.processElement(Row.of(10));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output).hasSize(2);
+        assertThat(output.get(0)).isEqualTo(Row.of(10));
+        assertThat(output.get(1)).isEqualTo(Row.of(20));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+{{< top >}}
+
+## Common Testing Scenarios
+
+### Testing Row-Semantic Tables
+
+Use `.withTableArgument()` to configure the input table schema:
+
+{{< tabs "row-semantic" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<value INT>")
+public class PassthroughPTF extends ProcessTableFunction<Row> {
+    public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+        collect(input);
+    }
+}
+
+@Test
+void testPassthrough() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                    .build()) {
+
+        harness.processElement(Row.of(42));
+        harness.processElement(Row.of(100));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output).containsExactly(Row.of(42), Row.of(100));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Testing Set-Semantic Tables with Partitioning
+
+For `SET_SEMANTIC_TABLE`, use `.withPartitionBy()` to configure partition columns:
+
+{{< tabs "set-semantic" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<doubled INT>")
+public class PartitionedPTF extends ProcessTableFunction<Row> {
+    public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+        int value = input.getFieldAs("value");
+        collect(Row.of(value * 2));
+    }
+}
+
+@Test
+void testPartitionedPTF() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                    .withPartitionBy("input", "key")
+                    .build()) {
+
+        harness.processElement(Row.of("A", 10));
+        harness.processElement(Row.of("B", 20));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+        assertThat(output.get(1)).isEqualTo(Row.of("B", 40));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Testing Multiple Table Arguments
+
+Use `processElementForTable()` to specify which table receives each row:
+
+{{< tabs "multi-table" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<output STRING>")
+public class JoinPTF extends ProcessTableFunction<Row> {
+    public void eval(
+            @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row left,
+            @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row right) {
+        if (left != null) {
+            collect(Row.of("LEFT: " + left));
+        }
+        if (right != null) {
+            collect(Row.of("RIGHT: " + right));
+        }
+    }
+}
+
+@Test
+void testMultiTable() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(JoinPTF.class)
+                    .withTableArgument("left", DataTypes.of("ROW<id INT, name STRING>"))
+                    .withPartitionBy("left", "id")
+                    .withTableArgument("right", DataTypes.of("ROW<id INT, city STRING>"))
+                    .withPartitionBy("right", "id")
+                    .build()) {
+
+        // Use processElementForTable() to target specific tables
+        harness.processElementForTable("left", Row.of(1, "Alice"));
+        harness.processElementForTable("right", Row.of(1, "Berlin"));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output.get(0)).isEqualTo(Row.of(1, null, "LEFT: +I[1, Alice]"));
+        assertThat(output.get(1)).isEqualTo(Row.of(null, 1, "RIGHT: +I[1, Berlin]"));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Testing with Scalar Arguments
+
+Use `.withScalarArgument()` to configure scalar parameter values:
+
+{{< tabs "scalar-args" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<value INT>")
+public class FilterPTF extends ProcessTableFunction<Row> {

Review Comment:
   nit: do we also want to update at least one of the examples to non-Row. Just to show that also `ProcessTableFunction<Integer>` in this example is possible and is auto wrapped in the output.



##########
docs/content/docs/dev/table/testing/ptf_test_harness.md:
##########
@@ -0,0 +1,361 @@
+---
+title: "Testing Process Table Functions"
+weight: 10
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Testing Process Table Functions
+
+The `ProcessTableFunctionTestHarness` provides a lightweight unit testing framework for Process Table
+Functions (PTFs). It allows you to test PTF logic without starting a full Flink cluster. It is useful

Review Comment:
   PTF can also run locally without a full Flink cluster. This is more for unit testing.
   ```suggestion
   Functions (PTFs). It allows you to unit test PTF logic. It is useful
   ```



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/DataTypeFactoryMock.java:
##########
@@ -0,0 +1,116 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.Internal;
+import org.apache.flink.api.common.typeinfo.TypeInformation;
+import org.apache.flink.api.common.typeutils.TypeSerializer;
+import org.apache.flink.api.common.typeutils.base.VoidSerializer;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.api.ValidationException;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.catalog.UnresolvedIdentifier;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.UnresolvedDataType;
+import org.apache.flink.table.types.extraction.DataTypeExtractor;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.utils.LogicalTypeParser;
+import org.apache.flink.table.types.utils.TypeInfoDataTypeConverter;
+
+import java.util.Optional;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/** {@link DataTypeFactory} mock for testing purposes. Copied from flink-table-common. */
+@Internal
+class DataTypeFactoryMock implements DataTypeFactory {
+
+    public Optional<DataType> dataType = Optional.empty();
+
+    public Optional<LogicalType> logicalType = Optional.empty();
+
+    public Optional<Class<?>> expectedClass = Optional.empty();

Review Comment:
   There is a lot of unnecessary code. How about we call this `TestHarnessDataTypeFactory` and clean it up. We should inform the user if certain methods are not implemented. Also `dummyRaw` and `dummySerializer` are not needed.



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1199 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;

Review Comment:
   Important: The harness should be a light-weight Maven module that only depends on `flink-table-common`. Currently this module has a full planner and runtime dependency. How about we repurpose this module and potentially move `TableAssertionTest` to the planner module. After that we can simplify the deps for test-utils. This also means that DataStructureConverter is not available anymore. For this, let's introduce a new module `flink-table/flink-table-type-utils`. Introducing this module was under discussion a couple of times, we should do it now. Ideally under a new Jira ticket that gets merged before this PR.



##########
docs/content/docs/dev/table/testing/ptf_test_harness.md:
##########
@@ -0,0 +1,361 @@
+---
+title: "Testing Process Table Functions"
+weight: 10
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Testing Process Table Functions
+
+The `ProcessTableFunctionTestHarness` provides a lightweight unit testing framework for Process Table
+Functions (PTFs). It allows you to test PTF logic without starting a full Flink cluster. It is useful
+for testing and validating PTF business logic, multi-table PTF behaviour and validating errors.
+
+For end-to-end integration testing with the full Flink planner and runtime, use integration tests
+instead.
+
+{{< top >}}
+
+## Quick Start
+
+{{< tabs "quickstart" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.*;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.runtime.functions.ProcessTableFunctionTestHarness;
+import org.apache.flink.types.Row;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+// PTF under test
+@DataTypeHint("ROW<doubled INT>")
+public class DoublePTF extends ProcessTableFunction<Row> {
+    public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+        int value = input.getFieldAs("value");
+        collect(Row.of(value * 2));
+    }
+}
+
+// Test
+@Test
+void testDoublePTF() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(DoublePTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                    .build()) {
+
+        harness.processElement(Row.of(5));
+        harness.processElement(Row.of(10));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output).hasSize(2);
+        assertThat(output.get(0)).isEqualTo(Row.of(10));
+        assertThat(output.get(1)).isEqualTo(Row.of(20));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+{{< top >}}
+
+## Common Testing Scenarios
+
+### Testing Row-Semantic Tables
+
+Use `.withTableArgument()` to configure the input table schema:
+
+{{< tabs "row-semantic" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<value INT>")
+public class PassthroughPTF extends ProcessTableFunction<Row> {
+    public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+        collect(input);
+    }
+}
+
+@Test
+void testPassthrough() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                    .build()) {
+
+        harness.processElement(Row.of(42));
+        harness.processElement(Row.of(100));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output).containsExactly(Row.of(42), Row.of(100));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Testing Set-Semantic Tables with Partitioning
+
+For `SET_SEMANTIC_TABLE`, use `.withPartitionBy()` to configure partition columns:
+
+{{< tabs "set-semantic" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<doubled INT>")
+public class PartitionedPTF extends ProcessTableFunction<Row> {
+    public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+        int value = input.getFieldAs("value");
+        collect(Row.of(value * 2));
+    }
+}
+
+@Test
+void testPartitionedPTF() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                    .withPartitionBy("input", "key")
+                    .build()) {
+
+        harness.processElement(Row.of("A", 10));
+        harness.processElement(Row.of("B", 20));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+        assertThat(output.get(1)).isEqualTo(Row.of("B", 40));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Testing Multiple Table Arguments
+
+Use `processElementForTable()` to specify which table receives each row:
+
+{{< tabs "multi-table" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<output STRING>")
+public class JoinPTF extends ProcessTableFunction<Row> {
+    public void eval(
+            @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row left,
+            @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row right) {
+        if (left != null) {
+            collect(Row.of("LEFT: " + left));
+        }
+        if (right != null) {
+            collect(Row.of("RIGHT: " + right));
+        }
+    }
+}
+
+@Test
+void testMultiTable() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(JoinPTF.class)
+                    .withTableArgument("left", DataTypes.of("ROW<id INT, name STRING>"))
+                    .withPartitionBy("left", "id")
+                    .withTableArgument("right", DataTypes.of("ROW<id INT, city STRING>"))
+                    .withPartitionBy("right", "id")
+                    .build()) {
+
+        // Use processElementForTable() to target specific tables
+        harness.processElementForTable("left", Row.of(1, "Alice"));
+        harness.processElementForTable("right", Row.of(1, "Berlin"));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output.get(0)).isEqualTo(Row.of(1, null, "LEFT: +I[1, Alice]"));
+        assertThat(output.get(1)).isEqualTo(Row.of(null, 1, "RIGHT: +I[1, Berlin]"));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Testing with Scalar Arguments
+
+Use `.withScalarArgument()` to configure scalar parameter values:
+
+{{< tabs "scalar-args" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<value INT>")
+public class FilterPTF extends ProcessTableFunction<Row> {
+    public void eval(
+            @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+            @ArgumentHint(ArgumentTrait.SCALAR) int threshold) {
+        int value = input.getFieldAs("value");
+        if (value > threshold) {
+            collect(Row.of(value));
+        }
+    }
+}
+
+@Test
+void testFilter() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                    .withScalarArgument("threshold", 50)  // Configure scalar value
+                    .build()) {
+
+        harness.processElement(Row.of(30));
+        harness.processElement(Row.of(70));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output).containsExactly(Row.of(70));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+**Scalar-Only PTFs**: For PTFs with only scalar arguments, use `invoke()` to trigger evaluation:
+
+{{< tabs "scalar-only" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<sum INT>")
+public class AddPTF extends ProcessTableFunction<Row> {
+    public void eval(
+            @ArgumentHint(ArgumentTrait.SCALAR) int a,
+            @ArgumentHint(ArgumentTrait.SCALAR) int b) {
+        collect(Row.of(a + b));
+    }
+}
+
+@Test
+void testScalarOnly() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(AddPTF.class)
+                    .withScalarArgument("a", 5)
+                    .withScalarArgument("b", 7)
+                    .build()) {
+
+        harness.invoke();  // Use invoke() instead of processElement()
+
+        List<Row> output = harness.getOutput();
+        assertThat(output).containsExactly(Row.of(12));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Configuring Table Argument Types
+
+The harness supports two ways to specify table argument types:
+
+{{< tabs "type-config" >}}
+{{< tab "Java" >}}
+```java
+// Option 1: Inline type annotation using DataTypeHint
+@DataTypeHint("ROW<doubled INT>")
+public class InlineTypePTF extends ProcessTableFunction<Row> {
+    public void eval(
+            @ArgumentHint(
+                value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+                type = @DataTypeHint("ROW<value INT>")
+            ) Row input) {
+        int value = input.getFieldAs("value");
+        collect(Row.of(value * 2));
+    }
+}
+
+@Test
+void testInlineType() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class).build()) {
+
+        harness.processElement(Row.of(5));
+        assertThat(harness.getOutput()).containsExactly(Row.of(10));
+    }
+}
+
+// Option 2: Builder configuration
+@Test
+void testBuilderType() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(DoublePTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                    .build()) {
+
+        harness.processElement(Row.of(5));
+        assertThat(harness.getOutput()).containsExactly(Row.of(10));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+**Structured Types**: The harness supports structured POJO types in addition to `Row`, both as PTF inputs
+and outputs:
+
+{{< tabs "pojo-types" >}}
+{{< tab "Java" >}}
+```java
+public static class Customer {
+    public String name;
+    public int age;
+}
+
+@DataTypeHint("ROW<name STRING, age INT>")
+public class CustomerPTF extends ProcessTableFunction<Customer> {
+    public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Customer c) {
+        collect(c);
+    }
+}
+
+@Test
+void testPOJO() throws Exception {
+    try (ProcessTableFunctionTestHarness<Customer> harness =
+            ProcessTableFunctionTestHarness.ofClass(CustomerPTF.class)
+                    .withTableArgument("input", DataTypes.of(Customer.class))

Review Comment:
   Should not not be necessary if the type is explicit in the function?
   ```suggestion
                       .withTableArgument("input")
   ```



##########
docs/content/docs/dev/table/testing/ptf_test_harness.md:
##########
@@ -0,0 +1,361 @@
+---
+title: "Testing Process Table Functions"
+weight: 10
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Testing Process Table Functions
+
+The `ProcessTableFunctionTestHarness` provides a lightweight unit testing framework for Process Table
+Functions (PTFs). It allows you to test PTF logic without starting a full Flink cluster. It is useful
+for testing and validating PTF business logic, multi-table PTF behaviour and validating errors.
+
+For end-to-end integration testing with the full Flink planner and runtime, use integration tests
+instead.
+
+{{< top >}}
+
+## Quick Start
+
+{{< tabs "quickstart" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.*;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.runtime.functions.ProcessTableFunctionTestHarness;
+import org.apache.flink.types.Row;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+// PTF under test
+@DataTypeHint("ROW<doubled INT>")
+public class DoublePTF extends ProcessTableFunction<Row> {
+    public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+        int value = input.getFieldAs("value");
+        collect(Row.of(value * 2));
+    }
+}
+
+// Test
+@Test
+void testDoublePTF() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(DoublePTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                    .build()) {
+
+        harness.processElement(Row.of(5));
+        harness.processElement(Row.of(10));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output).hasSize(2);
+        assertThat(output.get(0)).isEqualTo(Row.of(10));
+        assertThat(output.get(1)).isEqualTo(Row.of(20));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+{{< top >}}
+
+## Common Testing Scenarios
+
+### Testing Row-Semantic Tables
+
+Use `.withTableArgument()` to configure the input table schema:
+
+{{< tabs "row-semantic" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<value INT>")
+public class PassthroughPTF extends ProcessTableFunction<Row> {
+    public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+        collect(input);
+    }
+}
+
+@Test
+void testPassthrough() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                    .build()) {
+
+        harness.processElement(Row.of(42));
+        harness.processElement(Row.of(100));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output).containsExactly(Row.of(42), Row.of(100));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Testing Set-Semantic Tables with Partitioning
+
+For `SET_SEMANTIC_TABLE`, use `.withPartitionBy()` to configure partition columns:
+
+{{< tabs "set-semantic" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<doubled INT>")
+public class PartitionedPTF extends ProcessTableFunction<Row> {
+    public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+        int value = input.getFieldAs("value");
+        collect(Row.of(value * 2));
+    }
+}
+
+@Test
+void testPartitionedPTF() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                    .withPartitionBy("input", "key")
+                    .build()) {
+
+        harness.processElement(Row.of("A", 10));
+        harness.processElement(Row.of("B", 20));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+        assertThat(output.get(1)).isEqualTo(Row.of("B", 40));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Testing Multiple Table Arguments
+
+Use `processElementForTable()` to specify which table receives each row:
+
+{{< tabs "multi-table" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<output STRING>")
+public class JoinPTF extends ProcessTableFunction<Row> {
+    public void eval(
+            @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row left,
+            @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row right) {
+        if (left != null) {
+            collect(Row.of("LEFT: " + left));
+        }
+        if (right != null) {
+            collect(Row.of("RIGHT: " + right));
+        }
+    }
+}
+
+@Test
+void testMultiTable() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(JoinPTF.class)
+                    .withTableArgument("left", DataTypes.of("ROW<id INT, name STRING>"))
+                    .withPartitionBy("left", "id")
+                    .withTableArgument("right", DataTypes.of("ROW<id INT, city STRING>"))
+                    .withPartitionBy("right", "id")
+                    .build()) {
+
+        // Use processElementForTable() to target specific tables
+        harness.processElementForTable("left", Row.of(1, "Alice"));
+        harness.processElementForTable("right", Row.of(1, "Berlin"));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output.get(0)).isEqualTo(Row.of(1, null, "LEFT: +I[1, Alice]"));
+        assertThat(output.get(1)).isEqualTo(Row.of(null, 1, "RIGHT: +I[1, Berlin]"));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Testing with Scalar Arguments
+
+Use `.withScalarArgument()` to configure scalar parameter values:
+
+{{< tabs "scalar-args" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<value INT>")
+public class FilterPTF extends ProcessTableFunction<Row> {
+    public void eval(
+            @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+            @ArgumentHint(ArgumentTrait.SCALAR) int threshold) {
+        int value = input.getFieldAs("value");
+        if (value > threshold) {
+            collect(Row.of(value));
+        }
+    }
+}
+
+@Test
+void testFilter() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                    .withScalarArgument("threshold", 50)  // Configure scalar value
+                    .build()) {
+
+        harness.processElement(Row.of(30));
+        harness.processElement(Row.of(70));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output).containsExactly(Row.of(70));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+**Scalar-Only PTFs**: For PTFs with only scalar arguments, use `invoke()` to trigger evaluation:
+
+{{< tabs "scalar-only" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<sum INT>")
+public class AddPTF extends ProcessTableFunction<Row> {
+    public void eval(
+            @ArgumentHint(ArgumentTrait.SCALAR) int a,
+            @ArgumentHint(ArgumentTrait.SCALAR) int b) {
+        collect(Row.of(a + b));
+    }
+}
+
+@Test
+void testScalarOnly() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(AddPTF.class)
+                    .withScalarArgument("a", 5)
+                    .withScalarArgument("b", 7)
+                    .build()) {
+
+        harness.invoke();  // Use invoke() instead of processElement()

Review Comment:
   Maybe better naming?
   ```suggestion
           harness.process();
   ```
   What is the error behavior if you call this method but there are actually table args?



##########
docs/content/docs/dev/table/testing/ptf_test_harness.md:
##########
@@ -0,0 +1,361 @@
+---
+title: "Testing Process Table Functions"
+weight: 10
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Testing Process Table Functions
+
+The `ProcessTableFunctionTestHarness` provides a lightweight unit testing framework for Process Table
+Functions (PTFs). It allows you to test PTF logic without starting a full Flink cluster. It is useful
+for testing and validating PTF business logic, multi-table PTF behaviour and validating errors.
+
+For end-to-end integration testing with the full Flink planner and runtime, use integration tests
+instead.
+
+{{< top >}}
+
+## Quick Start
+
+{{< tabs "quickstart" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.*;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.runtime.functions.ProcessTableFunctionTestHarness;
+import org.apache.flink.types.Row;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+// PTF under test
+@DataTypeHint("ROW<doubled INT>")
+public class DoublePTF extends ProcessTableFunction<Row> {
+    public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+        int value = input.getFieldAs("value");
+        collect(Row.of(value * 2));
+    }
+}
+
+// Test
+@Test
+void testDoublePTF() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(DoublePTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                    .build()) {
+
+        harness.processElement(Row.of(5));
+        harness.processElement(Row.of(10));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output).hasSize(2);
+        assertThat(output.get(0)).isEqualTo(Row.of(10));
+        assertThat(output.get(1)).isEqualTo(Row.of(20));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+{{< top >}}
+
+## Common Testing Scenarios
+
+### Testing Row-Semantic Tables
+
+Use `.withTableArgument()` to configure the input table schema:
+
+{{< tabs "row-semantic" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<value INT>")
+public class PassthroughPTF extends ProcessTableFunction<Row> {
+    public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+        collect(input);
+    }
+}
+
+@Test
+void testPassthrough() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                    .build()) {
+
+        harness.processElement(Row.of(42));
+        harness.processElement(Row.of(100));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output).containsExactly(Row.of(42), Row.of(100));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Testing Set-Semantic Tables with Partitioning
+
+For `SET_SEMANTIC_TABLE`, use `.withPartitionBy()` to configure partition columns:
+
+{{< tabs "set-semantic" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<doubled INT>")
+public class PartitionedPTF extends ProcessTableFunction<Row> {
+    public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+        int value = input.getFieldAs("value");
+        collect(Row.of(value * 2));
+    }
+}
+
+@Test
+void testPartitionedPTF() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                    .withPartitionBy("input", "key")
+                    .build()) {
+
+        harness.processElement(Row.of("A", 10));
+        harness.processElement(Row.of("B", 20));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+        assertThat(output.get(1)).isEqualTo(Row.of("B", 40));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Testing Multiple Table Arguments
+
+Use `processElementForTable()` to specify which table receives each row:
+
+{{< tabs "multi-table" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<output STRING>")
+public class JoinPTF extends ProcessTableFunction<Row> {
+    public void eval(
+            @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row left,
+            @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row right) {
+        if (left != null) {
+            collect(Row.of("LEFT: " + left));
+        }
+        if (right != null) {
+            collect(Row.of("RIGHT: " + right));
+        }
+    }
+}
+
+@Test
+void testMultiTable() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(JoinPTF.class)
+                    .withTableArgument("left", DataTypes.of("ROW<id INT, name STRING>"))
+                    .withPartitionBy("left", "id")
+                    .withTableArgument("right", DataTypes.of("ROW<id INT, city STRING>"))
+                    .withPartitionBy("right", "id")
+                    .build()) {
+
+        // Use processElementForTable() to target specific tables
+        harness.processElementForTable("left", Row.of(1, "Alice"));
+        harness.processElementForTable("right", Row.of(1, "Berlin"));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output.get(0)).isEqualTo(Row.of(1, null, "LEFT: +I[1, Alice]"));
+        assertThat(output.get(1)).isEqualTo(Row.of(null, 1, "RIGHT: +I[1, Berlin]"));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Testing with Scalar Arguments
+
+Use `.withScalarArgument()` to configure scalar parameter values:
+
+{{< tabs "scalar-args" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<value INT>")
+public class FilterPTF extends ProcessTableFunction<Row> {
+    public void eval(
+            @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+            @ArgumentHint(ArgumentTrait.SCALAR) int threshold) {
+        int value = input.getFieldAs("value");
+        if (value > threshold) {
+            collect(Row.of(value));
+        }
+    }
+}
+
+@Test
+void testFilter() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                    .withScalarArgument("threshold", 50)  // Configure scalar value
+                    .build()) {
+
+        harness.processElement(Row.of(30));
+        harness.processElement(Row.of(70));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output).containsExactly(Row.of(70));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+**Scalar-Only PTFs**: For PTFs with only scalar arguments, use `invoke()` to trigger evaluation:
+
+{{< tabs "scalar-only" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<sum INT>")
+public class AddPTF extends ProcessTableFunction<Row> {
+    public void eval(
+            @ArgumentHint(ArgumentTrait.SCALAR) int a,
+            @ArgumentHint(ArgumentTrait.SCALAR) int b) {
+        collect(Row.of(a + b));
+    }
+}
+
+@Test
+void testScalarOnly() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(AddPTF.class)
+                    .withScalarArgument("a", 5)
+                    .withScalarArgument("b", 7)
+                    .build()) {
+
+        harness.invoke();  // Use invoke() instead of processElement()
+
+        List<Row> output = harness.getOutput();
+        assertThat(output).containsExactly(Row.of(12));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Configuring Table Argument Types
+
+The harness supports two ways to specify table argument types:
+
+{{< tabs "type-config" >}}
+{{< tab "Java" >}}
+```java
+// Option 1: Inline type annotation using DataTypeHint
+@DataTypeHint("ROW<doubled INT>")
+public class InlineTypePTF extends ProcessTableFunction<Row> {
+    public void eval(
+            @ArgumentHint(
+                value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+                type = @DataTypeHint("ROW<value INT>")
+            ) Row input) {
+        int value = input.getFieldAs("value");
+        collect(Row.of(value * 2));
+    }
+}
+
+@Test
+void testInlineType() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class).build()) {
+
+        harness.processElement(Row.of(5));
+        assertThat(harness.getOutput()).containsExactly(Row.of(10));
+    }
+}
+
+// Option 2: Builder configuration
+@Test
+void testBuilderType() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(DoublePTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                    .build()) {
+
+        harness.processElement(Row.of(5));
+        assertThat(harness.getOutput()).containsExactly(Row.of(10));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+**Structured Types**: The harness supports structured POJO types in addition to `Row`, both as PTF inputs
+and outputs:
+
+{{< tabs "pojo-types" >}}
+{{< tab "Java" >}}
+```java
+public static class Customer {
+    public String name;
+    public int age;
+}
+
+@DataTypeHint("ROW<name STRING, age INT>")

Review Comment:
   
   ```suggestion
   // no annotation necessary, all types can be derived from class information
   ```



##########
docs/content/docs/dev/table/testing/ptf_test_harness.md:
##########
@@ -0,0 +1,361 @@
+---
+title: "Testing Process Table Functions"
+weight: 10
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Testing Process Table Functions
+
+The `ProcessTableFunctionTestHarness` provides a lightweight unit testing framework for Process Table
+Functions (PTFs). It allows you to test PTF logic without starting a full Flink cluster. It is useful
+for testing and validating PTF business logic, multi-table PTF behaviour and validating errors.
+
+For end-to-end integration testing with the full Flink planner and runtime, use integration tests
+instead.
+
+{{< top >}}
+
+## Quick Start
+
+{{< tabs "quickstart" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.*;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.runtime.functions.ProcessTableFunctionTestHarness;
+import org.apache.flink.types.Row;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+// PTF under test
+@DataTypeHint("ROW<doubled INT>")
+public class DoublePTF extends ProcessTableFunction<Row> {
+    public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+        int value = input.getFieldAs("value");
+        collect(Row.of(value * 2));
+    }
+}
+
+// Test
+@Test
+void testDoublePTF() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(DoublePTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                    .build()) {
+
+        harness.processElement(Row.of(5));
+        harness.processElement(Row.of(10));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output).hasSize(2);
+        assertThat(output.get(0)).isEqualTo(Row.of(10));
+        assertThat(output.get(1)).isEqualTo(Row.of(20));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+{{< top >}}
+
+## Common Testing Scenarios
+
+### Testing Row-Semantic Tables
+
+Use `.withTableArgument()` to configure the input table schema:
+
+{{< tabs "row-semantic" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<value INT>")
+public class PassthroughPTF extends ProcessTableFunction<Row> {
+    public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+        collect(input);
+    }
+}
+
+@Test
+void testPassthrough() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                    .build()) {
+
+        harness.processElement(Row.of(42));
+        harness.processElement(Row.of(100));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output).containsExactly(Row.of(42), Row.of(100));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Testing Set-Semantic Tables with Partitioning
+
+For `SET_SEMANTIC_TABLE`, use `.withPartitionBy()` to configure partition columns:
+
+{{< tabs "set-semantic" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<doubled INT>")
+public class PartitionedPTF extends ProcessTableFunction<Row> {
+    public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+        int value = input.getFieldAs("value");
+        collect(Row.of(value * 2));
+    }
+}
+
+@Test
+void testPartitionedPTF() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                    .withPartitionBy("input", "key")
+                    .build()) {
+
+        harness.processElement(Row.of("A", 10));
+        harness.processElement(Row.of("B", 20));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+        assertThat(output.get(1)).isEqualTo(Row.of("B", 40));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Testing Multiple Table Arguments
+
+Use `processElementForTable()` to specify which table receives each row:
+
+{{< tabs "multi-table" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<output STRING>")
+public class JoinPTF extends ProcessTableFunction<Row> {
+    public void eval(
+            @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row left,
+            @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row right) {
+        if (left != null) {
+            collect(Row.of("LEFT: " + left));
+        }
+        if (right != null) {
+            collect(Row.of("RIGHT: " + right));
+        }
+    }
+}
+
+@Test
+void testMultiTable() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(JoinPTF.class)
+                    .withTableArgument("left", DataTypes.of("ROW<id INT, name STRING>"))
+                    .withPartitionBy("left", "id")
+                    .withTableArgument("right", DataTypes.of("ROW<id INT, city STRING>"))
+                    .withPartitionBy("right", "id")
+                    .build()) {
+
+        // Use processElementForTable() to target specific tables
+        harness.processElementForTable("left", Row.of(1, "Alice"));
+        harness.processElementForTable("right", Row.of(1, "Berlin"));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output.get(0)).isEqualTo(Row.of(1, null, "LEFT: +I[1, Alice]"));
+        assertThat(output.get(1)).isEqualTo(Row.of(null, 1, "RIGHT: +I[1, Berlin]"));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Testing with Scalar Arguments
+
+Use `.withScalarArgument()` to configure scalar parameter values:
+
+{{< tabs "scalar-args" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<value INT>")
+public class FilterPTF extends ProcessTableFunction<Row> {
+    public void eval(
+            @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+            @ArgumentHint(ArgumentTrait.SCALAR) int threshold) {

Review Comment:
   For simplification, this is not necessary
   ```suggestion
               int threshold) {
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "autophagy (via GitHub)" <gi...@apache.org>.
autophagy commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3217408307


##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            LogicalType logicalType = dataType.getLogicalType();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                int index = 0;
+                for (RowType.RowField field : rowType.getFields()) {
+                    if (field.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                int index = 0;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    if (attr.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a table argument without an explicit schema.
+         *
+         * <p>Use this for structured type arguments where the type can be inferred from the PTF's
+         * eval() signature. For Row arguments, use {@link #withTableArgument(String,
+         * AbstractDataType)} with an explicit schema.
+         *
+         * @param argumentName The table argument name
+         */
+        public Builder<OUT> withTableArgument(String argumentName) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName) || tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException("Argument already configured: " + argumentName);
+            }
+
+            ScalarArgumentConfiguration config = new ScalarArgumentConfiguration(value);
+            scalarArgs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Partitioning
+        // ---------------------------------------------------------------------
+
+        /**
+         * Specifies partition columns for a set semantic table.
+         *
+         * @param argumentName The table argument name
+         * @param columnNames The partition column names
+         * @return This builder
+         */
+        public Builder<OUT> withPartitionBy(String argumentName, String... columnNames) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(columnNames, "columnNames must not be null");
+            checkArgument(columnNames.length > 0, "Must specify at least one column");
+
+            if (partitionConfigs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Partition config already exists for: " + argumentName);
+            }
+
+            PartitionConfiguration config = new PartitionConfiguration(columnNames);
+            partitionConfigs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Build
+        // ---------------------------------------------------------------------
+
+        /**
+         * Builds the test harness.
+         *
+         * <p>This instantiates the PTF, validates configuration via type inference, creates the
+         * FunctionContext, and opens the function.
+         *
+         * @return The configured test harness
+         * @throws Exception If instantiation or opening fails
+         */
+        public ProcessTableFunctionTestHarness<OUT> build() throws Exception {
+            ProcessTableFunction<OUT> function = instantiateFunction();
+
+            List<ArgumentInfo> arguments = extractAndValidateTypeInference(function);
+
+            FunctionContext functionContext =
+                    new FunctionContext(null, Thread.currentThread().getContextClassLoader(), null);
+
+            Method evalMethod = findEvalMethod();
+
+            validateEvalMethodSupported(evalMethod, arguments);
+            validatePartitionConsistency(arguments);
+
+            // In cases where PTFs have only a single table argument, set it as a default
+            // and mark as a single table function so that processElement without specifying
+            // a table argument can be used.
+            String defaultTableArg = null;
+            boolean isSingleTableFunction = false;
+
+            List<ArgumentInfo> tableArguments = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    tableArguments.add(arg);
+                }
+            }
+
+            if (tableArguments.size() == 1) {
+                defaultTableArg = tableArguments.get(0).name;
+                isSingleTableFunction = true;
+            }
+
+            Map<String, DataStructureConverter<Object, Object>> inputConverters = new HashMap<>();
+            Map<String, DataStructureConverter<Object, Object>> outputConverters = new HashMap<>();
+            createConverters(arguments, inputConverters, outputConverters);
+
+            Map<String, ArgumentInfo> argumentsByName = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    argumentsByName.put(arg.name, arg);
+                }
+            }
+
+            return new ProcessTableFunctionTestHarness<>(
+                    function,
+                    functionContext,
+                    defaultTableArg,
+                    evalMethod,
+                    arguments,
+                    argumentsByName,
+                    isSingleTableFunction,
+                    extractScalarValues(arguments),
+                    inputConverters,
+                    outputConverters);
+        }
+
+        /** Extracts scalar values from configs, creating a map keyed by argument name. */
+        private Map<String, Object> extractScalarValues(List<ArgumentInfo> arguments) {
+            Map<String, Object> values = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    ScalarArgumentConfiguration config = scalarArgs.get(arg.name);
+                    if (config != null) {
+                        values.put(arg.name, config.value);
+                    }
+                }
+            }
+            return values;
+        }
+
+        /**
+         * Creates and initializes data structure converters for all table arguments.
+         *
+         * <p>For Row types, both input and output converters are the same (between Row and
+         * RowData).
+         *
+         * <p>For structured types, input converter uses Row types (Row to RowData), and the output
+         * converter uses the structured type.
+         */
+        private void createConverters(
+                List<ArgumentInfo> arguments,
+                Map<String, DataStructureConverter<Object, Object>> inputConverters,
+                Map<String, DataStructureConverter<Object, Object>> outputConverters) {
+            ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    String converterKey = arg.name;
+
+                    LogicalType logicalType = arg.dataType.getLogicalType();
+                    boolean isStructuredType =
+                            logicalType instanceof StructuredType
+                                    && ((StructuredType) logicalType)
+                                            .getImplementationClass()
+                                            .isPresent();
+
+                    if (isStructuredType) {
+                        StructuredType structuredType = (StructuredType) logicalType;
+                        List<RowType.RowField> rowFields = new ArrayList<>();
+                        for (StructuredType.StructuredAttribute attr :
+                                structuredType.getAttributes()) {
+                            rowFields.add(new RowType.RowField(attr.getName(), attr.getType()));
+                        }
+                        RowType rowType = new RowType(logicalType.isNullable(), rowFields);
+                        DataType rowDataType = TypeConversions.fromLogicalToDataType(rowType);
+
+                        DataStructureConverter<Object, Object> inputConverter =
+                                DataStructureConverters.getConverter(rowDataType);
+                        inputConverter.open(classLoader);
+
+                        DataStructureConverter<Object, Object> outputConverter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        outputConverter.open(classLoader);
+
+                        inputConverters.put(converterKey, inputConverter);
+                        outputConverters.put(converterKey, outputConverter);
+                    } else {
+                        DataStructureConverter<Object, Object> converter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        converter.open(classLoader);
+
+                        inputConverters.put(converterKey, converter);
+                        outputConverters.put(converterKey, converter);
+                    }
+                }
+            }
+        }
+
+        private Method findEvalMethod() throws NoSuchMethodException {
+            Method[] methods = functionClass.getMethods();
+            Method evalMethod = null;
+            int evalMethodCount = 0;
+
+            for (Method method : methods) {
+                if (method.getName().equals("eval")) {
+                    evalMethod = method;
+                    evalMethodCount++;
+                }
+            }
+
+            if (evalMethodCount == 0) {
+                throw new NoSuchMethodException(
+                        "No eval() method found in " + functionClass.getSimpleName());
+            } else if (evalMethodCount > 1) {
+                throw new IllegalStateException(
+                        "Multiple eval() methods found in "
+                                + functionClass.getSimpleName()
+                                + ". ProcessTableFunction must have exactly one eval() method.");
+            } else {
+                return evalMethod;
+            }
+        }
+
+        /**
+         * Validates that the eval() method doesn't use unsupported features. Temporary, until state
+         * and context is supported.
+         */
+        private void validateEvalMethodSupported(Method evalMethod, List<ArgumentInfo> arguments) {
+            Parameter[] parameters = evalMethod.getParameters();
+
+            for (int i = 0; i < parameters.length; i++) {
+                Parameter param = parameters[i];
+                Class<?> paramType = param.getType();
+
+                if (ProcessTableFunction.Context.class.isAssignableFrom(paramType)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support Context parameters. "
+                                            + "Found Context parameter at position %d in eval() method. ",
+                                    i));
+                }
+
+                if (param.isAnnotationPresent(StateHint.class)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support state parameters. "
+                                            + "Found @StateHint parameter at position %d in eval() method. ",
+                                    i));
+                }
+            }
+
+            // Parameter count should also match our arguments list
+            if (parameters.length != arguments.size()) {
+                throw new IllegalStateException(
+                        String.format(
+                                "Parameter count mismatch: eval() has %d parameters but only %d arguments were extracted. "
+                                        + "This may indicate missing @ArgumentHint annotations.",
+                                parameters.length, arguments.size()));
+            }
+        }
+
+        /**
+         * Validates that all SET_SEMANTIC_TABLE arguments with partitioning use consistent
+         * partitioning. All such arguments must have the same number of partition columns with
+         * matching data types.
+         */
+        private void validatePartitionConsistency(List<ArgumentInfo> arguments) {
+            List<ArgumentInfo> partitionedTables = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    partitionedTables.add(arg);
+                }
+            }
+
+            if (partitionedTables.size() <= 1) {
+                return;
+            }
+
+            ArgumentInfo first = partitionedTables.get(0);
+            int expectedPartitionColumnCount = first.partitionColumnNames.length;
+
+            for (int i = 1; i < partitionedTables.size(); i++) {
+                ArgumentInfo current = partitionedTables.get(i);
+
+                if (current.partitionColumnNames.length != expectedPartitionColumnCount) {
+                    throw new IllegalArgumentException(
+                            String.format(
+                                    "Inconsistent partitioning: Table argument '%s' has %d partition column(s), "
+                                            + "but table argument '%s' has %d partition column(s). "
+                                            + "All SET_SEMANTIC_TABLE arguments must use consistent partitioning "
+                                            + "(same number of columns and matching data types).",
+                                    first.name,
+                                    expectedPartitionColumnCount,
+                                    current.name,
+                                    current.partitionColumnNames.length));
+                }
+
+                // Check that partition column types match
+                for (int colIdx = 0; colIdx < expectedPartitionColumnCount; colIdx++) {
+                    String firstColName = first.partitionColumnNames[colIdx];
+                    String currentColName = current.partitionColumnNames[colIdx];
+                    DataType firstColType = extractPartitionColumnType(first, firstColName);
+                    DataType currentColType = extractPartitionColumnType(current, currentColName);
+
+                    if (!firstColType.getLogicalType().equals(currentColType.getLogicalType())) {
+                        throw new IllegalArgumentException(
+                                String.format(
+                                        "Inconsistent partitioning: Partition column '%s' of table argument '%s' "
+                                                + "has type %s, but partition column '%s' of table argument '%s' "
+                                                + "has type %s. All SET_SEMANTIC_TABLE arguments must use "
+                                                + "consistent partitioning (same number of columns and matching data types).",
+                                        firstColName,
+                                        first.name,
+                                        firstColType,
+                                        currentColName,
+                                        current.name,
+                                        currentColType));
+                    }
+                }
+            }
+        }
+
+        private DataType extractPartitionColumnType(ArgumentInfo arg, String columnName) {
+            if (arg.dataType instanceof FieldsDataType) {
+                FieldsDataType fieldsDataType = (FieldsDataType) arg.dataType;
+                LogicalType logicalType = fieldsDataType.getLogicalType();
+                List<DataType> fieldDataTypes = fieldsDataType.getChildren();
+
+                if (logicalType instanceof RowType) {
+                    RowType rowType = (RowType) logicalType;
+                    int fieldIndex = 0;
+                    for (RowType.RowField field : rowType.getFields()) {
+                        if (field.getName().equals(columnName)) {
+                            return fieldDataTypes.get(fieldIndex);
+                        }
+                        fieldIndex++;
+                    }
+                } else if (logicalType instanceof StructuredType) {
+                    StructuredType structuredType = (StructuredType) logicalType;
+                    int attrIndex = 0;
+                    for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                        if (attr.getName().equals(columnName)) {
+                            return fieldDataTypes.get(attrIndex);
+                        }
+                        attrIndex++;
+                    }
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format(
+                            "Cannot extract data type for partition column '%s' of argument '%s'",
+                            columnName, arg.name));
+        }
+
+        // ---------------------------------------------------------------------
+        // Type Inference
+        // ---------------------------------------------------------------------
+
+        /**
+         * Extracts type inference from the PTF and validates builder configuration.
+         *
+         * <p>Uses SystemTypeInference to validate things like reserved argument names, multiple
+         * table argument rules, static argument trait validation, etc.
+         */
+        private List<ArgumentInfo> extractAndValidateTypeInference(
+                ProcessTableFunction<OUT> function) {
+
+            DataTypeFactory dataTypeFactory = createDataTypeFactory();
+            TypeInference baseTypeInference = function.getTypeInference(dataTypeFactory);
+            TypeInference systemTypeInference =
+                    SystemTypeInference.of(FunctionKind.PROCESS_TABLE, baseTypeInference);
+
+            Optional<List<StaticArgument>> staticArgsOpt = systemTypeInference.getStaticArguments();
+            if (staticArgsOpt.isEmpty()) {
+                throw new IllegalStateException(
+                        "PTF does not provide static argument information. "
+                                + "Ensure @ArgumentHint annotations are present on all eval() parameters.");
+            }
+
+            List<StaticArgument> allArgs = staticArgsOpt.get();
+            List<StaticArgument> userArgs = new ArrayList<>();
+            for (StaticArgument arg : allArgs) {
+                if (!isSystemArgument(arg.getName())) {
+                    userArgs.add(arg);
+                }
+            }
+
+            List<ArgumentInfo> arguments = new ArrayList<>();
+
+            for (StaticArgument staticArg : userArgs) {
+                boolean isScalar = staticArg.getTraits().contains(StaticArgumentTrait.SCALAR);
+                boolean isTableArg =
+                        staticArg.getTraits().contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)
+                                || staticArg
+                                        .getTraits()
+                                        .contains(StaticArgumentTrait.SET_SEMANTIC_TABLE);
+
+                if (isScalar || isTableArg) {
+                    ArgumentInfo argInfo = buildArgumentInfo(staticArg);
+                    arguments.add(argInfo);
+                } else {
+                    throw new IllegalStateException(
+                            "Unknown argument type for StaticArgument. "
+                                    + "Expected SCALAR, ROW_SEMANTIC_TABLE, or SET_SEMANTIC_TABLE trait.");
+                }
+            }
+
+            validateArgumentConfiguration(arguments);
+
+            return arguments;
+        }
+
+        /** Checks if an argument name is a system-reserved argument. */
+        private boolean isSystemArgument(String argName) {
+            return SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_ON_TIME.equals(argName)
+                    || SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_UID.equals(argName);
+        }
+
+        private DataTypeFactory createDataTypeFactory() {
+            return new TestHarnessDataTypeFactory();
+        }
+
+        private ArgumentInfo buildArgumentInfo(StaticArgument staticArg) {
+
+            String name = staticArg.getName();
+            ArgumentTrait primaryTrait = extractPrimaryTrait(staticArg.getTraits());
+
+            DataType dataType;
+            if (primaryTrait == ArgumentTrait.SCALAR) {
+                Optional<DataType> dataTypeOpt = staticArg.getDataType();
+                if (dataTypeOpt.isPresent()) {
+                    dataType = dataTypeOpt.get();
+                } else {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "Cannot determine data type for scalar argument '%s'", name));
+                }
+            } else {
+                // For table arguments, check both annotation and builder config
+                Optional<DataType> annotationTypeOpt = staticArg.getDataType();
+                TableArgumentConfiguration config = tableArgs.get(name);
+
+                if (annotationTypeOpt.isPresent()
+                        && config != null
+                        && config.explicitType != null) {
+                    // Both specified - validate they match
+                    DataTypeFactory factory = createDataTypeFactory();
+                    DataType builderType = factory.createDataType(config.explicitType);
+                    DataType annotationType = annotationTypeOpt.get();
+
+                    if (!annotationType.equals(builderType)) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Type mismatch for table argument '%s': "
+                                                + "annotation declares type %s but builder declares type %s. "
+                                                + "Use either @ArgumentHint(type = ...) OR .withTableArgument(...), not both.",
+                                        name, annotationType, builderType));
+                    }
+                    dataType = annotationType;
+                } else if (annotationTypeOpt.isPresent()) {
+                    dataType = annotationTypeOpt.get();
+                } else if (config != null && config.explicitType != null) {
+                    DataTypeFactory factory = createDataTypeFactory();
+                    dataType = factory.createDataType(config.explicitType);
+                } else {
+                    // Try to infer from Java parameter class (for structured types)
+                    Optional<Class<?>> conversionClassOpt = staticArg.getConversionClass();
+                    if (conversionClassOpt.isPresent()) {
+                        DataTypeFactory factory = createDataTypeFactory();
+                        dataType = factory.createDataType(conversionClassOpt.get());
+                    } else {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Table argument '%s' requires explicit type configuration. "
+                                                + "Use @ArgumentHint(type = @DataTypeHint(\"ROW<...>\")) or "
+                                                + ".withTableArgument(\"%s\", DataTypes.of(\"ROW<...>\"))",
+                                        name, name));
+                    }
+                }
+            }
+
+            String[] partitionColumnNames = null;
+            if (primaryTrait == ArgumentTrait.SET_SEMANTIC_TABLE) {
+                boolean hasOptionalPartitionBy =
+                        staticArg.getTraits().contains(StaticArgumentTrait.OPTIONAL_PARTITION_BY);
+                partitionColumnNames =
+                        extractAndValidatePartitionColumns(name, dataType, hasOptionalPartitionBy);
+            }
+
+            boolean hasPassColumnsThrough =
+                    staticArg.getTraits().contains(StaticArgumentTrait.PASS_COLUMNS_THROUGH);

Review Comment:
   Not on purpose, no! I think this is because I realised late that I had missed the pass cols through trait handling, and so just added it on but you are right, only one of these modes can only apply at the same time so handling both independently makes no real sense.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "autophagy (via GitHub)" <gi...@apache.org>.
autophagy commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3217468026


##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls

Review Comment:
   No, you're right - I must have been confused here, the docs are pretty clear that the partition value is included for both https://nightlies.apache.org/flink/flink-docs-stable/docs/dev/table/functions/ptfs/#example-custom-join



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "fhueske (via GitHub)" <gi...@apache.org>.
fhueske commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3249331267


##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1298 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        this.argumentsByName = new HashMap<>();
+        for (ArgumentInfo arg : arguments) {
+            if (arg.name != null) {
+                argumentsByName.put(arg.name, arg);
+            }
+        }
+
+        final List<ArgumentInfo> tableArguments = new ArrayList<>();
+        for (ArgumentInfo arg : arguments) {
+            if (arg.isTableArgument) {
+                tableArguments.add(arg);
+            }
+        }
+
+        if (tableArguments.size() == 1) {
+            this.defaultTableArgument = tableArguments.get(0).name;
+            this.isSingleTableFunction = true;
+        } else {
+            this.defaultTableArgument = null;
+            this.isSingleTableFunction = false;
+        }
+
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);

Review Comment:
   nit:
   
   ```suggestion
   ```
   
   Can be set while iterating over `arguments` (line 135)



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -240,19 +240,64 @@ public void process() throws Exception {
 
         try {
             evalMethod.invoke(function, args);
+        } catch (IllegalArgumentException e) {
+            StringBuilder details = new StringBuilder();
+            details.append("Argument type mismatch during scalar-only PTF eval() invocation.\n");
+            details.append("Expected parameter types: ");
+            details.append(Arrays.toString(evalMethod.getParameterTypes()));
+            details.append("\nActual arguments:\n");
+            for (int i = 0; i < arguments.size(); i++) {
+                ArgumentInfo arg = arguments.get(i);
+                Object value = scalarArgumentValues.get(arg.name);
+                details.append(
+                        String.format(
+                                "  [%d] %s: %s (type: %s)\n",
+                                i,
+                                arg.name,
+                                value,
+                                value != null ? value.getClass().getName() : "null"));
+            }

Review Comment:
   Nit: move into a helper function and reuse it?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1298 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        this.argumentsByName = new HashMap<>();
+        for (ArgumentInfo arg : arguments) {
+            if (arg.name != null) {
+                argumentsByName.put(arg.name, arg);
+            }
+        }
+
+        final List<ArgumentInfo> tableArguments = new ArrayList<>();
+        for (ArgumentInfo arg : arguments) {
+            if (arg.isTableArgument) {
+                tableArguments.add(arg);

Review Comment:
   ```suggestion
                   tableArguments.add(arg);
                   this.hasTableArguments = true;
   ```



##########
flink-table/flink-table-test-utils/src/test/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarnessTest.java:
##########
@@ -0,0 +1,1021 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.api.ValidationException;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class ProcessTableFunctionTestHarnessTest {
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PassthroughPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** Filter PTF for testing scalar argument handling. */
+    @DataTypeHint("ROW<value INT>")
+    public static class FilterPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer threshold) {
+            // Use named field access - converter enriches Row with field names
+            int value = input.getFieldAs("value");
+            if (value >= threshold) {
+                collect(input);
+            }
+        }
+    }
+
+    /** PTF for testing transformation of output types. */
+    @DataTypeHint("ROW<doubled INT, original INT>")
+    public static class DoublePTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2, value));
+        }
+    }
+
+    /** PTF with for testing table argument names set via argument hints. */
+    @DataTypeHint("ROW<value INT>")
+    public static class ExplicitNamePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "customName")
+                        Row actualParamName) {
+            collect(actualParamName);
+        }
+    }
+
+    /** PTF with inline type annotation - no builder config needed. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class InlineTypePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(
+                                value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+                                type = @DataTypeHint("ROW<value INT>"))
+                        Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PartitionedPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+            collect(Row.of((Integer) input.getFieldAs("value")));
+        }
+    }
+
+    /**
+     * PTF with PASS_COLUMNS_THROUGH for validating that all input columns are prepended to output.
+     */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class PassColumnsThroughPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** PTF with OPTIONAL_PARTITION_BY for validating that partition setup can be omitted. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class OptionalPartitionPTF extends ProcessTableFunction<Row> {
+
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.OPTIONAL_PARTITION_BY
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** Simple POJO for testing structured type input/output. */
+    public static class User {
+        public String name;
+        public int age;
+
+        public User() {}
+
+        public User(String name, int age) {
+            this.name = name;
+            this.age = age;
+        }
+
+        @Override
+        public String toString() {
+            return "User{name='" + name + "', age=" + age + '}';
+        }
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o) {
+                return true;
+            }
+            if (o == null || getClass() != o.getClass()) {
+                return false;
+            }
+            User user = (User) o;
+            return age == user.age && java.util.Objects.equals(name, user.name);
+        }
+
+        @Override
+        public int hashCode() {
+            return java.util.Objects.hash(name, age);
+        }
+    }
+
+    /** PTF for testing structured type inputs. */
+    @DataTypeHint("ROW<name STRING, age INT>")
+    public static class UserPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            if (user.age >= 18) {
+                collect(Row.of(user.name, user.age));
+            }
+        }
+    }
+
+    /** PTF that transforms structured type inputs and outputs. */
+    public static class UserTransformPTF extends ProcessTableFunction<User> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            User transformed = new User(user.name, user.age + 1);
+            collect(transformed);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "on_time". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgOnTimePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "on_time")
+                        Row input) {
+            collect(input);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "uid". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgUidPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) String uid) {
+            collect(input);
+        }
+    }
+
+    /** Multi-table PTF for validating multi-input processing. */
+    @DataTypeHint("ROW<output STRING>")
+    public static class MultiTableUnionPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /**
+     * Multi-table PTF with one POJO and one Row argument, for testing partitioning with structured
+     * types.
+     */
+    @DataTypeHint("ROW<source STRING, age INT>")
+    public static class MixedTypeMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) User userTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rowTable) {
+            if (userTable != null) {
+                collect(Row.of("USER", userTable.age));
+            }
+            if (rowTable != null) {
+                collect(Row.of("ROW", rowTable.getFieldAs("age")));
+            }
+        }
+    }
+
+    /**
+     * Invalid PTF - uses PASS_COLUMNS_THROUGH with multiple table arguments (not allowed per Flink
+     * docs).
+     */
+    @DataTypeHint("ROW<output STRING>")
+    public static class InvalidPassColumnsThroughMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /** PTF with only scalar arguments, no tables. */
+    @DataTypeHint("ROW<sum INT>")
+    public static class ScalarOnlyPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer a,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer b) {
+            collect(Row.of(a + b));
+        }
+    }
+
+    /** PTF with Context parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithContext extends ProcessTableFunction<Row> {
+        public void eval(Context ctx, @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** PTF with State parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithState extends ProcessTableFunction<Row> {
+        public static class CountState {
+            public long counter = 0L;
+        }
+
+        public void eval(
+                @StateHint CountState state,
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Builder Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testBuilderRejectsDuplicateScalarArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("threshold", 50)
+                                    .withScalarArgument("threshold", 100);
+                        });
+
+        assertThat(exception.getMessage()).contains("threshold");
+    }
+
+    @Test
+    void testBuilderRejectsDuplicateTableArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableUnionPTF.class)
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, value INT>"));
+                        });
+
+        assertThat(exception.getMessage()).contains("leftTable");
+    }
+
+    @Test
+    void testBuilderRejectsMixedDuplicateArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("input", 42);
+                        });
+
+        assertThat(exception.getMessage()).contains("input");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentOnTime() {
+        // We should reject PTFs that use reserved argument name "on_time"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgOnTimePTF.class)
+                        .withTableArgument("on_time", DataTypes.of("ROW<id INT>"));
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("on_time");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentUid() {
+        // We should reject PTFs that use reserved argument name "uid"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgUidPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<id INT>"))
+                        .withScalarArgument("uid", "my-id");
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("uid");
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testExplicitNameTakesPrecedence() throws Exception {
+        // Verify that @ArgumentHint(name="customName") takes precedence over actual parameter
+        // name when processing elements and calling eval.
+
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ExplicitNamePTF.class)
+                        .withTableArgument("customName", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(42));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0).getField(0)).isEqualTo(42);
+            assertThat(output.get(1).getField(0)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testScalarOnlyPTF() throws Exception {

Review Comment:
   Add a test for a scalar-only PTF with wrong scalar arg types?



##########
flink-table/flink-table-test-utils/src/test/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarnessTest.java:
##########
@@ -0,0 +1,1021 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.api.ValidationException;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class ProcessTableFunctionTestHarnessTest {
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PassthroughPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** Filter PTF for testing scalar argument handling. */
+    @DataTypeHint("ROW<value INT>")
+    public static class FilterPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer threshold) {
+            // Use named field access - converter enriches Row with field names
+            int value = input.getFieldAs("value");
+            if (value >= threshold) {
+                collect(input);
+            }
+        }
+    }
+
+    /** PTF for testing transformation of output types. */
+    @DataTypeHint("ROW<doubled INT, original INT>")
+    public static class DoublePTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2, value));
+        }
+    }
+
+    /** PTF with for testing table argument names set via argument hints. */
+    @DataTypeHint("ROW<value INT>")
+    public static class ExplicitNamePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "customName")
+                        Row actualParamName) {
+            collect(actualParamName);
+        }
+    }
+
+    /** PTF with inline type annotation - no builder config needed. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class InlineTypePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(
+                                value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+                                type = @DataTypeHint("ROW<value INT>"))
+                        Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PartitionedPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+            collect(Row.of((Integer) input.getFieldAs("value")));
+        }
+    }
+
+    /**
+     * PTF with PASS_COLUMNS_THROUGH for validating that all input columns are prepended to output.
+     */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class PassColumnsThroughPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** PTF with OPTIONAL_PARTITION_BY for validating that partition setup can be omitted. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class OptionalPartitionPTF extends ProcessTableFunction<Row> {
+
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.OPTIONAL_PARTITION_BY
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** Simple POJO for testing structured type input/output. */
+    public static class User {
+        public String name;
+        public int age;
+
+        public User() {}
+
+        public User(String name, int age) {
+            this.name = name;
+            this.age = age;
+        }
+
+        @Override
+        public String toString() {
+            return "User{name='" + name + "', age=" + age + '}';
+        }
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o) {
+                return true;
+            }
+            if (o == null || getClass() != o.getClass()) {
+                return false;
+            }
+            User user = (User) o;
+            return age == user.age && java.util.Objects.equals(name, user.name);
+        }
+
+        @Override
+        public int hashCode() {
+            return java.util.Objects.hash(name, age);
+        }
+    }
+
+    /** PTF for testing structured type inputs. */
+    @DataTypeHint("ROW<name STRING, age INT>")
+    public static class UserPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            if (user.age >= 18) {
+                collect(Row.of(user.name, user.age));
+            }
+        }
+    }
+
+    /** PTF that transforms structured type inputs and outputs. */
+    public static class UserTransformPTF extends ProcessTableFunction<User> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            User transformed = new User(user.name, user.age + 1);
+            collect(transformed);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "on_time". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgOnTimePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "on_time")
+                        Row input) {
+            collect(input);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "uid". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgUidPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) String uid) {
+            collect(input);
+        }
+    }
+
+    /** Multi-table PTF for validating multi-input processing. */
+    @DataTypeHint("ROW<output STRING>")
+    public static class MultiTableUnionPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /**
+     * Multi-table PTF with one POJO and one Row argument, for testing partitioning with structured
+     * types.
+     */
+    @DataTypeHint("ROW<source STRING, age INT>")
+    public static class MixedTypeMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) User userTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rowTable) {
+            if (userTable != null) {
+                collect(Row.of("USER", userTable.age));
+            }
+            if (rowTable != null) {
+                collect(Row.of("ROW", rowTable.getFieldAs("age")));
+            }
+        }
+    }
+
+    /**
+     * Invalid PTF - uses PASS_COLUMNS_THROUGH with multiple table arguments (not allowed per Flink
+     * docs).
+     */
+    @DataTypeHint("ROW<output STRING>")
+    public static class InvalidPassColumnsThroughMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /** PTF with only scalar arguments, no tables. */
+    @DataTypeHint("ROW<sum INT>")
+    public static class ScalarOnlyPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer a,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer b) {
+            collect(Row.of(a + b));
+        }
+    }
+
+    /** PTF with Context parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithContext extends ProcessTableFunction<Row> {
+        public void eval(Context ctx, @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** PTF with State parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithState extends ProcessTableFunction<Row> {
+        public static class CountState {
+            public long counter = 0L;
+        }
+
+        public void eval(
+                @StateHint CountState state,
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Builder Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testBuilderRejectsDuplicateScalarArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("threshold", 50)
+                                    .withScalarArgument("threshold", 100);
+                        });
+
+        assertThat(exception.getMessage()).contains("threshold");
+    }
+
+    @Test
+    void testBuilderRejectsDuplicateTableArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableUnionPTF.class)
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, value INT>"));
+                        });
+
+        assertThat(exception.getMessage()).contains("leftTable");
+    }
+
+    @Test
+    void testBuilderRejectsMixedDuplicateArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("input", 42);
+                        });
+
+        assertThat(exception.getMessage()).contains("input");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentOnTime() {
+        // We should reject PTFs that use reserved argument name "on_time"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgOnTimePTF.class)
+                        .withTableArgument("on_time", DataTypes.of("ROW<id INT>"));
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("on_time");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentUid() {
+        // We should reject PTFs that use reserved argument name "uid"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgUidPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<id INT>"))
+                        .withScalarArgument("uid", "my-id");
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("uid");
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testExplicitNameTakesPrecedence() throws Exception {
+        // Verify that @ArgumentHint(name="customName") takes precedence over actual parameter
+        // name when processing elements and calling eval.
+
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ExplicitNamePTF.class)
+                        .withTableArgument("customName", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(42));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0).getField(0)).isEqualTo(42);
+            assertThat(output.get(1).getField(0)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testScalarOnlyPTF() throws Exception {
+        // Test scalar-only PTF with no table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ScalarOnlyPTF.class)
+                        .withScalarArgument("a", 10)
+                        .withScalarArgument("b", 20)
+                        .build()) {
+
+            harness.process();
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0).getField(0)).isEqualTo(30);
+        }
+    }
+
+    @Test
+    void testInvokeRejectsTableArguments() throws Exception {
+        // Verify that invoke() rejects PTFs with table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50)
+                        .build()) {
+
+            Exception exception =
+                    assertThrows(
+                            IllegalStateException.class,
+                            () -> {
+                                harness.process();
+                            });
+
+            assertThat(exception.getMessage()).contains("process() is only for scalar-only PTFs");
+        }
+    }
+
+    @Test
+    void testTableProcessingWithScalarArgument() throws Exception {

Review Comment:
   Add a test for a PTF with table and scalar args and a wrong scalar arg value type?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -309,26 +354,84 @@ private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Excep
 
         try {
             evalMethod.invoke(function, args);
+        } catch (IllegalArgumentException e) {

Review Comment:
   This should not happen for invalid static args (should be checked during harness configuration) but might this happen if we pass a wrong class for a table argument (Foo.class instead of Row.class)?



##########
flink-table/flink-table-test-utils/src/test/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarnessTest.java:
##########
@@ -0,0 +1,1021 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.api.ValidationException;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class ProcessTableFunctionTestHarnessTest {
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PassthroughPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** Filter PTF for testing scalar argument handling. */
+    @DataTypeHint("ROW<value INT>")
+    public static class FilterPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer threshold) {
+            // Use named field access - converter enriches Row with field names
+            int value = input.getFieldAs("value");
+            if (value >= threshold) {
+                collect(input);
+            }
+        }
+    }
+
+    /** PTF for testing transformation of output types. */
+    @DataTypeHint("ROW<doubled INT, original INT>")
+    public static class DoublePTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2, value));
+        }
+    }
+
+    /** PTF with for testing table argument names set via argument hints. */
+    @DataTypeHint("ROW<value INT>")
+    public static class ExplicitNamePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "customName")
+                        Row actualParamName) {
+            collect(actualParamName);
+        }
+    }
+
+    /** PTF with inline type annotation - no builder config needed. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class InlineTypePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(
+                                value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+                                type = @DataTypeHint("ROW<value INT>"))
+                        Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PartitionedPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+            collect(Row.of((Integer) input.getFieldAs("value")));
+        }
+    }
+
+    /**
+     * PTF with PASS_COLUMNS_THROUGH for validating that all input columns are prepended to output.
+     */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class PassColumnsThroughPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** PTF with OPTIONAL_PARTITION_BY for validating that partition setup can be omitted. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class OptionalPartitionPTF extends ProcessTableFunction<Row> {
+
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.OPTIONAL_PARTITION_BY
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** Simple POJO for testing structured type input/output. */
+    public static class User {
+        public String name;
+        public int age;
+
+        public User() {}
+
+        public User(String name, int age) {
+            this.name = name;
+            this.age = age;
+        }
+
+        @Override
+        public String toString() {
+            return "User{name='" + name + "', age=" + age + '}';
+        }
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o) {
+                return true;
+            }
+            if (o == null || getClass() != o.getClass()) {
+                return false;
+            }
+            User user = (User) o;
+            return age == user.age && java.util.Objects.equals(name, user.name);
+        }
+
+        @Override
+        public int hashCode() {
+            return java.util.Objects.hash(name, age);
+        }
+    }
+
+    /** PTF for testing structured type inputs. */
+    @DataTypeHint("ROW<name STRING, age INT>")
+    public static class UserPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            if (user.age >= 18) {
+                collect(Row.of(user.name, user.age));
+            }
+        }
+    }
+
+    /** PTF that transforms structured type inputs and outputs. */
+    public static class UserTransformPTF extends ProcessTableFunction<User> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            User transformed = new User(user.name, user.age + 1);
+            collect(transformed);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "on_time". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgOnTimePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "on_time")
+                        Row input) {
+            collect(input);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "uid". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgUidPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) String uid) {
+            collect(input);
+        }
+    }
+
+    /** Multi-table PTF for validating multi-input processing. */
+    @DataTypeHint("ROW<output STRING>")
+    public static class MultiTableUnionPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /**
+     * Multi-table PTF with one POJO and one Row argument, for testing partitioning with structured
+     * types.
+     */
+    @DataTypeHint("ROW<source STRING, age INT>")
+    public static class MixedTypeMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) User userTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rowTable) {
+            if (userTable != null) {
+                collect(Row.of("USER", userTable.age));
+            }
+            if (rowTable != null) {
+                collect(Row.of("ROW", rowTable.getFieldAs("age")));
+            }
+        }
+    }
+
+    /**
+     * Invalid PTF - uses PASS_COLUMNS_THROUGH with multiple table arguments (not allowed per Flink
+     * docs).
+     */
+    @DataTypeHint("ROW<output STRING>")
+    public static class InvalidPassColumnsThroughMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /** PTF with only scalar arguments, no tables. */
+    @DataTypeHint("ROW<sum INT>")
+    public static class ScalarOnlyPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer a,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer b) {
+            collect(Row.of(a + b));
+        }
+    }
+
+    /** PTF with Context parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithContext extends ProcessTableFunction<Row> {
+        public void eval(Context ctx, @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** PTF with State parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithState extends ProcessTableFunction<Row> {
+        public static class CountState {
+            public long counter = 0L;
+        }
+
+        public void eval(
+                @StateHint CountState state,
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Builder Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testBuilderRejectsDuplicateScalarArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("threshold", 50)
+                                    .withScalarArgument("threshold", 100);
+                        });
+
+        assertThat(exception.getMessage()).contains("threshold");
+    }
+
+    @Test
+    void testBuilderRejectsDuplicateTableArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableUnionPTF.class)
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, value INT>"));
+                        });
+
+        assertThat(exception.getMessage()).contains("leftTable");
+    }
+
+    @Test
+    void testBuilderRejectsMixedDuplicateArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("input", 42);
+                        });
+
+        assertThat(exception.getMessage()).contains("input");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentOnTime() {
+        // We should reject PTFs that use reserved argument name "on_time"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgOnTimePTF.class)
+                        .withTableArgument("on_time", DataTypes.of("ROW<id INT>"));
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("on_time");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentUid() {
+        // We should reject PTFs that use reserved argument name "uid"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgUidPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<id INT>"))
+                        .withScalarArgument("uid", "my-id");
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("uid");
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testExplicitNameTakesPrecedence() throws Exception {
+        // Verify that @ArgumentHint(name="customName") takes precedence over actual parameter
+        // name when processing elements and calling eval.
+
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ExplicitNamePTF.class)
+                        .withTableArgument("customName", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(42));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0).getField(0)).isEqualTo(42);
+            assertThat(output.get(1).getField(0)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testScalarOnlyPTF() throws Exception {
+        // Test scalar-only PTF with no table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ScalarOnlyPTF.class)
+                        .withScalarArgument("a", 10)
+                        .withScalarArgument("b", 20)
+                        .build()) {
+
+            harness.process();
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0).getField(0)).isEqualTo(30);
+        }
+    }
+
+    @Test
+    void testInvokeRejectsTableArguments() throws Exception {
+        // Verify that invoke() rejects PTFs with table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50)
+                        .build()) {
+
+            Exception exception =
+                    assertThrows(
+                            IllegalStateException.class,
+                            () -> {
+                                harness.process();
+                            });
+
+            assertThat(exception.getMessage()).contains("process() is only for scalar-only PTFs");
+        }
+    }
+
+    @Test
+    void testTableProcessingWithScalarArgument() throws Exception {
+        // Test a PTF that uses a scalar parameter
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50) // Scalar argument: threshold = 50
+                        .build()) {
+
+            harness.processElement(Row.of(25));
+            harness.processElement(Row.of(75));
+            harness.processElement(Row.of(50));
+            harness.processElement(Row.of(10));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0).getField(0)).isEqualTo(75);
+            assertThat(output.get(1).getField(0)).isEqualTo(50);
+            assertThat(output.get(2).getField(0)).isEqualTo(100);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Trait Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testProcessElementWithRowKind() throws Exception {
+        // Verify RowKind is preserved through processing (ROW_SEMANTIC_TABLE)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(RowKind.INSERT, 10);
+            harness.processElement(RowKind.UPDATE_BEFORE, 15);
+            harness.processElement(RowKind.UPDATE_AFTER, 20);
+            harness.processElement(RowKind.DELETE, 30);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+            assertThat(output.get(0).getKind()).isEqualTo(RowKind.INSERT);
+            assertThat(output.get(0).getField(0)).isEqualTo(10);
+            assertThat(output.get(1).getKind()).isEqualTo(RowKind.UPDATE_BEFORE);
+            assertThat(output.get(1).getField(0)).isEqualTo(15);
+            assertThat(output.get(2).getKind()).isEqualTo(RowKind.UPDATE_AFTER);
+            assertThat(output.get(2).getField(0)).isEqualTo(20);
+            assertThat(output.get(3).getKind()).isEqualTo(RowKind.DELETE);
+            assertThat(output.get(3).getField(0)).isEqualTo(30);
+        }
+    }
+
+    @Test
+    void testPassColumnsThroughTrait() throws Exception {
+        // Verify PASS_COLUMNS_THROUGH prepends ALL input columns (not just partition keys)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassColumnsThroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 10, 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("B", 20, 40));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithoutPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY allows omitting partition configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+            harness.processElement(Row.of("C", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of(20));
+            assertThat(output.get(1)).isEqualTo(Row.of(40));
+            assertThat(output.get(2)).isEqualTo(Row.of(60));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY still works when partition is configured
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("A", 5));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("A", 10));
+            assertThat(output.get(2)).isEqualTo(Row.of("B", 40));
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Data Type Conversion Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testNamedRowFieldOrdering() throws Exception {
+        // Test what happens when Row field order differs from DataType schema order
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row rowA = Row.withNames();
+            rowA.setField("value", 100);
+            rowA.setField("user", "Alice");
+
+            harness.processElement(rowA);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+
+            // Positional access follows schema order
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testPositionalRowWithWrongTypeOrder() throws Exception {
+        // Verify that type mismatches are caught when Row values don't match schema types
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row wrongOrderRow = Row.of(10, "Alice");
+
+            Exception exception =
+                    assertThrows(
+                            ClassCastException.class, () -> harness.processElement(wrongOrderRow));
+
+            assertThat(exception.getMessage()).contains("Integer");
+            assertThat(exception.getMessage()).contains("String");
+            assertThat(exception.getMessage()).contains("cannot be cast");
+        }
+    }
+
+    @Test
+    void testStructuredTypeInput() throws Exception {
+        // Test that a PTF can declare an input type as a structured type,
+        // and that the harness can handle the conversion from Row into
+        // that type.
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+            harness.processElement(Row.of("Bob", 17));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(25);
+        }
+    }
+
+    @Test
+    void testStructuredTypeInputAndOutput() throws Exception {
+        // Test PTF with structured type inputs and outputs
+        try (ProcessTableFunctionTestHarness<User> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserTransformPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+
+            List<User> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            User result = output.get(0);
+            assertThat(result.getClass()).isEqualTo(User.class);
+            assertThat(result.name).isEqualTo("Alice");
+            assertThat(result.age).isEqualTo(26);
+        }
+    }
+
+    @Test
+    void testInlineTypeAnnotation() throws Exception {
+        // Verify that PTFs can declare table argument types via @ArgumentHint(type = ...)
+        // without needing .withTableArgument() configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class).build()) {
+
+            harness.processElement(Row.of(5));
+            harness.processElement(Row.of(10));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0)).isEqualTo(Row.of(10));
+            assertThat(output.get(1)).isEqualTo(Row.of(20));
+        }
+    }
+
+    @Test
+    void testInlineTypeMatchesBuilderConfig() throws Exception {
+        // Verify that when both inline annotation and builder config are provided with matching
+        // types, the harness builds successfully
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(7));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0)).isEqualTo(Row.of(14));
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Partitioning Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testSetSemanticWithPartitionByName() throws Exception {
+        // Verify set-semantic table with partition configuration by column name
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key") // Partition by "key" column name
+                        .build()) {
+
+            harness.processElement(Row.of("X", 10));
+            harness.processElement(Row.of("Y", 20));
+            harness.processElement(Row.of("X", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0)).isEqualTo(Row.of("X", 10));
+            assertThat(output.get(1)).isEqualTo(Row.of("Y", 20));
+            assertThat(output.get(2)).isEqualTo(Row.of("X", 30));
+        }
+    }
+
+    @Test
+    void testSetSemanticWithMultiplePartitionColumns() throws Exception {
+        // Verify composite partition key (multiple columns)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument(
+                                "input",
+                                DataTypes.of("ROW<region STRING, country STRING, value INT>"))
+                        .withPartitionBy("input", "region", "country")
+                        .build()) {
+
+            harness.processElement(Row.of("EU", "DE", 100));
+            harness.processElement(Row.of("EU", "DE", 200));
+            harness.processElement(Row.of("EU", "FR", 300));
+            harness.processElement(Row.of("US", "NY", 400));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+            assertThat(output.get(0)).isEqualTo(Row.of("EU", "DE", 100));
+            assertThat(output.get(1)).isEqualTo(Row.of("EU", "DE", 200));
+            assertThat(output.get(2)).isEqualTo(Row.of("EU", "FR", 300));
+            assertThat(output.get(3)).isEqualTo(Row.of("US", "NY", 400));
+        }
+    }
+
+    @Test
+    void testSetSemanticWithSelectivePartitioning() throws Exception {
+        // Verify that only partition columns are automatically included in output
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument(
+                                "input",
+                                DataTypes.of(
+                                        "ROW<id INT, region STRING, country STRING, city STRING, value INT>"))
+                        .withPartitionBy("input", "region")
+                        .build()) {
+
+            harness.processElement(Row.of(1, "EU", "DE", "Berlin", 100));
+            harness.processElement(Row.of(4, "US", "CA", "LA", 200));
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output.get(0)).isEqualTo(Row.of("EU", 100));
+            assertThat(output.get(1)).isEqualTo(Row.of("US", 200));
+        }
+    }
+
+    @Test
+    void testMultipleSetSemanticTablesWithMatchingPartitionKeys() throws Exception {
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(MultiTableUnionPTF.class)
+                        .withTableArgument("leftTable", DataTypes.of("ROW<name STRING, score INT>"))
+                        .withPartitionBy("leftTable", "name")
+                        .withTableArgument(
+                                "rightTable", DataTypes.of("ROW<name STRING, city STRING>"))
+                        .withPartitionBy("rightTable", "name")
+                        .build()) {
+
+            harness.processElementForTable("leftTable", Row.of("Alice", 100));
+            harness.processElementForTable("leftTable", Row.of("Bob", 200));
+
+            harness.processElementForTable("rightTable", Row.of("Alice", "Berlin"));
+            harness.processElementForTable("rightTable", Row.of("Bob", "London"));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+
+            assertThat(output.get(0).getField(0)).isEqualTo("Alice");
+            assertThat(output.get(0).getField(1)).isEqualTo("Alice");
+            assertThat(output.get(0).getField(2)).isEqualTo("LEFT: +I[Alice, 100]");
+
+            assertThat(output.get(1).getField(0)).isEqualTo("Bob");
+            assertThat(output.get(1).getField(1)).isEqualTo("Bob");
+            assertThat(output.get(1).getField(2)).isEqualTo("LEFT: +I[Bob, 200]");
+
+            assertThat(output.get(2).getField(0)).isEqualTo("Alice");
+            assertThat(output.get(2).getField(1)).isEqualTo("Alice");
+            assertThat(output.get(2).getField(2)).isEqualTo("RIGHT: +I[Alice, Berlin]");
+
+            assertThat(output.get(3).getField(0)).isEqualTo("Bob");
+            assertThat(output.get(3).getField(1)).isEqualTo("Bob");
+            assertThat(output.get(3).getField(2)).isEqualTo("RIGHT: +I[Bob, London]");
+        }
+    }
+
+    @Test
+    void testMultipleSetSemanticTablesWithStructuredTypePartitioning() throws Exception {
+        // Verify that multi-table PTFs work when one argument is a structured type
+        // and another is a Row, both partitioned by the same field type
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(MixedTypeMultiTablePTF.class)
+                        .withTableArgument("userTable")
+                        .withPartitionBy("userTable", "age")
+                        .withTableArgument(
+                                "rowTable", DataTypes.of("ROW<name STRING, age INT NOT NULL>"))
+                        .withPartitionBy("rowTable", "age")
+                        .build()) {
+
+            harness.processElementForTable("userTable", Row.of("Alice", 25));
+            harness.processElementForTable("rowTable", Row.of("Bob", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);

Review Comment:
   check if the output is as expected?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -309,26 +354,84 @@ private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Excep
 
         try {
             evalMethod.invoke(function, args);
+        } catch (IllegalArgumentException e) {

Review Comment:
   is there a test for these errors?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -240,19 +240,64 @@ public void process() throws Exception {
 
         try {
             evalMethod.invoke(function, args);
+        } catch (IllegalArgumentException e) {

Review Comment:
   Are there unit tests to validate the message for these errors?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -240,19 +240,64 @@ public void process() throws Exception {
 
         try {
             evalMethod.invoke(function, args);
+        } catch (IllegalArgumentException e) {

Review Comment:
   Just noticed, this should not happen because we check the static arg types already during harness configuration,  correct?



##########
docs/content.zh/docs/dev/table/functions/ptfs.md:
##########
@@ -2034,3 +2034,321 @@ Limitations
 PTFs are in an early stage. The following limitations apply:
 - PTFs cannot run in batch mode.
 - Broadcast state
+
+Testing Process Table Functions
+-------------------------------
+
+The `ProcessTableFunctionTestHarness` provides a lightweight unit testing framework for Process Table
+Functions (PTFs). It is useful for unit testing and validating PTF business logic, multi-table PTF
+behaviour and validating errors.
+
+For end-to-end integration testing with the full Flink planner and runtime, use integration tests
+instead.
+
+{{< top >}}
+
+### Quick Start
+
+{{< tabs "quickstart" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.*;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.runtime.functions.ProcessTableFunctionTestHarness;
+import org.apache.flink.types.Row;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+// PTF under test
+@DataTypeHint("ROW<doubled INT>")
+public class DoublePTF extends ProcessTableFunction<Row> {
+  public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+    int value = input.getFieldAs("value");
+    collect(Row.of(value * 2));
+  }
+}
+
+// Test
+@Test
+void testDoublePTF() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+    ProcessTableFunctionTestHarness.ofClass(DoublePTF.class)
+    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+    .build()) {
+
+    harness.processElement(Row.of(5));
+    harness.processElement(Row.of(10));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).hasSize(2);
+    assertThat(output.get(0)).isEqualTo(Row.of(10));
+    assertThat(output.get(1)).isEqualTo(Row.of(20));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+{{< top >}}
+
+### Common Testing Scenarios
+
+#### Testing Row-Semantic Tables
+
+Use `.withTableArgument()` to configure the input table schema:
+
+{{< tabs "row-semantic" >}}
+{{< tab "Java" >}}
+```java
+public class PassthroughPTF extends ProcessTableFunction<Integer> {
+  public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+    collect(input.getFieldAs("value"));
+  }
+}
+
+@Test
+void testPassthrough() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+    ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+    .build()) {
+
+    harness.processElement(Row.of(42));
+    harness.processElement(Row.of(100));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).containsExactly(42, 100);
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Testing Set-Semantic Tables with Partitioning
+
+For `SET_SEMANTIC_TABLE`, use `.withPartitionBy()` to configure partition columns:
+
+{{< tabs "set-semantic" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<doubled INT>")
+public class PartitionedPTF extends ProcessTableFunction<Row> {
+  public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+    int value = input.getFieldAs("value");
+    collect(Row.of(value * 2));
+  }
+}
+
+@Test
+void testPartitionedPTF() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+    ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+    .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+    .withPartitionBy("input", "key")
+    .build()) {
+
+    harness.processElement(Row.of("A", 10));
+    harness.processElement(Row.of("B", 20));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+    assertThat(output.get(1)).isEqualTo(Row.of("B", 40));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Testing Multiple Table Arguments
+
+Use `processElementForTable()` to specify which table receives each row:
+
+{{< tabs "multi-table" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<output STRING>")
+public class JoinPTF extends ProcessTableFunction<Row> {
+  public void eval(
+    @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row left,
+    @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row right) {
+    if (left != null) {
+      collect(Row.of("LEFT: " + left));
+    }
+    if (right != null) {
+      collect(Row.of("RIGHT: " + right));
+    }
+  }
+}
+
+@Test
+void testMultiTable() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+    ProcessTableFunctionTestHarness.ofClass(JoinPTF.class)
+    .withTableArgument("left", DataTypes.of("ROW<id INT, name STRING>"))
+    .withPartitionBy("left", "id")
+    .withTableArgument("right", DataTypes.of("ROW<id INT, city STRING>"))
+    .withPartitionBy("right", "id")
+    .build()) {
+
+    // Use processElementForTable() to target specific tables
+    harness.processElementForTable("left", Row.of(1, "Alice"));
+    harness.processElementForTable("right", Row.of(1, "Berlin"));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output.get(0)).isEqualTo(Row.of(1, null, "LEFT: +I[1, Alice]"));
+    assertThat(output.get(1)).isEqualTo(Row.of(null, 1, "RIGHT: +I[1, Berlin]"));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Testing with Scalar Arguments
+
+Use `.withScalarArgument()` to configure scalar parameter values:
+
+{{< tabs "scalar-args" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<value INT>")
+public class FilterPTF extends ProcessTableFunction<Row> {
+  public void eval(
+    @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+    int threshold) {
+    int value = input.getFieldAs("value");
+    if (value > threshold) {
+      collect(Row.of(value));
+    }
+  }
+}
+
+@Test
+void testFilter() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+    ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+    .withScalarArgument("threshold", 50) // Configure scalar value
+    .build()) {
+
+    harness.processElement(Row.of(30));
+    harness.processElement(Row.of(70));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).containsExactly(Row.of(70));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+**Scalar-Only PTFs**: For PTFs with only scalar arguments, use `process()` to trigger evaluation:
+
+{{< tabs "scalar-only" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<sum INT>")
+public class AddPTF extends ProcessTableFunction<Row> {
+  public void eval(int a, int b) {
+    collect(Row.of(a + b));
+  }
+}
+
+@Test
+void testScalarOnly() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+    ProcessTableFunctionTestHarness.ofClass(AddPTF.class)
+    .withScalarArgument("a", 5)
+    .withScalarArgument("b", 7)
+    .build()) {
+
+    harness.process(); // Use process() instead of processElement()
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).containsExactly(Row.of(12));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Configuring Table Argument Types
+
+In contexts where the harness can't infer the table argument types for table arguments (when using unannotated `Row` inputs,
+for example), it is possible to specify the input table type during the builder setup.
+
+{{< tabs "type-config" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<doubled INT, original INT>")
+public static class DoublePTF extends ProcessTableFunction<Row> {
+  public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {

Review Comment:
   nit
   ```suggestion
     // NOTE: ArgumentHint does not provide a type for input argument. 
     //       Since harness cannot automatically infer the type, it needs to be explicitly declared.
     public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
   ```
   add comment to highlight what is "missing" needs to be declared for the harness?



##########
docs/content.zh/docs/dev/table/functions/ptfs.md:
##########
@@ -2034,3 +2034,321 @@ Limitations
 PTFs are in an early stage. The following limitations apply:
 - PTFs cannot run in batch mode.
 - Broadcast state
+
+Testing Process Table Functions
+-------------------------------
+
+The `ProcessTableFunctionTestHarness` provides a lightweight unit testing framework for Process Table
+Functions (PTFs). It is useful for unit testing and validating PTF business logic, multi-table PTF
+behaviour and validating errors.
+
+For end-to-end integration testing with the full Flink planner and runtime, use integration tests
+instead.
+
+{{< top >}}
+
+### Quick Start
+
+{{< tabs "quickstart" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.*;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.runtime.functions.ProcessTableFunctionTestHarness;
+import org.apache.flink.types.Row;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+// PTF under test
+@DataTypeHint("ROW<doubled INT>")
+public class DoublePTF extends ProcessTableFunction<Row> {
+  public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+    int value = input.getFieldAs("value");
+    collect(Row.of(value * 2));
+  }
+}
+
+// Test
+@Test
+void testDoublePTF() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+    ProcessTableFunctionTestHarness.ofClass(DoublePTF.class)
+    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+    .build()) {
+
+    harness.processElement(Row.of(5));
+    harness.processElement(Row.of(10));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).hasSize(2);
+    assertThat(output.get(0)).isEqualTo(Row.of(10));
+    assertThat(output.get(1)).isEqualTo(Row.of(20));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+{{< top >}}
+
+### Common Testing Scenarios
+
+#### Testing Row-Semantic Tables
+
+Use `.withTableArgument()` to configure the input table schema:
+
+{{< tabs "row-semantic" >}}
+{{< tab "Java" >}}
+```java
+public class PassthroughPTF extends ProcessTableFunction<Integer> {
+  public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+    collect(input.getFieldAs("value"));
+  }
+}
+
+@Test
+void testPassthrough() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+    ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+    .build()) {
+
+    harness.processElement(Row.of(42));
+    harness.processElement(Row.of(100));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).containsExactly(42, 100);
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Testing Set-Semantic Tables with Partitioning
+
+For `SET_SEMANTIC_TABLE`, use `.withPartitionBy()` to configure partition columns:
+
+{{< tabs "set-semantic" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<doubled INT>")
+public class PartitionedPTF extends ProcessTableFunction<Row> {
+  public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+    int value = input.getFieldAs("value");
+    collect(Row.of(value * 2));
+  }
+}
+
+@Test
+void testPartitionedPTF() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+    ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+    .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+    .withPartitionBy("input", "key")
+    .build()) {
+
+    harness.processElement(Row.of("A", 10));
+    harness.processElement(Row.of("B", 20));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+    assertThat(output.get(1)).isEqualTo(Row.of("B", 40));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Testing Multiple Table Arguments
+
+Use `processElementForTable()` to specify which table receives each row:
+
+{{< tabs "multi-table" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<output STRING>")
+public class JoinPTF extends ProcessTableFunction<Row> {
+  public void eval(
+    @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row left,
+    @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row right) {
+    if (left != null) {
+      collect(Row.of("LEFT: " + left));
+    }
+    if (right != null) {
+      collect(Row.of("RIGHT: " + right));
+    }
+  }
+}
+
+@Test
+void testMultiTable() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+    ProcessTableFunctionTestHarness.ofClass(JoinPTF.class)
+    .withTableArgument("left", DataTypes.of("ROW<id INT, name STRING>"))
+    .withPartitionBy("left", "id")
+    .withTableArgument("right", DataTypes.of("ROW<id INT, city STRING>"))
+    .withPartitionBy("right", "id")
+    .build()) {
+
+    // Use processElementForTable() to target specific tables
+    harness.processElementForTable("left", Row.of(1, "Alice"));
+    harness.processElementForTable("right", Row.of(1, "Berlin"));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output.get(0)).isEqualTo(Row.of(1, null, "LEFT: +I[1, Alice]"));
+    assertThat(output.get(1)).isEqualTo(Row.of(null, 1, "RIGHT: +I[1, Berlin]"));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Testing with Scalar Arguments
+
+Use `.withScalarArgument()` to configure scalar parameter values:
+
+{{< tabs "scalar-args" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<value INT>")
+public class FilterPTF extends ProcessTableFunction<Row> {
+  public void eval(
+    @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+    int threshold) {
+    int value = input.getFieldAs("value");
+    if (value > threshold) {
+      collect(Row.of(value));
+    }
+  }
+}
+
+@Test
+void testFilter() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+    ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+    .withScalarArgument("threshold", 50) // Configure scalar value
+    .build()) {
+
+    harness.processElement(Row.of(30));
+    harness.processElement(Row.of(70));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).containsExactly(Row.of(70));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+**Scalar-Only PTFs**: For PTFs with only scalar arguments, use `process()` to trigger evaluation:
+
+{{< tabs "scalar-only" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<sum INT>")
+public class AddPTF extends ProcessTableFunction<Row> {
+  public void eval(int a, int b) {
+    collect(Row.of(a + b));
+  }
+}
+
+@Test
+void testScalarOnly() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+    ProcessTableFunctionTestHarness.ofClass(AddPTF.class)
+    .withScalarArgument("a", 5)
+    .withScalarArgument("b", 7)
+    .build()) {
+
+    harness.process(); // Use process() instead of processElement()
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).containsExactly(Row.of(12));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Configuring Table Argument Types
+
+In contexts where the harness can't infer the table argument types for table arguments (when using unannotated `Row` inputs,
+for example), it is possible to specify the input table type during the builder setup.
+
+{{< tabs "type-config" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<doubled INT, original INT>")
+public static class DoublePTF extends ProcessTableFunction<Row> {
+  public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+    int value = (Integer) input.getField(0);
+    collect(Row.of(value * 2, value));
+  }
+}
+
+@Test
+void testBuilderType() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+    ProcessTableFunctionTestHarness.ofClass(DoublePTF.class)
+    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+    .build()) {
+
+    harness.processElement(Row.of(5));
+    assertThat(harness.getOutput()).containsExactly(Row.of(10));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+**Structured Types**: The harness supports structured POJO types in addition to `Row`, both as PTF inputs
+and outputs:
+
+{{< tabs "pojo-types" >}}
+{{< tab "Java" >}}
+```java
+public static class Customer {
+  public String name;
+  public int age;
+}
+
+public class CustomerPTF extends ProcessTableFunction<Customer> {
+  public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Customer c) {
+    collect(c);
+  }
+}
+
+@Test
+void testPOJO() throws Exception {
+  try (ProcessTableFunctionTestHarness<Customer> harness =
+      ProcessTableFunctionTestHarness.ofClass(CustomerPTF.class)
+          .withTableArgument("input", DataTypes.of(Customer.class))
+          .build()) {
+
+    harness.processElement(Row.of("Alice", 30));
+
+    List<Customer> output = harness.getOutput();
+    assertThat(output.get(0).name).isEqualTo("Alice");
+    assertThat(output.get(0).age).isEqualTo(30);
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+{{< top >}}
+
+### PTF Features Unsupported by the TestHarness
+
+| Feature                                                     | Support                   |

Review Comment:
   Nit: 
   The heading already says "unsupported", so the "Support" column is a bit redundant.
   Could be a simple bullet list instead of a table.



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1298 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        this.argumentsByName = new HashMap<>();
+        for (ArgumentInfo arg : arguments) {
+            if (arg.name != null) {
+                argumentsByName.put(arg.name, arg);
+            }
+        }
+
+        final List<ArgumentInfo> tableArguments = new ArrayList<>();
+        for (ArgumentInfo arg : arguments) {
+            if (arg.isTableArgument) {
+                tableArguments.add(arg);
+            }
+        }
+
+        if (tableArguments.size() == 1) {
+            this.defaultTableArgument = tableArguments.get(0).name;
+            this.isSingleTableFunction = true;
+        } else {
+            this.defaultTableArgument = null;
+            this.isSingleTableFunction = false;
+        }
+
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        Object[] args = arguments.stream().map(arg -> scalarArgumentValues.get(arg.name)).toArray();
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (IllegalArgumentException e) {
+            StringBuilder details = new StringBuilder();
+            details.append("Argument type mismatch during scalar-only PTF eval() invocation.\n");
+            details.append("Expected parameter types: ");
+            details.append(Arrays.toString(evalMethod.getParameterTypes()));
+            details.append("\nActual arguments:\n");
+            for (int i = 0; i < arguments.size(); i++) {
+                ArgumentInfo arg = arguments.get(i);
+                Object value = scalarArgumentValues.get(arg.name);
+                details.append(
+                        String.format(
+                                "  [%d] %s: %s (type: %s)\n",
+                                i,
+                                arg.name,
+                                value,
+                                value != null ? value.getClass().getName() : "null"));
+            }
+            throw new IllegalArgumentException(details.toString(), e);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                StringBuilder details = new StringBuilder();
+                details.append("Exception occurred during scalar-only PTF eval() invocation.\n");
+                details.append("Expected parameter types: ");
+                details.append(Arrays.toString(evalMethod.getParameterTypes()));
+                details.append("\nActual arguments:\n");
+                for (int i = 0; i < arguments.size(); i++) {
+                    ArgumentInfo arg = arguments.get(i);
+                    Object value = scalarArgumentValues.get(arg.name);
+                    details.append(
+                            String.format(
+                                    "  [%d] %s: %s (type: %s)\n",
+                                    i,
+                                    arg.name,
+                                    value,
+                                    value != null ? value.getClass().getName() : "null"));
+                }
+                userException.addSuppressed(new Exception(details.toString()));
+                throw userException;
+            } else {
+                StringBuilder details = new StringBuilder();
+                details.append("Error invoking scalar-only PTF eval() method.\n");
+                details.append("Expected parameter types: ");
+                details.append(Arrays.toString(evalMethod.getParameterTypes()));
+                details.append("\nActual arguments:\n");
+                for (int i = 0; i < arguments.size(); i++) {
+                    ArgumentInfo arg = arguments.get(i);
+                    Object value = scalarArgumentValues.get(arg.name);
+                    details.append(
+                            String.format(
+                                    "  [%d] %s: %s (type: %s)\n",
+                                    i,
+                                    arg.name,
+                                    value,
+                                    value != null ? value.getClass().getName() : "null"));
+                }
+                throw new RuntimeException(details.toString(), e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (IllegalArgumentException e) {
+            StringBuilder details = new StringBuilder();
+            details.append("Argument type mismatch during PTF eval() invocation.\n");
+            details.append("Expected parameter types: ");
+            details.append(Arrays.toString(evalMethod.getParameterTypes()));
+            details.append("\nActual arguments:\n");
+            for (int i = 0; i < arguments.size(); i++) {
+                ArgumentInfo arg = arguments.get(i);
+                Object value = args[i];
+                details.append(
+                        String.format(
+                                "  [%d] %s: %s (type: %s)\n",
+                                i,
+                                arg.name,
+                                value,
+                                value != null ? value.getClass().getName() : "null"));
+            }
+            throw new IllegalArgumentException(details.toString(), e);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                StringBuilder details = new StringBuilder();
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        " (partition columns: %s)",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : "";
+                details.append(
+                        String.format(
+                                "Exception occurred during PTF eval() while processing table argument '%s'%s.\n",
+                                activeTableArg.name, partitionInfo));
+                details.append("Expected parameter types: ");
+                details.append(Arrays.toString(evalMethod.getParameterTypes()));
+                details.append("\nActual arguments:\n");
+                for (int i = 0; i < arguments.size(); i++) {
+                    ArgumentInfo arg = arguments.get(i);
+                    Object value = args[i];
+                    details.append(
+                            String.format(
+                                    "  [%d] %s: %s (type: %s)\n",
+                                    i,
+                                    arg.name,
+                                    value,
+                                    value != null ? value.getClass().getName() : "null"));
+                }
+                userException.addSuppressed(new Exception(details.toString()));
+                throw userException;
+            } else {
+                StringBuilder details = new StringBuilder();
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        " (partition columns: %s)",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : "";
+                details.append(
+                        String.format(
+                                "Error invoking PTF eval() method while processing table argument '%s'%s.\n",
+                                activeTableArg.name, partitionInfo));
+                details.append("Expected parameter types: ");
+                details.append(Arrays.toString(evalMethod.getParameterTypes()));
+                details.append("\nActual arguments:\n");
+                for (int i = 0; i < arguments.size(); i++) {
+                    ArgumentInfo arg = arguments.get(i);
+                    Object value = args[i];
+                    details.append(
+                            String.format(
+                                    "  [%d] %s: %s (type: %s)\n",
+                                    i,
+                                    arg.name,
+                                    value,
+                                    value != null ? value.getClass().getName() : "null"));
+                }
+                throw new RuntimeException(details.toString(), e);
+            }
+        }
+    }
+
+    /** Collector implementation that stores output in the harness. */
+    private class HarnessCollector implements Collector<OUT> {
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            switch (activeTableArg.prependStrategy) {
+                case ALL_COLUMNS:
+                    output.add(prependAllColumns(record));
+                    break;
+                case PARTITION_KEYS:
+                    output.add(prependPartitionKeys(record));
+                    break;
+                case NONE:
+                    output.add(record);
+                    break;
+            }

Review Comment:
   nice!



##########
flink-table/flink-table-test-utils/src/test/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarnessTest.java:
##########
@@ -0,0 +1,1021 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.api.ValidationException;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class ProcessTableFunctionTestHarnessTest {
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PassthroughPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** Filter PTF for testing scalar argument handling. */
+    @DataTypeHint("ROW<value INT>")
+    public static class FilterPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer threshold) {
+            // Use named field access - converter enriches Row with field names
+            int value = input.getFieldAs("value");
+            if (value >= threshold) {
+                collect(input);
+            }
+        }
+    }
+
+    /** PTF for testing transformation of output types. */
+    @DataTypeHint("ROW<doubled INT, original INT>")
+    public static class DoublePTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2, value));
+        }
+    }
+
+    /** PTF with for testing table argument names set via argument hints. */
+    @DataTypeHint("ROW<value INT>")
+    public static class ExplicitNamePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "customName")
+                        Row actualParamName) {
+            collect(actualParamName);
+        }
+    }
+
+    /** PTF with inline type annotation - no builder config needed. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class InlineTypePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(
+                                value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+                                type = @DataTypeHint("ROW<value INT>"))
+                        Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PartitionedPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+            collect(Row.of((Integer) input.getFieldAs("value")));
+        }
+    }
+
+    /**
+     * PTF with PASS_COLUMNS_THROUGH for validating that all input columns are prepended to output.
+     */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class PassColumnsThroughPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** PTF with OPTIONAL_PARTITION_BY for validating that partition setup can be omitted. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class OptionalPartitionPTF extends ProcessTableFunction<Row> {
+
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.OPTIONAL_PARTITION_BY
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** Simple POJO for testing structured type input/output. */
+    public static class User {
+        public String name;
+        public int age;
+
+        public User() {}
+
+        public User(String name, int age) {
+            this.name = name;
+            this.age = age;
+        }
+
+        @Override
+        public String toString() {
+            return "User{name='" + name + "', age=" + age + '}';
+        }
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o) {
+                return true;
+            }
+            if (o == null || getClass() != o.getClass()) {
+                return false;
+            }
+            User user = (User) o;
+            return age == user.age && java.util.Objects.equals(name, user.name);
+        }
+
+        @Override
+        public int hashCode() {
+            return java.util.Objects.hash(name, age);
+        }
+    }
+
+    /** PTF for testing structured type inputs. */
+    @DataTypeHint("ROW<name STRING, age INT>")
+    public static class UserPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            if (user.age >= 18) {
+                collect(Row.of(user.name, user.age));
+            }
+        }
+    }
+
+    /** PTF that transforms structured type inputs and outputs. */
+    public static class UserTransformPTF extends ProcessTableFunction<User> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            User transformed = new User(user.name, user.age + 1);
+            collect(transformed);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "on_time". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgOnTimePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "on_time")
+                        Row input) {
+            collect(input);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "uid". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgUidPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) String uid) {
+            collect(input);
+        }
+    }
+
+    /** Multi-table PTF for validating multi-input processing. */
+    @DataTypeHint("ROW<output STRING>")
+    public static class MultiTableUnionPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /**
+     * Multi-table PTF with one POJO and one Row argument, for testing partitioning with structured
+     * types.
+     */
+    @DataTypeHint("ROW<source STRING, age INT>")
+    public static class MixedTypeMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) User userTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rowTable) {
+            if (userTable != null) {
+                collect(Row.of("USER", userTable.age));
+            }
+            if (rowTable != null) {
+                collect(Row.of("ROW", rowTable.getFieldAs("age")));
+            }
+        }
+    }
+
+    /**
+     * Invalid PTF - uses PASS_COLUMNS_THROUGH with multiple table arguments (not allowed per Flink
+     * docs).
+     */
+    @DataTypeHint("ROW<output STRING>")
+    public static class InvalidPassColumnsThroughMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /** PTF with only scalar arguments, no tables. */
+    @DataTypeHint("ROW<sum INT>")
+    public static class ScalarOnlyPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer a,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer b) {
+            collect(Row.of(a + b));
+        }
+    }
+
+    /** PTF with Context parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithContext extends ProcessTableFunction<Row> {
+        public void eval(Context ctx, @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** PTF with State parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithState extends ProcessTableFunction<Row> {
+        public static class CountState {
+            public long counter = 0L;
+        }
+
+        public void eval(
+                @StateHint CountState state,
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Builder Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testBuilderRejectsDuplicateScalarArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("threshold", 50)
+                                    .withScalarArgument("threshold", 100);
+                        });
+
+        assertThat(exception.getMessage()).contains("threshold");
+    }
+
+    @Test
+    void testBuilderRejectsDuplicateTableArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableUnionPTF.class)
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, value INT>"));
+                        });
+
+        assertThat(exception.getMessage()).contains("leftTable");
+    }
+
+    @Test
+    void testBuilderRejectsMixedDuplicateArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("input", 42);
+                        });
+
+        assertThat(exception.getMessage()).contains("input");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentOnTime() {
+        // We should reject PTFs that use reserved argument name "on_time"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgOnTimePTF.class)
+                        .withTableArgument("on_time", DataTypes.of("ROW<id INT>"));
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("on_time");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentUid() {
+        // We should reject PTFs that use reserved argument name "uid"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgUidPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<id INT>"))
+                        .withScalarArgument("uid", "my-id");
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("uid");
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testExplicitNameTakesPrecedence() throws Exception {
+        // Verify that @ArgumentHint(name="customName") takes precedence over actual parameter
+        // name when processing elements and calling eval.
+
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ExplicitNamePTF.class)
+                        .withTableArgument("customName", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(42));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0).getField(0)).isEqualTo(42);
+            assertThat(output.get(1).getField(0)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testScalarOnlyPTF() throws Exception {
+        // Test scalar-only PTF with no table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ScalarOnlyPTF.class)
+                        .withScalarArgument("a", 10)
+                        .withScalarArgument("b", 20)
+                        .build()) {
+
+            harness.process();
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0).getField(0)).isEqualTo(30);
+        }
+    }
+
+    @Test
+    void testInvokeRejectsTableArguments() throws Exception {
+        // Verify that invoke() rejects PTFs with table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50)
+                        .build()) {
+
+            Exception exception =
+                    assertThrows(
+                            IllegalStateException.class,
+                            () -> {
+                                harness.process();
+                            });
+
+            assertThat(exception.getMessage()).contains("process() is only for scalar-only PTFs");
+        }
+    }
+
+    @Test
+    void testTableProcessingWithScalarArgument() throws Exception {
+        // Test a PTF that uses a scalar parameter
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50) // Scalar argument: threshold = 50
+                        .build()) {
+
+            harness.processElement(Row.of(25));
+            harness.processElement(Row.of(75));
+            harness.processElement(Row.of(50));
+            harness.processElement(Row.of(10));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0).getField(0)).isEqualTo(75);
+            assertThat(output.get(1).getField(0)).isEqualTo(50);
+            assertThat(output.get(2).getField(0)).isEqualTo(100);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Trait Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testProcessElementWithRowKind() throws Exception {
+        // Verify RowKind is preserved through processing (ROW_SEMANTIC_TABLE)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(RowKind.INSERT, 10);
+            harness.processElement(RowKind.UPDATE_BEFORE, 15);
+            harness.processElement(RowKind.UPDATE_AFTER, 20);
+            harness.processElement(RowKind.DELETE, 30);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+            assertThat(output.get(0).getKind()).isEqualTo(RowKind.INSERT);
+            assertThat(output.get(0).getField(0)).isEqualTo(10);
+            assertThat(output.get(1).getKind()).isEqualTo(RowKind.UPDATE_BEFORE);
+            assertThat(output.get(1).getField(0)).isEqualTo(15);
+            assertThat(output.get(2).getKind()).isEqualTo(RowKind.UPDATE_AFTER);
+            assertThat(output.get(2).getField(0)).isEqualTo(20);
+            assertThat(output.get(3).getKind()).isEqualTo(RowKind.DELETE);
+            assertThat(output.get(3).getField(0)).isEqualTo(30);
+        }
+    }
+
+    @Test
+    void testPassColumnsThroughTrait() throws Exception {
+        // Verify PASS_COLUMNS_THROUGH prepends ALL input columns (not just partition keys)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassColumnsThroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 10, 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("B", 20, 40));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithoutPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY allows omitting partition configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+            harness.processElement(Row.of("C", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of(20));
+            assertThat(output.get(1)).isEqualTo(Row.of(40));
+            assertThat(output.get(2)).isEqualTo(Row.of(60));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY still works when partition is configured
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("A", 5));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("A", 10));
+            assertThat(output.get(2)).isEqualTo(Row.of("B", 40));
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Data Type Conversion Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testNamedRowFieldOrdering() throws Exception {
+        // Test what happens when Row field order differs from DataType schema order
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row rowA = Row.withNames();
+            rowA.setField("value", 100);
+            rowA.setField("user", "Alice");
+
+            harness.processElement(rowA);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+
+            // Positional access follows schema order
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testPositionalRowWithWrongTypeOrder() throws Exception {
+        // Verify that type mismatches are caught when Row values don't match schema types
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row wrongOrderRow = Row.of(10, "Alice");
+
+            Exception exception =
+                    assertThrows(
+                            ClassCastException.class, () -> harness.processElement(wrongOrderRow));
+
+            assertThat(exception.getMessage()).contains("Integer");
+            assertThat(exception.getMessage()).contains("String");
+            assertThat(exception.getMessage()).contains("cannot be cast");
+        }
+    }
+
+    @Test
+    void testStructuredTypeInput() throws Exception {
+        // Test that a PTF can declare an input type as a structured type,
+        // and that the harness can handle the conversion from Row into
+        // that type.
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+            harness.processElement(Row.of("Bob", 17));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(25);
+        }
+    }
+
+    @Test
+    void testStructuredTypeInputAndOutput() throws Exception {
+        // Test PTF with structured type inputs and outputs
+        try (ProcessTableFunctionTestHarness<User> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserTransformPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+
+            List<User> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            User result = output.get(0);
+            assertThat(result.getClass()).isEqualTo(User.class);
+            assertThat(result.name).isEqualTo("Alice");
+            assertThat(result.age).isEqualTo(26);
+        }
+    }
+
+    @Test
+    void testInlineTypeAnnotation() throws Exception {
+        // Verify that PTFs can declare table argument types via @ArgumentHint(type = ...)
+        // without needing .withTableArgument() configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class).build()) {
+
+            harness.processElement(Row.of(5));
+            harness.processElement(Row.of(10));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0)).isEqualTo(Row.of(10));
+            assertThat(output.get(1)).isEqualTo(Row.of(20));
+        }
+    }
+
+    @Test
+    void testInlineTypeMatchesBuilderConfig() throws Exception {
+        // Verify that when both inline annotation and builder config are provided with matching
+        // types, the harness builds successfully
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(7));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0)).isEqualTo(Row.of(14));
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Partitioning Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testSetSemanticWithPartitionByName() throws Exception {
+        // Verify set-semantic table with partition configuration by column name
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key") // Partition by "key" column name
+                        .build()) {
+
+            harness.processElement(Row.of("X", 10));
+            harness.processElement(Row.of("Y", 20));
+            harness.processElement(Row.of("X", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0)).isEqualTo(Row.of("X", 10));
+            assertThat(output.get(1)).isEqualTo(Row.of("Y", 20));
+            assertThat(output.get(2)).isEqualTo(Row.of("X", 30));
+        }
+    }
+
+    @Test
+    void testSetSemanticWithMultiplePartitionColumns() throws Exception {
+        // Verify composite partition key (multiple columns)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument(
+                                "input",
+                                DataTypes.of("ROW<region STRING, country STRING, value INT>"))
+                        .withPartitionBy("input", "region", "country")
+                        .build()) {
+
+            harness.processElement(Row.of("EU", "DE", 100));
+            harness.processElement(Row.of("EU", "DE", 200));
+            harness.processElement(Row.of("EU", "FR", 300));
+            harness.processElement(Row.of("US", "NY", 400));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+            assertThat(output.get(0)).isEqualTo(Row.of("EU", "DE", 100));
+            assertThat(output.get(1)).isEqualTo(Row.of("EU", "DE", 200));
+            assertThat(output.get(2)).isEqualTo(Row.of("EU", "FR", 300));
+            assertThat(output.get(3)).isEqualTo(Row.of("US", "NY", 400));
+        }
+    }
+
+    @Test
+    void testSetSemanticWithSelectivePartitioning() throws Exception {
+        // Verify that only partition columns are automatically included in output
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument(
+                                "input",
+                                DataTypes.of(
+                                        "ROW<id INT, region STRING, country STRING, city STRING, value INT>"))
+                        .withPartitionBy("input", "region")
+                        .build()) {
+
+            harness.processElement(Row.of(1, "EU", "DE", "Berlin", 100));
+            harness.processElement(Row.of(4, "US", "CA", "LA", 200));
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output.get(0)).isEqualTo(Row.of("EU", 100));
+            assertThat(output.get(1)).isEqualTo(Row.of("US", 200));
+        }
+    }
+
+    @Test
+    void testMultipleSetSemanticTablesWithMatchingPartitionKeys() throws Exception {
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(MultiTableUnionPTF.class)
+                        .withTableArgument("leftTable", DataTypes.of("ROW<name STRING, score INT>"))
+                        .withPartitionBy("leftTable", "name")
+                        .withTableArgument(
+                                "rightTable", DataTypes.of("ROW<name STRING, city STRING>"))
+                        .withPartitionBy("rightTable", "name")

Review Comment:
   Just curious, do PTFs emit rows with named fields? 
   I'm asking because, that might cause problems with this configuration which would need to prepend two cols with the name `name` (due to the `partition by` clauses).
   
   Might be worth checking how the PTF runtime handles this situation.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "autophagy (via GitHub)" <gi...@apache.org>.
autophagy commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3180023999


##########
docs/content/docs/dev/table/testing/ptf_test_harness.md:
##########
@@ -0,0 +1,361 @@
+---
+title: "Testing Process Table Functions"
+weight: 10
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Testing Process Table Functions
+
+The `ProcessTableFunctionTestHarness` provides a lightweight unit testing framework for Process Table
+Functions (PTFs). It allows you to test PTF logic without starting a full Flink cluster. It is useful
+for testing and validating PTF business logic, multi-table PTF behaviour and validating errors.
+
+For end-to-end integration testing with the full Flink planner and runtime, use integration tests
+instead.
+
+{{< top >}}
+
+## Quick Start
+
+{{< tabs "quickstart" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.*;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.runtime.functions.ProcessTableFunctionTestHarness;
+import org.apache.flink.types.Row;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+// PTF under test
+@DataTypeHint("ROW<doubled INT>")
+public class DoublePTF extends ProcessTableFunction<Row> {
+    public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+        int value = input.getFieldAs("value");
+        collect(Row.of(value * 2));
+    }
+}
+
+// Test
+@Test
+void testDoublePTF() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(DoublePTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                    .build()) {
+
+        harness.processElement(Row.of(5));
+        harness.processElement(Row.of(10));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output).hasSize(2);
+        assertThat(output.get(0)).isEqualTo(Row.of(10));
+        assertThat(output.get(1)).isEqualTo(Row.of(20));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+{{< top >}}
+
+## Common Testing Scenarios
+
+### Testing Row-Semantic Tables
+
+Use `.withTableArgument()` to configure the input table schema:
+
+{{< tabs "row-semantic" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<value INT>")
+public class PassthroughPTF extends ProcessTableFunction<Row> {
+    public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+        collect(input);
+    }
+}
+
+@Test
+void testPassthrough() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                    .build()) {
+
+        harness.processElement(Row.of(42));
+        harness.processElement(Row.of(100));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output).containsExactly(Row.of(42), Row.of(100));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Testing Set-Semantic Tables with Partitioning
+
+For `SET_SEMANTIC_TABLE`, use `.withPartitionBy()` to configure partition columns:
+
+{{< tabs "set-semantic" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<doubled INT>")
+public class PartitionedPTF extends ProcessTableFunction<Row> {
+    public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+        int value = input.getFieldAs("value");
+        collect(Row.of(value * 2));
+    }
+}
+
+@Test
+void testPartitionedPTF() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                    .withPartitionBy("input", "key")
+                    .build()) {
+
+        harness.processElement(Row.of("A", 10));
+        harness.processElement(Row.of("B", 20));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+        assertThat(output.get(1)).isEqualTo(Row.of("B", 40));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Testing Multiple Table Arguments
+
+Use `processElementForTable()` to specify which table receives each row:
+
+{{< tabs "multi-table" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<output STRING>")
+public class JoinPTF extends ProcessTableFunction<Row> {
+    public void eval(
+            @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row left,
+            @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row right) {
+        if (left != null) {
+            collect(Row.of("LEFT: " + left));
+        }
+        if (right != null) {
+            collect(Row.of("RIGHT: " + right));
+        }
+    }
+}
+
+@Test
+void testMultiTable() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(JoinPTF.class)
+                    .withTableArgument("left", DataTypes.of("ROW<id INT, name STRING>"))
+                    .withPartitionBy("left", "id")
+                    .withTableArgument("right", DataTypes.of("ROW<id INT, city STRING>"))
+                    .withPartitionBy("right", "id")
+                    .build()) {
+
+        // Use processElementForTable() to target specific tables
+        harness.processElementForTable("left", Row.of(1, "Alice"));
+        harness.processElementForTable("right", Row.of(1, "Berlin"));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output.get(0)).isEqualTo(Row.of(1, null, "LEFT: +I[1, Alice]"));
+        assertThat(output.get(1)).isEqualTo(Row.of(null, 1, "RIGHT: +I[1, Berlin]"));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Testing with Scalar Arguments
+
+Use `.withScalarArgument()` to configure scalar parameter values:
+
+{{< tabs "scalar-args" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<value INT>")
+public class FilterPTF extends ProcessTableFunction<Row> {
+    public void eval(
+            @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+            @ArgumentHint(ArgumentTrait.SCALAR) int threshold) {
+        int value = input.getFieldAs("value");
+        if (value > threshold) {
+            collect(Row.of(value));
+        }
+    }
+}
+
+@Test
+void testFilter() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                    .withScalarArgument("threshold", 50)  // Configure scalar value
+                    .build()) {
+
+        harness.processElement(Row.of(30));
+        harness.processElement(Row.of(70));
+
+        List<Row> output = harness.getOutput();
+        assertThat(output).containsExactly(Row.of(70));
+    }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+**Scalar-Only PTFs**: For PTFs with only scalar arguments, use `invoke()` to trigger evaluation:
+
+{{< tabs "scalar-only" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<sum INT>")
+public class AddPTF extends ProcessTableFunction<Row> {
+    public void eval(
+            @ArgumentHint(ArgumentTrait.SCALAR) int a,
+            @ArgumentHint(ArgumentTrait.SCALAR) int b) {
+        collect(Row.of(a + b));
+    }
+}
+
+@Test
+void testScalarOnly() throws Exception {
+    try (ProcessTableFunctionTestHarness<Row> harness =
+            ProcessTableFunctionTestHarness.ofClass(AddPTF.class)
+                    .withScalarArgument("a", 5)
+                    .withScalarArgument("b", 7)
+                    .build()) {
+
+        harness.invoke();  // Use invoke() instead of processElement()

Review Comment:
   It throws an invalid state exception, with `process() is only for scalar-only PTFs. This PTF has table arguments. Use processElement() or processElementForTable() instead.`



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "autophagy (via GitHub)" <gi...@apache.org>.
autophagy commented on PR #27928:
URL: https://github.com/apache/flink/pull/27928#issuecomment-4258450136

   @spuru9 Thank you for the review! I've pushed up a couple of commits to address your comments, and thank you for the prompt to get me to sort of my IDE so it doesn't do that kind of inline import anymore 😅 


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "fhueske (via GitHub)" <gi...@apache.org>.
fhueske commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3217795115


##########
flink-table/flink-table-test-utils/src/test/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarnessTest.java:
##########
@@ -0,0 +1,1058 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.api.ValidationException;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class ProcessTableFunctionTestHarnessTest {
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PassthroughPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** Filter PTF for testing scalar argument handling. */
+    @DataTypeHint("ROW<value INT>")
+    public static class FilterPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer threshold) {
+            // Use named field access - converter enriches Row with field names
+            int value = input.getFieldAs("value");
+            if (value >= threshold) {
+                collect(input);
+            }
+        }
+    }
+
+    /** PTF for testing transformation of output types. */
+    @DataTypeHint("ROW<doubled INT, original INT>")
+    public static class DoublePTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2, value));
+        }
+    }
+
+    /** PTF with for testing table argument names set via argument hints. */
+    @DataTypeHint("ROW<value INT>")
+    public static class ExplicitNamePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "customName")
+                        Row actualParamName) {
+            collect(actualParamName);
+        }
+    }
+
+    /** PTF with inline type annotation - no builder config needed. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class InlineTypePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(
+                                value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+                                type = @DataTypeHint("ROW<value INT>"))
+                        Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PartitionedPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+            collect(Row.of((Integer) input.getFieldAs("value")));
+        }
+    }
+
+    /**
+     * PTF with PASS_COLUMNS_THROUGH for validating that all input columns are prepended to output.
+     */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class PassColumnsThroughPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** PTF with OPTIONAL_PARTITION_BY for validating that partition setup can be omitted. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class OptionalPartitionPTF extends ProcessTableFunction<Row> {
+
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.OPTIONAL_PARTITION_BY
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** Simple POJO for testing structured type input/output. */
+    public static class User {
+        public String name;
+        public int age;
+
+        public User() {}
+
+        public User(String name, int age) {
+            this.name = name;
+            this.age = age;
+        }
+
+        @Override
+        public String toString() {
+            return "User{name='" + name + "', age=" + age + '}';
+        }
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o) {
+                return true;
+            }
+            if (o == null || getClass() != o.getClass()) {
+                return false;
+            }
+            User user = (User) o;
+            return age == user.age && java.util.Objects.equals(name, user.name);
+        }
+
+        @Override
+        public int hashCode() {
+            return java.util.Objects.hash(name, age);
+        }
+    }
+
+    /** PTF for testing structured type inputs. */
+    @DataTypeHint("ROW<name STRING, age INT>")
+    public static class UserPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            if (user.age >= 18) {
+                collect(Row.of(user.name, user.age));
+            }
+        }
+    }
+
+    /** PTF that transforms structured type inputs and outputs. */
+    public static class UserTransformPTF extends ProcessTableFunction<User> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            User transformed = new User(user.name, user.age + 1);
+            collect(transformed);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "on_time". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgOnTimePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "on_time")
+                        Row input) {
+            collect(input);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "uid". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgUidPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) String uid) {
+            collect(input);
+        }
+    }
+
+    /** Multi-table PTF for validating multi-input processing. */
+    @DataTypeHint("ROW<output STRING>")
+    public static class MultiTableJoinPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /**
+     * Multi-table PTF with one POJO and one Row argument, for testing partitioning with structured
+     * types.
+     */
+    @DataTypeHint("ROW<source STRING, age INT>")
+    public static class MixedTypeMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) User userTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rowTable) {
+            if (userTable != null) {
+                collect(Row.of("USER", userTable.age));
+            }
+            if (rowTable != null) {
+                collect(Row.of("ROW", rowTable.getFieldAs("age")));
+            }
+        }
+    }
+
+    /**
+     * Invalid PTF - uses PASS_COLUMNS_THROUGH with multiple table arguments (not allowed per Flink
+     * docs).
+     */
+    @DataTypeHint("ROW<output STRING>")
+    public static class InvalidPassColumnsThroughMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /** PTF with only scalar arguments, no tables. */
+    @DataTypeHint("ROW<sum INT>")
+    public static class ScalarOnlyPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer a,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer b) {
+            collect(Row.of(a + b));
+        }
+    }
+
+    /** PTF with Context parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithContext extends ProcessTableFunction<Row> {
+        public void eval(Context ctx, @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** PTF with State parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithState extends ProcessTableFunction<Row> {
+        public static class CountState {
+            public long counter = 0L;
+        }
+
+        public void eval(
+                @StateHint CountState state,
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Builder Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testBuilderRejectsDuplicateScalarArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("threshold", 50)
+                                    .withScalarArgument("threshold", 100);
+                        });
+
+        assertThat(exception.getMessage()).contains("threshold");
+    }
+
+    @Test
+    void testBuilderRejectsDuplicateTableArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, value INT>"));
+                        });
+
+        assertThat(exception.getMessage()).contains("leftTable");
+    }
+
+    @Test
+    void testBuilderRejectsMixedDuplicateArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("input", 42);
+                        });
+
+        assertThat(exception.getMessage()).contains("input");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentOnTime() {
+        // We should reject PTFs that use reserved argument name "on_time"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgOnTimePTF.class)
+                        .withTableArgument("on_time", DataTypes.of("ROW<id INT>"));
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("on_time");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentUid() {
+        // We should reject PTFs that use reserved argument name "uid"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgUidPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<id INT>"))
+                        .withScalarArgument("uid", "my-id");
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("uid");
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testExplicitNameTakesPrecedence() throws Exception {
+        // Verify that @ArgumentHint(name="customName") takes precedence over actual parameter
+        // name when processing elements and calling eval.
+
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ExplicitNamePTF.class)
+                        .withTableArgument("customName", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(42));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0).getField(0)).isEqualTo(42);
+            assertThat(output.get(1).getField(0)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testScalarOnlyPTF() throws Exception {
+        // Test scalar-only PTF with no table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ScalarOnlyPTF.class)
+                        .withScalarArgument("a", 10)
+                        .withScalarArgument("b", 20)
+                        .build()) {
+
+            harness.process();
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0).getField(0)).isEqualTo(30);
+        }
+    }
+
+    @Test
+    void testInvokeRejectsTableArguments() throws Exception {
+        // Verify that invoke() rejects PTFs with table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50)
+                        .build()) {
+
+            Exception exception =
+                    assertThrows(
+                            IllegalStateException.class,
+                            () -> {
+                                harness.process();
+                            });
+
+            assertThat(exception.getMessage()).contains("process() is only for scalar-only PTFs");
+        }
+    }
+
+    @Test
+    void testTableProcessingWithScalarArgument() throws Exception {
+        // Test a PTF that uses a scalar parameter
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50) // Scalar argument: threshold = 50
+                        .build()) {
+
+            harness.processElement(Row.of(25));
+            harness.processElement(Row.of(75));
+            harness.processElement(Row.of(50));
+            harness.processElement(Row.of(10));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0).getField(0)).isEqualTo(75);
+            assertThat(output.get(1).getField(0)).isEqualTo(50);
+            assertThat(output.get(2).getField(0)).isEqualTo(100);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Trait Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testProcessElementWithRowKind() throws Exception {
+        // Verify RowKind is preserved through processing (ROW_SEMANTIC_TABLE)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(RowKind.INSERT, 10);
+            harness.processElement(RowKind.UPDATE_BEFORE, 15);
+            harness.processElement(RowKind.UPDATE_AFTER, 20);
+            harness.processElement(RowKind.DELETE, 30);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+            assertThat(output.get(0).getKind()).isEqualTo(RowKind.INSERT);
+            assertThat(output.get(1).getKind()).isEqualTo(RowKind.UPDATE_BEFORE);
+            assertThat(output.get(2).getKind()).isEqualTo(RowKind.UPDATE_AFTER);
+            assertThat(output.get(3).getKind()).isEqualTo(RowKind.DELETE);
+        }
+    }
+
+    @Test
+    void testPassColumnsThroughTrait() throws Exception {
+        // Verify PASS_COLUMNS_THROUGH prepends ALL input columns (not just partition keys)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassColumnsThroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 10, 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("B", 20, 40));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithoutPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY allows omitting partition configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+            harness.processElement(Row.of("C", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of(20));
+            assertThat(output.get(1)).isEqualTo(Row.of(40));
+            assertThat(output.get(2)).isEqualTo(Row.of(60));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY still works when partition is configured
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("A", 5));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("A", 10));
+            assertThat(output.get(2)).isEqualTo(Row.of("B", 40));
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Data Type Conversion Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testNamedRowFieldOrdering() throws Exception {
+        // Test what happens when Row field order differs from DataType schema order
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row rowA = Row.withNames();
+            rowA.setField("value", 100);
+            rowA.setField("user", "Alice");
+
+            harness.processElement(rowA);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+
+            // Positional access follows schema order
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testPositionalRowWithWrongTypeOrder() throws Exception {
+        // Verify that type mismatches are caught when Row values don't match schema types
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row wrongOrderRow = Row.of(10, "Alice");
+
+            assertThrows(ClassCastException.class, () -> harness.processElement(wrongOrderRow));

Review Comment:
   should we check that the exception message is helpful for the user?



##########
flink-table/flink-table-test-utils/src/test/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarnessTest.java:
##########
@@ -0,0 +1,1058 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.api.ValidationException;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class ProcessTableFunctionTestHarnessTest {
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PassthroughPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** Filter PTF for testing scalar argument handling. */
+    @DataTypeHint("ROW<value INT>")
+    public static class FilterPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer threshold) {
+            // Use named field access - converter enriches Row with field names
+            int value = input.getFieldAs("value");
+            if (value >= threshold) {
+                collect(input);
+            }
+        }
+    }
+
+    /** PTF for testing transformation of output types. */
+    @DataTypeHint("ROW<doubled INT, original INT>")
+    public static class DoublePTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2, value));
+        }
+    }
+
+    /** PTF with for testing table argument names set via argument hints. */
+    @DataTypeHint("ROW<value INT>")
+    public static class ExplicitNamePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "customName")
+                        Row actualParamName) {
+            collect(actualParamName);
+        }
+    }
+
+    /** PTF with inline type annotation - no builder config needed. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class InlineTypePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(
+                                value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+                                type = @DataTypeHint("ROW<value INT>"))
+                        Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PartitionedPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+            collect(Row.of((Integer) input.getFieldAs("value")));
+        }
+    }
+
+    /**
+     * PTF with PASS_COLUMNS_THROUGH for validating that all input columns are prepended to output.
+     */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class PassColumnsThroughPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** PTF with OPTIONAL_PARTITION_BY for validating that partition setup can be omitted. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class OptionalPartitionPTF extends ProcessTableFunction<Row> {
+
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.OPTIONAL_PARTITION_BY
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** Simple POJO for testing structured type input/output. */
+    public static class User {
+        public String name;
+        public int age;
+
+        public User() {}
+
+        public User(String name, int age) {
+            this.name = name;
+            this.age = age;
+        }
+
+        @Override
+        public String toString() {
+            return "User{name='" + name + "', age=" + age + '}';
+        }
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o) {
+                return true;
+            }
+            if (o == null || getClass() != o.getClass()) {
+                return false;
+            }
+            User user = (User) o;
+            return age == user.age && java.util.Objects.equals(name, user.name);
+        }
+
+        @Override
+        public int hashCode() {
+            return java.util.Objects.hash(name, age);
+        }
+    }
+
+    /** PTF for testing structured type inputs. */
+    @DataTypeHint("ROW<name STRING, age INT>")
+    public static class UserPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            if (user.age >= 18) {
+                collect(Row.of(user.name, user.age));
+            }
+        }
+    }
+
+    /** PTF that transforms structured type inputs and outputs. */
+    public static class UserTransformPTF extends ProcessTableFunction<User> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            User transformed = new User(user.name, user.age + 1);
+            collect(transformed);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "on_time". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgOnTimePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "on_time")
+                        Row input) {
+            collect(input);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "uid". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgUidPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) String uid) {
+            collect(input);
+        }
+    }
+
+    /** Multi-table PTF for validating multi-input processing. */
+    @DataTypeHint("ROW<output STRING>")
+    public static class MultiTableJoinPTF extends ProcessTableFunction<Row> {

Review Comment:
   nit: this is not really a join (would require state) but rather a union operation.



##########
flink-table/flink-table-test-utils/src/test/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarnessTest.java:
##########
@@ -0,0 +1,1058 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.api.ValidationException;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class ProcessTableFunctionTestHarnessTest {
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PassthroughPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** Filter PTF for testing scalar argument handling. */
+    @DataTypeHint("ROW<value INT>")
+    public static class FilterPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer threshold) {
+            // Use named field access - converter enriches Row with field names
+            int value = input.getFieldAs("value");
+            if (value >= threshold) {
+                collect(input);
+            }
+        }
+    }
+
+    /** PTF for testing transformation of output types. */
+    @DataTypeHint("ROW<doubled INT, original INT>")
+    public static class DoublePTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2, value));
+        }
+    }
+
+    /** PTF with for testing table argument names set via argument hints. */
+    @DataTypeHint("ROW<value INT>")
+    public static class ExplicitNamePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "customName")
+                        Row actualParamName) {
+            collect(actualParamName);
+        }
+    }
+
+    /** PTF with inline type annotation - no builder config needed. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class InlineTypePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(
+                                value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+                                type = @DataTypeHint("ROW<value INT>"))
+                        Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PartitionedPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+            collect(Row.of((Integer) input.getFieldAs("value")));
+        }
+    }
+
+    /**
+     * PTF with PASS_COLUMNS_THROUGH for validating that all input columns are prepended to output.
+     */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class PassColumnsThroughPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** PTF with OPTIONAL_PARTITION_BY for validating that partition setup can be omitted. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class OptionalPartitionPTF extends ProcessTableFunction<Row> {
+
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.OPTIONAL_PARTITION_BY
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** Simple POJO for testing structured type input/output. */
+    public static class User {
+        public String name;
+        public int age;
+
+        public User() {}
+
+        public User(String name, int age) {
+            this.name = name;
+            this.age = age;
+        }
+
+        @Override
+        public String toString() {
+            return "User{name='" + name + "', age=" + age + '}';
+        }
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o) {
+                return true;
+            }
+            if (o == null || getClass() != o.getClass()) {
+                return false;
+            }
+            User user = (User) o;
+            return age == user.age && java.util.Objects.equals(name, user.name);
+        }
+
+        @Override
+        public int hashCode() {
+            return java.util.Objects.hash(name, age);
+        }
+    }
+
+    /** PTF for testing structured type inputs. */
+    @DataTypeHint("ROW<name STRING, age INT>")
+    public static class UserPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            if (user.age >= 18) {
+                collect(Row.of(user.name, user.age));
+            }
+        }
+    }
+
+    /** PTF that transforms structured type inputs and outputs. */
+    public static class UserTransformPTF extends ProcessTableFunction<User> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            User transformed = new User(user.name, user.age + 1);
+            collect(transformed);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "on_time". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgOnTimePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "on_time")
+                        Row input) {
+            collect(input);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "uid". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgUidPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) String uid) {
+            collect(input);
+        }
+    }
+
+    /** Multi-table PTF for validating multi-input processing. */
+    @DataTypeHint("ROW<output STRING>")
+    public static class MultiTableJoinPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /**
+     * Multi-table PTF with one POJO and one Row argument, for testing partitioning with structured
+     * types.
+     */
+    @DataTypeHint("ROW<source STRING, age INT>")
+    public static class MixedTypeMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) User userTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rowTable) {
+            if (userTable != null) {
+                collect(Row.of("USER", userTable.age));
+            }
+            if (rowTable != null) {
+                collect(Row.of("ROW", rowTable.getFieldAs("age")));
+            }
+        }
+    }
+
+    /**
+     * Invalid PTF - uses PASS_COLUMNS_THROUGH with multiple table arguments (not allowed per Flink
+     * docs).
+     */
+    @DataTypeHint("ROW<output STRING>")
+    public static class InvalidPassColumnsThroughMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /** PTF with only scalar arguments, no tables. */
+    @DataTypeHint("ROW<sum INT>")
+    public static class ScalarOnlyPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer a,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer b) {
+            collect(Row.of(a + b));
+        }
+    }
+
+    /** PTF with Context parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithContext extends ProcessTableFunction<Row> {
+        public void eval(Context ctx, @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** PTF with State parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithState extends ProcessTableFunction<Row> {
+        public static class CountState {
+            public long counter = 0L;
+        }
+
+        public void eval(
+                @StateHint CountState state,
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Builder Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testBuilderRejectsDuplicateScalarArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("threshold", 50)
+                                    .withScalarArgument("threshold", 100);
+                        });
+
+        assertThat(exception.getMessage()).contains("threshold");
+    }
+
+    @Test
+    void testBuilderRejectsDuplicateTableArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, value INT>"));
+                        });
+
+        assertThat(exception.getMessage()).contains("leftTable");
+    }
+
+    @Test
+    void testBuilderRejectsMixedDuplicateArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("input", 42);
+                        });
+
+        assertThat(exception.getMessage()).contains("input");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentOnTime() {
+        // We should reject PTFs that use reserved argument name "on_time"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgOnTimePTF.class)
+                        .withTableArgument("on_time", DataTypes.of("ROW<id INT>"));
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("on_time");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentUid() {
+        // We should reject PTFs that use reserved argument name "uid"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgUidPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<id INT>"))
+                        .withScalarArgument("uid", "my-id");
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("uid");
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testExplicitNameTakesPrecedence() throws Exception {
+        // Verify that @ArgumentHint(name="customName") takes precedence over actual parameter
+        // name when processing elements and calling eval.
+
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ExplicitNamePTF.class)
+                        .withTableArgument("customName", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(42));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0).getField(0)).isEqualTo(42);
+            assertThat(output.get(1).getField(0)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testScalarOnlyPTF() throws Exception {
+        // Test scalar-only PTF with no table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ScalarOnlyPTF.class)
+                        .withScalarArgument("a", 10)
+                        .withScalarArgument("b", 20)
+                        .build()) {
+
+            harness.process();
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0).getField(0)).isEqualTo(30);
+        }
+    }
+
+    @Test
+    void testInvokeRejectsTableArguments() throws Exception {
+        // Verify that invoke() rejects PTFs with table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50)
+                        .build()) {
+
+            Exception exception =
+                    assertThrows(
+                            IllegalStateException.class,
+                            () -> {
+                                harness.process();
+                            });
+
+            assertThat(exception.getMessage()).contains("process() is only for scalar-only PTFs");
+        }
+    }
+
+    @Test
+    void testTableProcessingWithScalarArgument() throws Exception {
+        // Test a PTF that uses a scalar parameter
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50) // Scalar argument: threshold = 50
+                        .build()) {
+
+            harness.processElement(Row.of(25));
+            harness.processElement(Row.of(75));
+            harness.processElement(Row.of(50));
+            harness.processElement(Row.of(10));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0).getField(0)).isEqualTo(75);
+            assertThat(output.get(1).getField(0)).isEqualTo(50);
+            assertThat(output.get(2).getField(0)).isEqualTo(100);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Trait Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testProcessElementWithRowKind() throws Exception {
+        // Verify RowKind is preserved through processing (ROW_SEMANTIC_TABLE)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(RowKind.INSERT, 10);
+            harness.processElement(RowKind.UPDATE_BEFORE, 15);
+            harness.processElement(RowKind.UPDATE_AFTER, 20);
+            harness.processElement(RowKind.DELETE, 30);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+            assertThat(output.get(0).getKind()).isEqualTo(RowKind.INSERT);
+            assertThat(output.get(1).getKind()).isEqualTo(RowKind.UPDATE_BEFORE);
+            assertThat(output.get(2).getKind()).isEqualTo(RowKind.UPDATE_AFTER);
+            assertThat(output.get(3).getKind()).isEqualTo(RowKind.DELETE);
+        }
+    }
+
+    @Test
+    void testPassColumnsThroughTrait() throws Exception {
+        // Verify PASS_COLUMNS_THROUGH prepends ALL input columns (not just partition keys)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassColumnsThroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 10, 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("B", 20, 40));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithoutPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY allows omitting partition configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+            harness.processElement(Row.of("C", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of(20));
+            assertThat(output.get(1)).isEqualTo(Row.of(40));
+            assertThat(output.get(2)).isEqualTo(Row.of(60));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY still works when partition is configured
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("A", 5));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("A", 10));
+            assertThat(output.get(2)).isEqualTo(Row.of("B", 40));
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Data Type Conversion Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testNamedRowFieldOrdering() throws Exception {
+        // Test what happens when Row field order differs from DataType schema order
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row rowA = Row.withNames();
+            rowA.setField("value", 100);
+            rowA.setField("user", "Alice");
+
+            harness.processElement(rowA);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+
+            // Positional access follows schema order
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testPositionalRowWithWrongTypeOrder() throws Exception {
+        // Verify that type mismatches are caught when Row values don't match schema types
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row wrongOrderRow = Row.of(10, "Alice");
+
+            assertThrows(ClassCastException.class, () -> harness.processElement(wrongOrderRow));
+        }
+    }
+
+    @Test
+    void testStructuredTypeInput() throws Exception {
+        // Test PTF that accepts structured types instead of Row
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+            harness.processElement(Row.of("Bob", 17));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(25);
+        }
+    }
+
+    @Test
+    void testStructuredTypeInputAndOutput() throws Exception {
+        // Test PTF with structured type inputs and outputs
+        try (ProcessTableFunctionTestHarness<User> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserTransformPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+
+            List<User> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            User result = output.get(0);
+            assertThat(result.getClass()).isEqualTo(User.class);
+            assertThat(result.name).isEqualTo("Alice");
+            assertThat(result.age).isEqualTo(26);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Partitioning Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testSetSemanticWithPartitionByName() throws Exception {
+        // Verify set-semantic table with partition configuration by column name
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key") // Partition by "key" column name
+                        .build()) {
+
+            harness.processElement(Row.of("X", 10));
+            harness.processElement(Row.of("Y", 20));
+            harness.processElement(Row.of("X", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0)).isEqualTo(Row.of("X", 10));
+            assertThat(output.get(1)).isEqualTo(Row.of("Y", 20));
+            assertThat(output.get(2)).isEqualTo(Row.of("X", 30));
+        }
+    }
+
+    @Test
+    void testSetSemanticWithMultiplePartitionColumns() throws Exception {
+        // Verify composite partition key (multiple columns)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument(
+                                "input",
+                                DataTypes.of("ROW<region STRING, country STRING, value INT>"))
+                        .withPartitionBy("input", "region", "country")
+                        .build()) {
+
+            harness.processElement(Row.of("EU", "DE", 100));
+            harness.processElement(Row.of("EU", "DE", 200));
+            harness.processElement(Row.of("EU", "FR", 300));
+            harness.processElement(Row.of("US", "NY", 400));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+        }
+    }
+
+    @Test
+    void testMultipleSetSemanticTablesWithMatchingPartitionKeys() throws Exception {
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                        .withTableArgument("leftTable", DataTypes.of("ROW<name STRING, score INT>"))
+                        .withPartitionBy("leftTable", "name")
+                        .withTableArgument(
+                                "rightTable", DataTypes.of("ROW<name STRING, city STRING>"))
+                        .withPartitionBy("rightTable", "name")
+                        .build()) {
+
+            harness.processElementForTable("leftTable", Row.of("Alice", 100));
+            harness.processElementForTable("leftTable", Row.of("Bob", 200));
+
+            harness.processElementForTable("rightTable", Row.of("Alice", "Berlin"));
+            harness.processElementForTable("rightTable", Row.of("Bob", "London"));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+
+            assertThat(output.get(0).getField(0)).isEqualTo("Alice");
+            assertThat(output.get(0).getField(1)).isNull();
+            assertThat(output.get(0).getField(2)).isEqualTo("LEFT: +I[Alice, 100]");
+
+            assertThat(output.get(1).getField(0)).isEqualTo("Bob");
+            assertThat(output.get(1).getField(1)).isNull();
+            assertThat(output.get(1).getField(2)).isEqualTo("LEFT: +I[Bob, 200]");
+
+            assertThat(output.get(2).getField(0)).isNull();
+            assertThat(output.get(2).getField(1)).isEqualTo("Alice");
+            assertThat(output.get(2).getField(2)).isEqualTo("RIGHT: +I[Alice, Berlin]");
+
+            assertThat(output.get(3).getField(0)).isNull();
+            assertThat(output.get(3).getField(1)).isEqualTo("Bob");
+            assertThat(output.get(3).getField(2)).isEqualTo("RIGHT: +I[Bob, London]");
+        }
+    }
+
+    @Test
+    void testMultipleSetSemanticTablesWithMismatchedPartitionTypes() {
+        // Verify that multi-table PTFs with inconsistent partition types are rejected
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                                    .withPartitionBy("leftTable", "id")
+                                    .withTableArgument(
+                                            "rightTable",
+                                            DataTypes.of("ROW<key STRING, city STRING>"))
+                                    .withPartitionBy("rightTable", "key")
+                                    .build();
+                        });
+
+        assertThat(exception.getMessage()).contains("Inconsistent partitioning");
+    }
+
+    @Test
+    void testMultipleSetSemanticTablesWithMismatchedPartitionColumnCount() {
+        // Verify that multi-table PTFs with different partition column counts are rejected
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                                    .withTableArgument(
+                                            "leftTable",
+                                            DataTypes.of("ROW<id INT, region STRING, name STRING>"))
+                                    .withPartitionBy("leftTable", "id", "region")
+                                    .withTableArgument(
+                                            "rightTable", DataTypes.of("ROW<id INT, city STRING>"))
+                                    .withPartitionBy("rightTable", "id")
+                                    .build();
+                        });
+
+        assertThat(exception.getMessage()).contains("Inconsistent partitioning");
+    }
+
+    @Test
+    void testPassColumnsThroughWithMultipleTablesRejected() {
+        // Verify that PASS_COLUMNS_THROUGH is rejected when used with multiple table arguments
+        Exception exception =
+                assertThrows(
+                        org.apache.flink.table.api.ValidationException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(
+                                            InvalidPassColumnsThroughMultiTablePTF.class)
+                                    .withTableArgument("leftTable", DataTypes.of("ROW<a INT>"))
+                                    .withTableArgument("rightTable", DataTypes.of("ROW<b INT>"))
+                                    .build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Pass-through columns")
+                .contains("multiple table arguments");
+    }
+
+    @Test
+    void testInlineTypeAnnotation() throws Exception {
+        // Verify that PTFs can declare table argument types via @ArgumentHint(type = ...)
+        // without needing .withTableArgument() configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class).build()) {
+
+            harness.processElement(Row.of(5));
+            harness.processElement(Row.of(10));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0)).isEqualTo(Row.of(10));
+            assertThat(output.get(1)).isEqualTo(Row.of(20));
+        }
+    }
+
+    @Test
+    void testInlineTypeMatchesBuilderConfig() throws Exception {
+        // Verify that when both inline annotation and builder config are provided with matching
+        // types, the harness builds successfully
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(7));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0)).isEqualTo(Row.of(14));
+        }
+    }
+
+    @Test
+    void testInlineTypeMismatchWithBuilderConfigRejected() {
+        // Verify that when inline annotation and builder config specify different types,
+        // build() throws an exception
+        Exception exception =
+                assertThrows(
+                        IllegalStateException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class)
+                                    .withTableArgument(
+                                            "input", DataTypes.of("ROW<value BIGINT>")) // Mismatch!
+                                    .build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Type mismatch")
+                .contains("input")
+                .contains("INT")
+                .contains("BIGINT");
+    }
+
+    // -------------------------------------------------------------------------
+    // Element Processing Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testProcessElementOnMultiTableThrows() throws Exception {
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                        .withTableArgument("leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                        .withTableArgument("rightTable", DataTypes.of("ROW<id INT, value STRING>"))
+                        .withPartitionBy("leftTable", "id")
+                        .withPartitionBy("rightTable", "id")
+                        .build()) {
+
+            Exception exception =
+                    assertThrows(
+                            IllegalStateException.class,
+                            () -> harness.processElement(Row.of(1, "Alice")));
+            assertThat(exception.getMessage())
+                    .contains("multiple table arguments")
+                    .contains("processElementForTable");
+        }
+    }
+
+    @Test
+    void testProcessElementForTableMultipleTables() throws Exception {
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                        .withTableArgument("leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                        .withTableArgument("rightTable", DataTypes.of("ROW<id INT, value STRING>"))
+                        .withPartitionBy("leftTable", "id")
+                        .withPartitionBy("rightTable", "id")
+                        .build()) {
+
+            harness.processElementForTable("leftTable", Row.of(1, "Alice"));
+            harness.processElementForTable("leftTable", Row.of(2, "Bob"));
+
+            harness.processElementForTable("rightTable", Row.of(1, "value1"));
+            harness.processElementForTable("rightTable", Row.of(2, "value2"));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+
+            assertThat(output.get(0).getField(0)).isEqualTo(1);
+            assertThat(output.get(0).getField(1)).isNull();
+            assertThat(output.get(0).getField(2)).asString().startsWith("LEFT:");
+
+            assertThat(output.get(1).getField(0)).isEqualTo(2);
+            assertThat(output.get(1).getField(1)).isNull();
+            assertThat(output.get(1).getField(2)).asString().startsWith("LEFT:");
+
+            assertThat(output.get(2).getField(0)).isNull();
+            assertThat(output.get(2).getField(1)).isEqualTo(1);
+            assertThat(output.get(2).getField(2)).asString().startsWith("RIGHT:");
+
+            assertThat(output.get(3).getField(0)).isNull();
+            assertThat(output.get(3).getField(1)).isEqualTo(2);
+            assertThat(output.get(3).getField(2)).asString().startsWith("RIGHT:");
+        }
+    }
+
+    @Test
+    void testPassthroughEndToEnd() throws Exception {

Review Comment:
   Couldn't `testProcessElementWithRowKind()` be easily extended with more asserts on the result to check the same as this test method?



##########
flink-table/flink-table-test-utils/src/test/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarnessTest.java:
##########
@@ -0,0 +1,1058 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.api.ValidationException;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class ProcessTableFunctionTestHarnessTest {
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PassthroughPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** Filter PTF for testing scalar argument handling. */
+    @DataTypeHint("ROW<value INT>")
+    public static class FilterPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer threshold) {
+            // Use named field access - converter enriches Row with field names
+            int value = input.getFieldAs("value");
+            if (value >= threshold) {
+                collect(input);
+            }
+        }
+    }
+
+    /** PTF for testing transformation of output types. */
+    @DataTypeHint("ROW<doubled INT, original INT>")
+    public static class DoublePTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2, value));
+        }
+    }
+
+    /** PTF with for testing table argument names set via argument hints. */
+    @DataTypeHint("ROW<value INT>")
+    public static class ExplicitNamePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "customName")
+                        Row actualParamName) {
+            collect(actualParamName);
+        }
+    }
+
+    /** PTF with inline type annotation - no builder config needed. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class InlineTypePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(
+                                value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+                                type = @DataTypeHint("ROW<value INT>"))
+                        Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PartitionedPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+            collect(Row.of((Integer) input.getFieldAs("value")));
+        }
+    }
+
+    /**
+     * PTF with PASS_COLUMNS_THROUGH for validating that all input columns are prepended to output.
+     */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class PassColumnsThroughPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** PTF with OPTIONAL_PARTITION_BY for validating that partition setup can be omitted. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class OptionalPartitionPTF extends ProcessTableFunction<Row> {
+
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.OPTIONAL_PARTITION_BY
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** Simple POJO for testing structured type input/output. */
+    public static class User {
+        public String name;
+        public int age;
+
+        public User() {}
+
+        public User(String name, int age) {
+            this.name = name;
+            this.age = age;
+        }
+
+        @Override
+        public String toString() {
+            return "User{name='" + name + "', age=" + age + '}';
+        }
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o) {
+                return true;
+            }
+            if (o == null || getClass() != o.getClass()) {
+                return false;
+            }
+            User user = (User) o;
+            return age == user.age && java.util.Objects.equals(name, user.name);
+        }
+
+        @Override
+        public int hashCode() {
+            return java.util.Objects.hash(name, age);
+        }
+    }
+
+    /** PTF for testing structured type inputs. */
+    @DataTypeHint("ROW<name STRING, age INT>")
+    public static class UserPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            if (user.age >= 18) {
+                collect(Row.of(user.name, user.age));
+            }
+        }
+    }
+
+    /** PTF that transforms structured type inputs and outputs. */
+    public static class UserTransformPTF extends ProcessTableFunction<User> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            User transformed = new User(user.name, user.age + 1);
+            collect(transformed);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "on_time". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgOnTimePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "on_time")
+                        Row input) {
+            collect(input);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "uid". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgUidPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) String uid) {
+            collect(input);
+        }
+    }
+
+    /** Multi-table PTF for validating multi-input processing. */
+    @DataTypeHint("ROW<output STRING>")
+    public static class MultiTableJoinPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /**
+     * Multi-table PTF with one POJO and one Row argument, for testing partitioning with structured
+     * types.
+     */
+    @DataTypeHint("ROW<source STRING, age INT>")
+    public static class MixedTypeMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) User userTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rowTable) {
+            if (userTable != null) {
+                collect(Row.of("USER", userTable.age));
+            }
+            if (rowTable != null) {
+                collect(Row.of("ROW", rowTable.getFieldAs("age")));
+            }
+        }
+    }
+
+    /**
+     * Invalid PTF - uses PASS_COLUMNS_THROUGH with multiple table arguments (not allowed per Flink
+     * docs).
+     */
+    @DataTypeHint("ROW<output STRING>")
+    public static class InvalidPassColumnsThroughMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /** PTF with only scalar arguments, no tables. */
+    @DataTypeHint("ROW<sum INT>")
+    public static class ScalarOnlyPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer a,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer b) {
+            collect(Row.of(a + b));
+        }
+    }
+
+    /** PTF with Context parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithContext extends ProcessTableFunction<Row> {
+        public void eval(Context ctx, @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** PTF with State parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithState extends ProcessTableFunction<Row> {
+        public static class CountState {
+            public long counter = 0L;
+        }
+
+        public void eval(
+                @StateHint CountState state,
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Builder Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testBuilderRejectsDuplicateScalarArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("threshold", 50)
+                                    .withScalarArgument("threshold", 100);
+                        });
+
+        assertThat(exception.getMessage()).contains("threshold");
+    }
+
+    @Test
+    void testBuilderRejectsDuplicateTableArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, value INT>"));
+                        });
+
+        assertThat(exception.getMessage()).contains("leftTable");
+    }
+
+    @Test
+    void testBuilderRejectsMixedDuplicateArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("input", 42);
+                        });
+
+        assertThat(exception.getMessage()).contains("input");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentOnTime() {
+        // We should reject PTFs that use reserved argument name "on_time"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgOnTimePTF.class)
+                        .withTableArgument("on_time", DataTypes.of("ROW<id INT>"));
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("on_time");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentUid() {
+        // We should reject PTFs that use reserved argument name "uid"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgUidPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<id INT>"))
+                        .withScalarArgument("uid", "my-id");
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("uid");
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testExplicitNameTakesPrecedence() throws Exception {
+        // Verify that @ArgumentHint(name="customName") takes precedence over actual parameter
+        // name when processing elements and calling eval.
+
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ExplicitNamePTF.class)
+                        .withTableArgument("customName", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(42));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0).getField(0)).isEqualTo(42);
+            assertThat(output.get(1).getField(0)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testScalarOnlyPTF() throws Exception {
+        // Test scalar-only PTF with no table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ScalarOnlyPTF.class)
+                        .withScalarArgument("a", 10)
+                        .withScalarArgument("b", 20)
+                        .build()) {
+
+            harness.process();
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0).getField(0)).isEqualTo(30);
+        }
+    }
+
+    @Test
+    void testInvokeRejectsTableArguments() throws Exception {
+        // Verify that invoke() rejects PTFs with table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50)
+                        .build()) {
+
+            Exception exception =
+                    assertThrows(
+                            IllegalStateException.class,
+                            () -> {
+                                harness.process();
+                            });
+
+            assertThat(exception.getMessage()).contains("process() is only for scalar-only PTFs");
+        }
+    }
+
+    @Test
+    void testTableProcessingWithScalarArgument() throws Exception {
+        // Test a PTF that uses a scalar parameter
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50) // Scalar argument: threshold = 50
+                        .build()) {
+
+            harness.processElement(Row.of(25));
+            harness.processElement(Row.of(75));
+            harness.processElement(Row.of(50));
+            harness.processElement(Row.of(10));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0).getField(0)).isEqualTo(75);
+            assertThat(output.get(1).getField(0)).isEqualTo(50);
+            assertThat(output.get(2).getField(0)).isEqualTo(100);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Trait Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testProcessElementWithRowKind() throws Exception {
+        // Verify RowKind is preserved through processing (ROW_SEMANTIC_TABLE)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(RowKind.INSERT, 10);
+            harness.processElement(RowKind.UPDATE_BEFORE, 15);
+            harness.processElement(RowKind.UPDATE_AFTER, 20);
+            harness.processElement(RowKind.DELETE, 30);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+            assertThat(output.get(0).getKind()).isEqualTo(RowKind.INSERT);
+            assertThat(output.get(1).getKind()).isEqualTo(RowKind.UPDATE_BEFORE);
+            assertThat(output.get(2).getKind()).isEqualTo(RowKind.UPDATE_AFTER);
+            assertThat(output.get(3).getKind()).isEqualTo(RowKind.DELETE);
+        }
+    }
+
+    @Test
+    void testPassColumnsThroughTrait() throws Exception {
+        // Verify PASS_COLUMNS_THROUGH prepends ALL input columns (not just partition keys)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassColumnsThroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 10, 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("B", 20, 40));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithoutPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY allows omitting partition configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+            harness.processElement(Row.of("C", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of(20));
+            assertThat(output.get(1)).isEqualTo(Row.of(40));
+            assertThat(output.get(2)).isEqualTo(Row.of(60));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY still works when partition is configured
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("A", 5));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("A", 10));
+            assertThat(output.get(2)).isEqualTo(Row.of("B", 40));
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Data Type Conversion Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testNamedRowFieldOrdering() throws Exception {
+        // Test what happens when Row field order differs from DataType schema order
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row rowA = Row.withNames();
+            rowA.setField("value", 100);
+            rowA.setField("user", "Alice");
+
+            harness.processElement(rowA);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+
+            // Positional access follows schema order
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testPositionalRowWithWrongTypeOrder() throws Exception {
+        // Verify that type mismatches are caught when Row values don't match schema types
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row wrongOrderRow = Row.of(10, "Alice");
+
+            assertThrows(ClassCastException.class, () -> harness.processElement(wrongOrderRow));
+        }
+    }
+
+    @Test
+    void testStructuredTypeInput() throws Exception {
+        // Test PTF that accepts structured types instead of Row
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+            harness.processElement(Row.of("Bob", 17));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(25);
+        }
+    }
+
+    @Test
+    void testStructuredTypeInputAndOutput() throws Exception {
+        // Test PTF with structured type inputs and outputs
+        try (ProcessTableFunctionTestHarness<User> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserTransformPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+
+            List<User> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            User result = output.get(0);
+            assertThat(result.getClass()).isEqualTo(User.class);
+            assertThat(result.name).isEqualTo("Alice");
+            assertThat(result.age).isEqualTo(26);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Partitioning Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testSetSemanticWithPartitionByName() throws Exception {
+        // Verify set-semantic table with partition configuration by column name
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key") // Partition by "key" column name
+                        .build()) {
+
+            harness.processElement(Row.of("X", 10));
+            harness.processElement(Row.of("Y", 20));
+            harness.processElement(Row.of("X", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0)).isEqualTo(Row.of("X", 10));
+            assertThat(output.get(1)).isEqualTo(Row.of("Y", 20));
+            assertThat(output.get(2)).isEqualTo(Row.of("X", 30));
+        }
+    }
+
+    @Test
+    void testSetSemanticWithMultiplePartitionColumns() throws Exception {
+        // Verify composite partition key (multiple columns)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument(
+                                "input",
+                                DataTypes.of("ROW<region STRING, country STRING, value INT>"))
+                        .withPartitionBy("input", "region", "country")
+                        .build()) {
+
+            harness.processElement(Row.of("EU", "DE", 100));
+            harness.processElement(Row.of("EU", "DE", 200));
+            harness.processElement(Row.of("EU", "FR", 300));
+            harness.processElement(Row.of("US", "NY", 400));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+        }
+    }
+
+    @Test
+    void testMultipleSetSemanticTablesWithMatchingPartitionKeys() throws Exception {
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                        .withTableArgument("leftTable", DataTypes.of("ROW<name STRING, score INT>"))
+                        .withPartitionBy("leftTable", "name")
+                        .withTableArgument(
+                                "rightTable", DataTypes.of("ROW<name STRING, city STRING>"))
+                        .withPartitionBy("rightTable", "name")
+                        .build()) {
+
+            harness.processElementForTable("leftTable", Row.of("Alice", 100));
+            harness.processElementForTable("leftTable", Row.of("Bob", 200));
+
+            harness.processElementForTable("rightTable", Row.of("Alice", "Berlin"));
+            harness.processElementForTable("rightTable", Row.of("Bob", "London"));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+
+            assertThat(output.get(0).getField(0)).isEqualTo("Alice");
+            assertThat(output.get(0).getField(1)).isNull();
+            assertThat(output.get(0).getField(2)).isEqualTo("LEFT: +I[Alice, 100]");
+
+            assertThat(output.get(1).getField(0)).isEqualTo("Bob");
+            assertThat(output.get(1).getField(1)).isNull();
+            assertThat(output.get(1).getField(2)).isEqualTo("LEFT: +I[Bob, 200]");
+
+            assertThat(output.get(2).getField(0)).isNull();
+            assertThat(output.get(2).getField(1)).isEqualTo("Alice");
+            assertThat(output.get(2).getField(2)).isEqualTo("RIGHT: +I[Alice, Berlin]");
+
+            assertThat(output.get(3).getField(0)).isNull();
+            assertThat(output.get(3).getField(1)).isEqualTo("Bob");
+            assertThat(output.get(3).getField(2)).isEqualTo("RIGHT: +I[Bob, London]");
+        }
+    }
+
+    @Test
+    void testMultipleSetSemanticTablesWithMismatchedPartitionTypes() {
+        // Verify that multi-table PTFs with inconsistent partition types are rejected
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                                    .withPartitionBy("leftTable", "id")
+                                    .withTableArgument(
+                                            "rightTable",
+                                            DataTypes.of("ROW<key STRING, city STRING>"))
+                                    .withPartitionBy("rightTable", "key")
+                                    .build();
+                        });
+
+        assertThat(exception.getMessage()).contains("Inconsistent partitioning");
+    }
+
+    @Test
+    void testMultipleSetSemanticTablesWithMismatchedPartitionColumnCount() {
+        // Verify that multi-table PTFs with different partition column counts are rejected
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                                    .withTableArgument(
+                                            "leftTable",
+                                            DataTypes.of("ROW<id INT, region STRING, name STRING>"))
+                                    .withPartitionBy("leftTable", "id", "region")
+                                    .withTableArgument(
+                                            "rightTable", DataTypes.of("ROW<id INT, city STRING>"))
+                                    .withPartitionBy("rightTable", "id")
+                                    .build();
+                        });
+
+        assertThat(exception.getMessage()).contains("Inconsistent partitioning");
+    }
+
+    @Test
+    void testPassColumnsThroughWithMultipleTablesRejected() {
+        // Verify that PASS_COLUMNS_THROUGH is rejected when used with multiple table arguments
+        Exception exception =
+                assertThrows(
+                        org.apache.flink.table.api.ValidationException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(
+                                            InvalidPassColumnsThroughMultiTablePTF.class)
+                                    .withTableArgument("leftTable", DataTypes.of("ROW<a INT>"))
+                                    .withTableArgument("rightTable", DataTypes.of("ROW<b INT>"))
+                                    .build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Pass-through columns")
+                .contains("multiple table arguments");
+    }
+
+    @Test
+    void testInlineTypeAnnotation() throws Exception {
+        // Verify that PTFs can declare table argument types via @ArgumentHint(type = ...)
+        // without needing .withTableArgument() configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class).build()) {
+
+            harness.processElement(Row.of(5));
+            harness.processElement(Row.of(10));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0)).isEqualTo(Row.of(10));
+            assertThat(output.get(1)).isEqualTo(Row.of(20));
+        }
+    }
+
+    @Test
+    void testInlineTypeMatchesBuilderConfig() throws Exception {
+        // Verify that when both inline annotation and builder config are provided with matching
+        // types, the harness builds successfully
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(7));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0)).isEqualTo(Row.of(14));
+        }
+    }
+
+    @Test
+    void testInlineTypeMismatchWithBuilderConfigRejected() {
+        // Verify that when inline annotation and builder config specify different types,
+        // build() throws an exception
+        Exception exception =
+                assertThrows(
+                        IllegalStateException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class)
+                                    .withTableArgument(
+                                            "input", DataTypes.of("ROW<value BIGINT>")) // Mismatch!
+                                    .build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Type mismatch")
+                .contains("input")
+                .contains("INT")
+                .contains("BIGINT");
+    }
+
+    // -------------------------------------------------------------------------
+    // Element Processing Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testProcessElementOnMultiTableThrows() throws Exception {
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                        .withTableArgument("leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                        .withTableArgument("rightTable", DataTypes.of("ROW<id INT, value STRING>"))
+                        .withPartitionBy("leftTable", "id")
+                        .withPartitionBy("rightTable", "id")
+                        .build()) {
+
+            Exception exception =
+                    assertThrows(
+                            IllegalStateException.class,
+                            () -> harness.processElement(Row.of(1, "Alice")));
+            assertThat(exception.getMessage())
+                    .contains("multiple table arguments")
+                    .contains("processElementForTable");
+        }
+    }
+
+    @Test
+    void testProcessElementForTableMultipleTables() throws Exception {
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                        .withTableArgument("leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                        .withTableArgument("rightTable", DataTypes.of("ROW<id INT, value STRING>"))
+                        .withPartitionBy("leftTable", "id")
+                        .withPartitionBy("rightTable", "id")
+                        .build()) {
+
+            harness.processElementForTable("leftTable", Row.of(1, "Alice"));
+            harness.processElementForTable("leftTable", Row.of(2, "Bob"));
+
+            harness.processElementForTable("rightTable", Row.of(1, "value1"));
+            harness.processElementForTable("rightTable", Row.of(2, "value2"));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+
+            assertThat(output.get(0).getField(0)).isEqualTo(1);
+            assertThat(output.get(0).getField(1)).isNull();
+            assertThat(output.get(0).getField(2)).asString().startsWith("LEFT:");
+
+            assertThat(output.get(1).getField(0)).isEqualTo(2);
+            assertThat(output.get(1).getField(1)).isNull();
+            assertThat(output.get(1).getField(2)).asString().startsWith("LEFT:");
+
+            assertThat(output.get(2).getField(0)).isNull();
+            assertThat(output.get(2).getField(1)).isEqualTo(1);
+            assertThat(output.get(2).getField(2)).asString().startsWith("RIGHT:");
+
+            assertThat(output.get(3).getField(0)).isNull();
+            assertThat(output.get(3).getField(1)).isEqualTo(2);
+            assertThat(output.get(3).getField(2)).asString().startsWith("RIGHT:");
+        }
+    }
+
+    @Test
+    void testPassthroughEndToEnd() throws Exception {
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(42));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0).getField(0)).isEqualTo(42);
+            assertThat(output.get(1).getField(0)).isEqualTo(100);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Output Collection Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testClearOutput() throws Exception {
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(10));
+            harness.processElement(Row.of(20));
+            assertThat(harness.getOutput()).hasSize(2);
+
+            harness.clearOutput();
+            assertThat(harness.getOutput()).isEmpty();
+
+            harness.processElement(Row.of(30));
+            assertThat(harness.getOutput()).hasSize(1);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Error Cases Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testProcessElementForTableWithInvalidName() throws Exception {
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            Exception exception =
+                    assertThrows(
+                            IllegalArgumentException.class,
+                            () -> harness.processElementForTable("nonexistent", Row.of(42)));
+            assertThat(exception.getMessage()).contains("nonexistent");
+        }
+    }
+
+    @Test
+    void testContextParameterRejected() {
+        Exception exception =
+                assertThrows(
+                        IllegalStateException.class,
+                        () ->
+                                ProcessTableFunctionTestHarness.ofClass(PTFWithContext.class)
+                                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                        .build());
+
+        assertThat(exception.getMessage())
+                .contains("does not yet support Context parameters")
+                .contains("Context parameter")
+                .contains("position 0");
+    }
+
+    @Test
+    void testStateParameterRejected() {
+        Exception exception =
+                assertThrows(
+                        IllegalStateException.class,
+                        () ->
+                                ProcessTableFunctionTestHarness.ofClass(PTFWithState.class)
+                                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                        .build());
+
+        assertThat(exception.getMessage())
+                .contains("does not yet support state parameters")
+                .contains("@StateHint parameter")
+                .contains("position 0");
+    }
+
+    @Test
+    void testSetSemanticMissingPartitionConfigThrows() {
+        Exception exception =
+                assertThrows(
+                        IllegalStateException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                                    .withTableArgument(
+                                            "input", DataTypes.of("ROW<key STRING, value INT>"))
+                                    .build();
+                        });
+
+        assertThat(exception.getMessage()).contains("No partition configuration found");
+        assertThat(exception.getMessage()).contains("withPartitionBy");
+    }
+
+    @Test
+    void testPartitionByInvalidColumnName() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                                    .withTableArgument(
+                                            "input", DataTypes.of("ROW<key STRING, value INT>"))
+                                    .withPartitionBy("input", "nonexistent")
+                                    .build();
+                        });
+
+        assertThat(exception.getMessage()).contains("not found");
+        assertThat(exception.getMessage()).contains("Available columns");
+    }
+
+    @Test
+    void testPartitionByDuplicateConfigThrows() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                                    .withTableArgument(
+                                            "input", DataTypes.of("ROW<key STRING, value INT>"))
+                                    .withPartitionBy("input", "key") // First config
+                                    .withPartitionBy("input", "key"); // Duplicate - should fail
+                        });
+
+        assertThat(exception.getMessage()).contains("Partition config already exists");
+    }
+
+    @Test
+    void testMultipleSetSemanticTablesWithStructuredTypePartitioning() throws Exception {
+        // Verify that multi-table PTFs work when one argument is a structured type
+        // and another is a Row, both partitioned by the same field type
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(MixedTypeMultiTablePTF.class)
+                        .withTableArgument("userTable")
+                        .withPartitionBy("userTable", "age")
+                        .withTableArgument(
+                                "rowTable", DataTypes.of("ROW<name STRING, age INT NOT NULL>"))
+                        .withPartitionBy("rowTable", "age")
+                        .build()) {
+
+            harness.processElementForTable("userTable", Row.of("Alice", 25));
+            harness.processElementForTable("rowTable", Row.of("Bob", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+        }
+    }

Review Comment:
   nit: not an error case test. Move up to partitioning tests?



##########
flink-table/flink-table-test-utils/src/test/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarnessTest.java:
##########
@@ -0,0 +1,1058 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.api.ValidationException;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class ProcessTableFunctionTestHarnessTest {
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PassthroughPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** Filter PTF for testing scalar argument handling. */
+    @DataTypeHint("ROW<value INT>")
+    public static class FilterPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer threshold) {
+            // Use named field access - converter enriches Row with field names
+            int value = input.getFieldAs("value");
+            if (value >= threshold) {
+                collect(input);
+            }
+        }
+    }
+
+    /** PTF for testing transformation of output types. */
+    @DataTypeHint("ROW<doubled INT, original INT>")
+    public static class DoublePTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2, value));
+        }
+    }
+
+    /** PTF with for testing table argument names set via argument hints. */
+    @DataTypeHint("ROW<value INT>")
+    public static class ExplicitNamePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "customName")
+                        Row actualParamName) {
+            collect(actualParamName);
+        }
+    }
+
+    /** PTF with inline type annotation - no builder config needed. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class InlineTypePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(
+                                value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+                                type = @DataTypeHint("ROW<value INT>"))
+                        Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PartitionedPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+            collect(Row.of((Integer) input.getFieldAs("value")));
+        }
+    }
+
+    /**
+     * PTF with PASS_COLUMNS_THROUGH for validating that all input columns are prepended to output.
+     */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class PassColumnsThroughPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** PTF with OPTIONAL_PARTITION_BY for validating that partition setup can be omitted. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class OptionalPartitionPTF extends ProcessTableFunction<Row> {
+
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.OPTIONAL_PARTITION_BY
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** Simple POJO for testing structured type input/output. */
+    public static class User {
+        public String name;
+        public int age;
+
+        public User() {}
+
+        public User(String name, int age) {
+            this.name = name;
+            this.age = age;
+        }
+
+        @Override
+        public String toString() {
+            return "User{name='" + name + "', age=" + age + '}';
+        }
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o) {
+                return true;
+            }
+            if (o == null || getClass() != o.getClass()) {
+                return false;
+            }
+            User user = (User) o;
+            return age == user.age && java.util.Objects.equals(name, user.name);
+        }
+
+        @Override
+        public int hashCode() {
+            return java.util.Objects.hash(name, age);
+        }
+    }
+
+    /** PTF for testing structured type inputs. */
+    @DataTypeHint("ROW<name STRING, age INT>")
+    public static class UserPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            if (user.age >= 18) {
+                collect(Row.of(user.name, user.age));
+            }
+        }
+    }
+
+    /** PTF that transforms structured type inputs and outputs. */
+    public static class UserTransformPTF extends ProcessTableFunction<User> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            User transformed = new User(user.name, user.age + 1);
+            collect(transformed);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "on_time". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgOnTimePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "on_time")
+                        Row input) {
+            collect(input);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "uid". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgUidPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) String uid) {
+            collect(input);
+        }
+    }
+
+    /** Multi-table PTF for validating multi-input processing. */
+    @DataTypeHint("ROW<output STRING>")
+    public static class MultiTableJoinPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /**
+     * Multi-table PTF with one POJO and one Row argument, for testing partitioning with structured
+     * types.
+     */
+    @DataTypeHint("ROW<source STRING, age INT>")
+    public static class MixedTypeMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) User userTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rowTable) {
+            if (userTable != null) {
+                collect(Row.of("USER", userTable.age));
+            }
+            if (rowTable != null) {
+                collect(Row.of("ROW", rowTable.getFieldAs("age")));
+            }
+        }
+    }
+
+    /**
+     * Invalid PTF - uses PASS_COLUMNS_THROUGH with multiple table arguments (not allowed per Flink
+     * docs).
+     */
+    @DataTypeHint("ROW<output STRING>")
+    public static class InvalidPassColumnsThroughMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /** PTF with only scalar arguments, no tables. */
+    @DataTypeHint("ROW<sum INT>")
+    public static class ScalarOnlyPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer a,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer b) {
+            collect(Row.of(a + b));
+        }
+    }
+
+    /** PTF with Context parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithContext extends ProcessTableFunction<Row> {
+        public void eval(Context ctx, @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** PTF with State parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithState extends ProcessTableFunction<Row> {
+        public static class CountState {
+            public long counter = 0L;
+        }
+
+        public void eval(
+                @StateHint CountState state,
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Builder Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testBuilderRejectsDuplicateScalarArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("threshold", 50)
+                                    .withScalarArgument("threshold", 100);
+                        });
+
+        assertThat(exception.getMessage()).contains("threshold");
+    }
+
+    @Test
+    void testBuilderRejectsDuplicateTableArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, value INT>"));
+                        });
+
+        assertThat(exception.getMessage()).contains("leftTable");
+    }
+
+    @Test
+    void testBuilderRejectsMixedDuplicateArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("input", 42);
+                        });
+
+        assertThat(exception.getMessage()).contains("input");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentOnTime() {
+        // We should reject PTFs that use reserved argument name "on_time"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgOnTimePTF.class)
+                        .withTableArgument("on_time", DataTypes.of("ROW<id INT>"));
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("on_time");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentUid() {
+        // We should reject PTFs that use reserved argument name "uid"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgUidPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<id INT>"))
+                        .withScalarArgument("uid", "my-id");
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("uid");
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testExplicitNameTakesPrecedence() throws Exception {
+        // Verify that @ArgumentHint(name="customName") takes precedence over actual parameter
+        // name when processing elements and calling eval.
+
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ExplicitNamePTF.class)
+                        .withTableArgument("customName", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(42));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0).getField(0)).isEqualTo(42);
+            assertThat(output.get(1).getField(0)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testScalarOnlyPTF() throws Exception {
+        // Test scalar-only PTF with no table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ScalarOnlyPTF.class)
+                        .withScalarArgument("a", 10)
+                        .withScalarArgument("b", 20)
+                        .build()) {
+
+            harness.process();
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0).getField(0)).isEqualTo(30);
+        }
+    }
+
+    @Test
+    void testInvokeRejectsTableArguments() throws Exception {
+        // Verify that invoke() rejects PTFs with table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50)
+                        .build()) {
+
+            Exception exception =
+                    assertThrows(
+                            IllegalStateException.class,
+                            () -> {
+                                harness.process();
+                            });
+
+            assertThat(exception.getMessage()).contains("process() is only for scalar-only PTFs");
+        }
+    }
+
+    @Test
+    void testTableProcessingWithScalarArgument() throws Exception {
+        // Test a PTF that uses a scalar parameter
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50) // Scalar argument: threshold = 50
+                        .build()) {
+
+            harness.processElement(Row.of(25));
+            harness.processElement(Row.of(75));
+            harness.processElement(Row.of(50));
+            harness.processElement(Row.of(10));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0).getField(0)).isEqualTo(75);
+            assertThat(output.get(1).getField(0)).isEqualTo(50);
+            assertThat(output.get(2).getField(0)).isEqualTo(100);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Trait Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testProcessElementWithRowKind() throws Exception {
+        // Verify RowKind is preserved through processing (ROW_SEMANTIC_TABLE)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(RowKind.INSERT, 10);
+            harness.processElement(RowKind.UPDATE_BEFORE, 15);
+            harness.processElement(RowKind.UPDATE_AFTER, 20);
+            harness.processElement(RowKind.DELETE, 30);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+            assertThat(output.get(0).getKind()).isEqualTo(RowKind.INSERT);
+            assertThat(output.get(1).getKind()).isEqualTo(RowKind.UPDATE_BEFORE);
+            assertThat(output.get(2).getKind()).isEqualTo(RowKind.UPDATE_AFTER);
+            assertThat(output.get(3).getKind()).isEqualTo(RowKind.DELETE);
+        }
+    }
+
+    @Test
+    void testPassColumnsThroughTrait() throws Exception {
+        // Verify PASS_COLUMNS_THROUGH prepends ALL input columns (not just partition keys)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassColumnsThroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 10, 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("B", 20, 40));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithoutPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY allows omitting partition configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+            harness.processElement(Row.of("C", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of(20));
+            assertThat(output.get(1)).isEqualTo(Row.of(40));
+            assertThat(output.get(2)).isEqualTo(Row.of(60));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY still works when partition is configured
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("A", 5));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("A", 10));
+            assertThat(output.get(2)).isEqualTo(Row.of("B", 40));
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Data Type Conversion Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testNamedRowFieldOrdering() throws Exception {
+        // Test what happens when Row field order differs from DataType schema order
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row rowA = Row.withNames();
+            rowA.setField("value", 100);
+            rowA.setField("user", "Alice");
+
+            harness.processElement(rowA);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+
+            // Positional access follows schema order
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testPositionalRowWithWrongTypeOrder() throws Exception {
+        // Verify that type mismatches are caught when Row values don't match schema types
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row wrongOrderRow = Row.of(10, "Alice");
+
+            assertThrows(ClassCastException.class, () -> harness.processElement(wrongOrderRow));
+        }
+    }
+
+    @Test
+    void testStructuredTypeInput() throws Exception {
+        // Test PTF that accepts structured types instead of Row

Review Comment:
   nit: IMO, this comment is a bit confusing because we are in fact passing a Row here (instead of a `User` object).
   I assume the test aims to assert that the PTF can declare an input type as POJO and the framework is able to convert that into a `User`



##########
flink-table/flink-table-test-utils/src/test/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarnessTest.java:
##########
@@ -0,0 +1,1058 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.api.ValidationException;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class ProcessTableFunctionTestHarnessTest {
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PassthroughPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** Filter PTF for testing scalar argument handling. */
+    @DataTypeHint("ROW<value INT>")
+    public static class FilterPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer threshold) {
+            // Use named field access - converter enriches Row with field names
+            int value = input.getFieldAs("value");
+            if (value >= threshold) {
+                collect(input);
+            }
+        }
+    }
+
+    /** PTF for testing transformation of output types. */
+    @DataTypeHint("ROW<doubled INT, original INT>")
+    public static class DoublePTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2, value));
+        }
+    }
+
+    /** PTF with for testing table argument names set via argument hints. */
+    @DataTypeHint("ROW<value INT>")
+    public static class ExplicitNamePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "customName")
+                        Row actualParamName) {
+            collect(actualParamName);
+        }
+    }
+
+    /** PTF with inline type annotation - no builder config needed. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class InlineTypePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(
+                                value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+                                type = @DataTypeHint("ROW<value INT>"))
+                        Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PartitionedPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+            collect(Row.of((Integer) input.getFieldAs("value")));
+        }
+    }
+
+    /**
+     * PTF with PASS_COLUMNS_THROUGH for validating that all input columns are prepended to output.
+     */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class PassColumnsThroughPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** PTF with OPTIONAL_PARTITION_BY for validating that partition setup can be omitted. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class OptionalPartitionPTF extends ProcessTableFunction<Row> {
+
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.OPTIONAL_PARTITION_BY
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** Simple POJO for testing structured type input/output. */
+    public static class User {
+        public String name;
+        public int age;
+
+        public User() {}
+
+        public User(String name, int age) {
+            this.name = name;
+            this.age = age;
+        }
+
+        @Override
+        public String toString() {
+            return "User{name='" + name + "', age=" + age + '}';
+        }
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o) {
+                return true;
+            }
+            if (o == null || getClass() != o.getClass()) {
+                return false;
+            }
+            User user = (User) o;
+            return age == user.age && java.util.Objects.equals(name, user.name);
+        }
+
+        @Override
+        public int hashCode() {
+            return java.util.Objects.hash(name, age);
+        }
+    }
+
+    /** PTF for testing structured type inputs. */
+    @DataTypeHint("ROW<name STRING, age INT>")
+    public static class UserPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            if (user.age >= 18) {
+                collect(Row.of(user.name, user.age));
+            }
+        }
+    }
+
+    /** PTF that transforms structured type inputs and outputs. */
+    public static class UserTransformPTF extends ProcessTableFunction<User> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            User transformed = new User(user.name, user.age + 1);
+            collect(transformed);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "on_time". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgOnTimePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "on_time")
+                        Row input) {
+            collect(input);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "uid". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgUidPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) String uid) {
+            collect(input);
+        }
+    }
+
+    /** Multi-table PTF for validating multi-input processing. */
+    @DataTypeHint("ROW<output STRING>")
+    public static class MultiTableJoinPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /**
+     * Multi-table PTF with one POJO and one Row argument, for testing partitioning with structured
+     * types.
+     */
+    @DataTypeHint("ROW<source STRING, age INT>")
+    public static class MixedTypeMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) User userTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rowTable) {
+            if (userTable != null) {
+                collect(Row.of("USER", userTable.age));
+            }
+            if (rowTable != null) {
+                collect(Row.of("ROW", rowTable.getFieldAs("age")));
+            }
+        }
+    }
+
+    /**
+     * Invalid PTF - uses PASS_COLUMNS_THROUGH with multiple table arguments (not allowed per Flink
+     * docs).
+     */
+    @DataTypeHint("ROW<output STRING>")
+    public static class InvalidPassColumnsThroughMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /** PTF with only scalar arguments, no tables. */
+    @DataTypeHint("ROW<sum INT>")
+    public static class ScalarOnlyPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer a,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer b) {
+            collect(Row.of(a + b));
+        }
+    }
+
+    /** PTF with Context parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithContext extends ProcessTableFunction<Row> {
+        public void eval(Context ctx, @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** PTF with State parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithState extends ProcessTableFunction<Row> {
+        public static class CountState {
+            public long counter = 0L;
+        }
+
+        public void eval(
+                @StateHint CountState state,
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Builder Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testBuilderRejectsDuplicateScalarArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("threshold", 50)
+                                    .withScalarArgument("threshold", 100);
+                        });
+
+        assertThat(exception.getMessage()).contains("threshold");
+    }
+
+    @Test
+    void testBuilderRejectsDuplicateTableArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, value INT>"));
+                        });
+
+        assertThat(exception.getMessage()).contains("leftTable");
+    }
+
+    @Test
+    void testBuilderRejectsMixedDuplicateArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("input", 42);
+                        });
+
+        assertThat(exception.getMessage()).contains("input");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentOnTime() {
+        // We should reject PTFs that use reserved argument name "on_time"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgOnTimePTF.class)
+                        .withTableArgument("on_time", DataTypes.of("ROW<id INT>"));
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("on_time");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentUid() {
+        // We should reject PTFs that use reserved argument name "uid"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgUidPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<id INT>"))
+                        .withScalarArgument("uid", "my-id");
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("uid");
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testExplicitNameTakesPrecedence() throws Exception {
+        // Verify that @ArgumentHint(name="customName") takes precedence over actual parameter
+        // name when processing elements and calling eval.
+
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ExplicitNamePTF.class)
+                        .withTableArgument("customName", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(42));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0).getField(0)).isEqualTo(42);
+            assertThat(output.get(1).getField(0)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testScalarOnlyPTF() throws Exception {
+        // Test scalar-only PTF with no table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ScalarOnlyPTF.class)
+                        .withScalarArgument("a", 10)
+                        .withScalarArgument("b", 20)
+                        .build()) {
+
+            harness.process();
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0).getField(0)).isEqualTo(30);
+        }
+    }
+
+    @Test
+    void testInvokeRejectsTableArguments() throws Exception {
+        // Verify that invoke() rejects PTFs with table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50)
+                        .build()) {
+
+            Exception exception =
+                    assertThrows(
+                            IllegalStateException.class,
+                            () -> {
+                                harness.process();
+                            });
+
+            assertThat(exception.getMessage()).contains("process() is only for scalar-only PTFs");
+        }
+    }
+
+    @Test
+    void testTableProcessingWithScalarArgument() throws Exception {
+        // Test a PTF that uses a scalar parameter
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50) // Scalar argument: threshold = 50
+                        .build()) {
+
+            harness.processElement(Row.of(25));
+            harness.processElement(Row.of(75));
+            harness.processElement(Row.of(50));
+            harness.processElement(Row.of(10));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0).getField(0)).isEqualTo(75);
+            assertThat(output.get(1).getField(0)).isEqualTo(50);
+            assertThat(output.get(2).getField(0)).isEqualTo(100);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Trait Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testProcessElementWithRowKind() throws Exception {
+        // Verify RowKind is preserved through processing (ROW_SEMANTIC_TABLE)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(RowKind.INSERT, 10);
+            harness.processElement(RowKind.UPDATE_BEFORE, 15);
+            harness.processElement(RowKind.UPDATE_AFTER, 20);
+            harness.processElement(RowKind.DELETE, 30);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+            assertThat(output.get(0).getKind()).isEqualTo(RowKind.INSERT);
+            assertThat(output.get(1).getKind()).isEqualTo(RowKind.UPDATE_BEFORE);
+            assertThat(output.get(2).getKind()).isEqualTo(RowKind.UPDATE_AFTER);
+            assertThat(output.get(3).getKind()).isEqualTo(RowKind.DELETE);
+        }
+    }
+
+    @Test
+    void testPassColumnsThroughTrait() throws Exception {
+        // Verify PASS_COLUMNS_THROUGH prepends ALL input columns (not just partition keys)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassColumnsThroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 10, 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("B", 20, 40));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithoutPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY allows omitting partition configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+            harness.processElement(Row.of("C", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of(20));
+            assertThat(output.get(1)).isEqualTo(Row.of(40));
+            assertThat(output.get(2)).isEqualTo(Row.of(60));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY still works when partition is configured
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("A", 5));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("A", 10));
+            assertThat(output.get(2)).isEqualTo(Row.of("B", 40));
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Data Type Conversion Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testNamedRowFieldOrdering() throws Exception {
+        // Test what happens when Row field order differs from DataType schema order
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row rowA = Row.withNames();
+            rowA.setField("value", 100);
+            rowA.setField("user", "Alice");
+
+            harness.processElement(rowA);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+
+            // Positional access follows schema order
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testPositionalRowWithWrongTypeOrder() throws Exception {
+        // Verify that type mismatches are caught when Row values don't match schema types
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row wrongOrderRow = Row.of(10, "Alice");
+
+            assertThrows(ClassCastException.class, () -> harness.processElement(wrongOrderRow));
+        }
+    }
+
+    @Test
+    void testStructuredTypeInput() throws Exception {
+        // Test PTF that accepts structured types instead of Row
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+            harness.processElement(Row.of("Bob", 17));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(25);
+        }
+    }
+
+    @Test
+    void testStructuredTypeInputAndOutput() throws Exception {
+        // Test PTF with structured type inputs and outputs
+        try (ProcessTableFunctionTestHarness<User> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserTransformPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+
+            List<User> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            User result = output.get(0);
+            assertThat(result.getClass()).isEqualTo(User.class);
+            assertThat(result.name).isEqualTo("Alice");
+            assertThat(result.age).isEqualTo(26);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Partitioning Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testSetSemanticWithPartitionByName() throws Exception {
+        // Verify set-semantic table with partition configuration by column name
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key") // Partition by "key" column name
+                        .build()) {
+
+            harness.processElement(Row.of("X", 10));
+            harness.processElement(Row.of("Y", 20));
+            harness.processElement(Row.of("X", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0)).isEqualTo(Row.of("X", 10));
+            assertThat(output.get(1)).isEqualTo(Row.of("Y", 20));
+            assertThat(output.get(2)).isEqualTo(Row.of("X", 30));
+        }
+    }
+
+    @Test
+    void testSetSemanticWithMultiplePartitionColumns() throws Exception {
+        // Verify composite partition key (multiple columns)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument(
+                                "input",
+                                DataTypes.of("ROW<region STRING, country STRING, value INT>"))
+                        .withPartitionBy("input", "region", "country")
+                        .build()) {
+
+            harness.processElement(Row.of("EU", "DE", 100));
+            harness.processElement(Row.of("EU", "DE", 200));
+            harness.processElement(Row.of("EU", "FR", 300));
+            harness.processElement(Row.of("US", "NY", 400));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);

Review Comment:
   also check that the output columns have all expected fields and values?



##########
flink-table/flink-table-test-utils/src/test/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarnessTest.java:
##########
@@ -0,0 +1,1058 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.api.ValidationException;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class ProcessTableFunctionTestHarnessTest {
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PassthroughPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** Filter PTF for testing scalar argument handling. */
+    @DataTypeHint("ROW<value INT>")
+    public static class FilterPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer threshold) {
+            // Use named field access - converter enriches Row with field names
+            int value = input.getFieldAs("value");
+            if (value >= threshold) {
+                collect(input);
+            }
+        }
+    }
+
+    /** PTF for testing transformation of output types. */
+    @DataTypeHint("ROW<doubled INT, original INT>")
+    public static class DoublePTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2, value));
+        }
+    }
+
+    /** PTF with for testing table argument names set via argument hints. */
+    @DataTypeHint("ROW<value INT>")
+    public static class ExplicitNamePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "customName")
+                        Row actualParamName) {
+            collect(actualParamName);
+        }
+    }
+
+    /** PTF with inline type annotation - no builder config needed. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class InlineTypePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(
+                                value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+                                type = @DataTypeHint("ROW<value INT>"))
+                        Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PartitionedPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+            collect(Row.of((Integer) input.getFieldAs("value")));
+        }
+    }
+
+    /**
+     * PTF with PASS_COLUMNS_THROUGH for validating that all input columns are prepended to output.
+     */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class PassColumnsThroughPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** PTF with OPTIONAL_PARTITION_BY for validating that partition setup can be omitted. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class OptionalPartitionPTF extends ProcessTableFunction<Row> {
+
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.OPTIONAL_PARTITION_BY
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** Simple POJO for testing structured type input/output. */
+    public static class User {
+        public String name;
+        public int age;
+
+        public User() {}
+
+        public User(String name, int age) {
+            this.name = name;
+            this.age = age;
+        }
+
+        @Override
+        public String toString() {
+            return "User{name='" + name + "', age=" + age + '}';
+        }
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o) {
+                return true;
+            }
+            if (o == null || getClass() != o.getClass()) {
+                return false;
+            }
+            User user = (User) o;
+            return age == user.age && java.util.Objects.equals(name, user.name);
+        }
+
+        @Override
+        public int hashCode() {
+            return java.util.Objects.hash(name, age);
+        }
+    }
+
+    /** PTF for testing structured type inputs. */
+    @DataTypeHint("ROW<name STRING, age INT>")
+    public static class UserPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            if (user.age >= 18) {
+                collect(Row.of(user.name, user.age));
+            }
+        }
+    }
+
+    /** PTF that transforms structured type inputs and outputs. */
+    public static class UserTransformPTF extends ProcessTableFunction<User> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            User transformed = new User(user.name, user.age + 1);
+            collect(transformed);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "on_time". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgOnTimePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "on_time")
+                        Row input) {
+            collect(input);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "uid". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgUidPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) String uid) {
+            collect(input);
+        }
+    }
+
+    /** Multi-table PTF for validating multi-input processing. */
+    @DataTypeHint("ROW<output STRING>")
+    public static class MultiTableJoinPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /**
+     * Multi-table PTF with one POJO and one Row argument, for testing partitioning with structured
+     * types.
+     */
+    @DataTypeHint("ROW<source STRING, age INT>")
+    public static class MixedTypeMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) User userTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rowTable) {
+            if (userTable != null) {
+                collect(Row.of("USER", userTable.age));
+            }
+            if (rowTable != null) {
+                collect(Row.of("ROW", rowTable.getFieldAs("age")));
+            }
+        }
+    }
+
+    /**
+     * Invalid PTF - uses PASS_COLUMNS_THROUGH with multiple table arguments (not allowed per Flink
+     * docs).
+     */
+    @DataTypeHint("ROW<output STRING>")
+    public static class InvalidPassColumnsThroughMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /** PTF with only scalar arguments, no tables. */
+    @DataTypeHint("ROW<sum INT>")
+    public static class ScalarOnlyPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer a,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer b) {
+            collect(Row.of(a + b));
+        }
+    }
+
+    /** PTF with Context parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithContext extends ProcessTableFunction<Row> {
+        public void eval(Context ctx, @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** PTF with State parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithState extends ProcessTableFunction<Row> {
+        public static class CountState {
+            public long counter = 0L;
+        }
+
+        public void eval(
+                @StateHint CountState state,
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Builder Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testBuilderRejectsDuplicateScalarArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("threshold", 50)
+                                    .withScalarArgument("threshold", 100);
+                        });
+
+        assertThat(exception.getMessage()).contains("threshold");
+    }
+
+    @Test
+    void testBuilderRejectsDuplicateTableArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, value INT>"));
+                        });
+
+        assertThat(exception.getMessage()).contains("leftTable");
+    }
+
+    @Test
+    void testBuilderRejectsMixedDuplicateArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("input", 42);
+                        });
+
+        assertThat(exception.getMessage()).contains("input");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentOnTime() {
+        // We should reject PTFs that use reserved argument name "on_time"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgOnTimePTF.class)
+                        .withTableArgument("on_time", DataTypes.of("ROW<id INT>"));
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("on_time");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentUid() {
+        // We should reject PTFs that use reserved argument name "uid"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgUidPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<id INT>"))
+                        .withScalarArgument("uid", "my-id");
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("uid");
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testExplicitNameTakesPrecedence() throws Exception {
+        // Verify that @ArgumentHint(name="customName") takes precedence over actual parameter
+        // name when processing elements and calling eval.
+
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ExplicitNamePTF.class)
+                        .withTableArgument("customName", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(42));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0).getField(0)).isEqualTo(42);
+            assertThat(output.get(1).getField(0)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testScalarOnlyPTF() throws Exception {
+        // Test scalar-only PTF with no table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ScalarOnlyPTF.class)
+                        .withScalarArgument("a", 10)
+                        .withScalarArgument("b", 20)
+                        .build()) {
+
+            harness.process();
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0).getField(0)).isEqualTo(30);
+        }
+    }
+
+    @Test
+    void testInvokeRejectsTableArguments() throws Exception {
+        // Verify that invoke() rejects PTFs with table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50)
+                        .build()) {
+
+            Exception exception =
+                    assertThrows(
+                            IllegalStateException.class,
+                            () -> {
+                                harness.process();
+                            });
+
+            assertThat(exception.getMessage()).contains("process() is only for scalar-only PTFs");
+        }
+    }
+
+    @Test
+    void testTableProcessingWithScalarArgument() throws Exception {
+        // Test a PTF that uses a scalar parameter
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50) // Scalar argument: threshold = 50
+                        .build()) {
+
+            harness.processElement(Row.of(25));
+            harness.processElement(Row.of(75));
+            harness.processElement(Row.of(50));
+            harness.processElement(Row.of(10));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0).getField(0)).isEqualTo(75);
+            assertThat(output.get(1).getField(0)).isEqualTo(50);
+            assertThat(output.get(2).getField(0)).isEqualTo(100);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Trait Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testProcessElementWithRowKind() throws Exception {
+        // Verify RowKind is preserved through processing (ROW_SEMANTIC_TABLE)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(RowKind.INSERT, 10);
+            harness.processElement(RowKind.UPDATE_BEFORE, 15);
+            harness.processElement(RowKind.UPDATE_AFTER, 20);
+            harness.processElement(RowKind.DELETE, 30);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+            assertThat(output.get(0).getKind()).isEqualTo(RowKind.INSERT);
+            assertThat(output.get(1).getKind()).isEqualTo(RowKind.UPDATE_BEFORE);
+            assertThat(output.get(2).getKind()).isEqualTo(RowKind.UPDATE_AFTER);
+            assertThat(output.get(3).getKind()).isEqualTo(RowKind.DELETE);
+        }
+    }
+
+    @Test
+    void testPassColumnsThroughTrait() throws Exception {
+        // Verify PASS_COLUMNS_THROUGH prepends ALL input columns (not just partition keys)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassColumnsThroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 10, 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("B", 20, 40));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithoutPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY allows omitting partition configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+            harness.processElement(Row.of("C", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of(20));
+            assertThat(output.get(1)).isEqualTo(Row.of(40));
+            assertThat(output.get(2)).isEqualTo(Row.of(60));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY still works when partition is configured
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("A", 5));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("A", 10));
+            assertThat(output.get(2)).isEqualTo(Row.of("B", 40));
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Data Type Conversion Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testNamedRowFieldOrdering() throws Exception {
+        // Test what happens when Row field order differs from DataType schema order
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row rowA = Row.withNames();
+            rowA.setField("value", 100);
+            rowA.setField("user", "Alice");
+
+            harness.processElement(rowA);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+
+            // Positional access follows schema order
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testPositionalRowWithWrongTypeOrder() throws Exception {
+        // Verify that type mismatches are caught when Row values don't match schema types
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row wrongOrderRow = Row.of(10, "Alice");
+
+            assertThrows(ClassCastException.class, () -> harness.processElement(wrongOrderRow));
+        }
+    }
+
+    @Test
+    void testStructuredTypeInput() throws Exception {
+        // Test PTF that accepts structured types instead of Row
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+            harness.processElement(Row.of("Bob", 17));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(25);
+        }
+    }
+
+    @Test
+    void testStructuredTypeInputAndOutput() throws Exception {
+        // Test PTF with structured type inputs and outputs
+        try (ProcessTableFunctionTestHarness<User> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserTransformPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+
+            List<User> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            User result = output.get(0);
+            assertThat(result.getClass()).isEqualTo(User.class);
+            assertThat(result.name).isEqualTo("Alice");
+            assertThat(result.age).isEqualTo(26);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Partitioning Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testSetSemanticWithPartitionByName() throws Exception {
+        // Verify set-semantic table with partition configuration by column name
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key") // Partition by "key" column name
+                        .build()) {
+
+            harness.processElement(Row.of("X", 10));
+            harness.processElement(Row.of("Y", 20));
+            harness.processElement(Row.of("X", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0)).isEqualTo(Row.of("X", 10));
+            assertThat(output.get(1)).isEqualTo(Row.of("Y", 20));
+            assertThat(output.get(2)).isEqualTo(Row.of("X", 30));
+        }
+    }
+
+    @Test
+    void testSetSemanticWithMultiplePartitionColumns() throws Exception {

Review Comment:
   This and the test above use all additional non-value columns as partitioning keys and hence add all of them to the output which is the same behavior as pass_through columns.
   Add one more test with three (or even four) input columns and only selecting a single  columns as key?
   



##########
flink-table/flink-table-test-utils/src/test/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarnessTest.java:
##########
@@ -0,0 +1,1058 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.api.ValidationException;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class ProcessTableFunctionTestHarnessTest {
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PassthroughPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** Filter PTF for testing scalar argument handling. */
+    @DataTypeHint("ROW<value INT>")
+    public static class FilterPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer threshold) {
+            // Use named field access - converter enriches Row with field names
+            int value = input.getFieldAs("value");
+            if (value >= threshold) {
+                collect(input);
+            }
+        }
+    }
+
+    /** PTF for testing transformation of output types. */
+    @DataTypeHint("ROW<doubled INT, original INT>")
+    public static class DoublePTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2, value));
+        }
+    }
+
+    /** PTF with for testing table argument names set via argument hints. */
+    @DataTypeHint("ROW<value INT>")
+    public static class ExplicitNamePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "customName")
+                        Row actualParamName) {
+            collect(actualParamName);
+        }
+    }
+
+    /** PTF with inline type annotation - no builder config needed. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class InlineTypePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(
+                                value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+                                type = @DataTypeHint("ROW<value INT>"))
+                        Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PartitionedPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+            collect(Row.of((Integer) input.getFieldAs("value")));
+        }
+    }
+
+    /**
+     * PTF with PASS_COLUMNS_THROUGH for validating that all input columns are prepended to output.
+     */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class PassColumnsThroughPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** PTF with OPTIONAL_PARTITION_BY for validating that partition setup can be omitted. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class OptionalPartitionPTF extends ProcessTableFunction<Row> {
+
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.OPTIONAL_PARTITION_BY
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** Simple POJO for testing structured type input/output. */
+    public static class User {
+        public String name;
+        public int age;
+
+        public User() {}
+
+        public User(String name, int age) {
+            this.name = name;
+            this.age = age;
+        }
+
+        @Override
+        public String toString() {
+            return "User{name='" + name + "', age=" + age + '}';
+        }
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o) {
+                return true;
+            }
+            if (o == null || getClass() != o.getClass()) {
+                return false;
+            }
+            User user = (User) o;
+            return age == user.age && java.util.Objects.equals(name, user.name);
+        }
+
+        @Override
+        public int hashCode() {
+            return java.util.Objects.hash(name, age);
+        }
+    }
+
+    /** PTF for testing structured type inputs. */
+    @DataTypeHint("ROW<name STRING, age INT>")
+    public static class UserPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            if (user.age >= 18) {
+                collect(Row.of(user.name, user.age));
+            }
+        }
+    }
+
+    /** PTF that transforms structured type inputs and outputs. */
+    public static class UserTransformPTF extends ProcessTableFunction<User> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            User transformed = new User(user.name, user.age + 1);
+            collect(transformed);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "on_time". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgOnTimePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "on_time")
+                        Row input) {
+            collect(input);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "uid". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgUidPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) String uid) {
+            collect(input);
+        }
+    }
+
+    /** Multi-table PTF for validating multi-input processing. */
+    @DataTypeHint("ROW<output STRING>")
+    public static class MultiTableJoinPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /**
+     * Multi-table PTF with one POJO and one Row argument, for testing partitioning with structured
+     * types.
+     */
+    @DataTypeHint("ROW<source STRING, age INT>")
+    public static class MixedTypeMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) User userTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rowTable) {
+            if (userTable != null) {
+                collect(Row.of("USER", userTable.age));
+            }
+            if (rowTable != null) {
+                collect(Row.of("ROW", rowTable.getFieldAs("age")));
+            }
+        }
+    }
+
+    /**
+     * Invalid PTF - uses PASS_COLUMNS_THROUGH with multiple table arguments (not allowed per Flink
+     * docs).
+     */
+    @DataTypeHint("ROW<output STRING>")
+    public static class InvalidPassColumnsThroughMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /** PTF with only scalar arguments, no tables. */
+    @DataTypeHint("ROW<sum INT>")
+    public static class ScalarOnlyPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer a,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer b) {
+            collect(Row.of(a + b));
+        }
+    }
+
+    /** PTF with Context parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithContext extends ProcessTableFunction<Row> {
+        public void eval(Context ctx, @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** PTF with State parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithState extends ProcessTableFunction<Row> {
+        public static class CountState {
+            public long counter = 0L;
+        }
+
+        public void eval(
+                @StateHint CountState state,
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Builder Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testBuilderRejectsDuplicateScalarArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("threshold", 50)
+                                    .withScalarArgument("threshold", 100);
+                        });
+
+        assertThat(exception.getMessage()).contains("threshold");
+    }
+
+    @Test
+    void testBuilderRejectsDuplicateTableArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, value INT>"));
+                        });
+
+        assertThat(exception.getMessage()).contains("leftTable");
+    }
+
+    @Test
+    void testBuilderRejectsMixedDuplicateArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("input", 42);
+                        });
+
+        assertThat(exception.getMessage()).contains("input");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentOnTime() {
+        // We should reject PTFs that use reserved argument name "on_time"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgOnTimePTF.class)
+                        .withTableArgument("on_time", DataTypes.of("ROW<id INT>"));
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("on_time");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentUid() {
+        // We should reject PTFs that use reserved argument name "uid"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgUidPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<id INT>"))
+                        .withScalarArgument("uid", "my-id");
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("uid");
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testExplicitNameTakesPrecedence() throws Exception {
+        // Verify that @ArgumentHint(name="customName") takes precedence over actual parameter
+        // name when processing elements and calling eval.
+
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ExplicitNamePTF.class)
+                        .withTableArgument("customName", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(42));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0).getField(0)).isEqualTo(42);
+            assertThat(output.get(1).getField(0)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testScalarOnlyPTF() throws Exception {
+        // Test scalar-only PTF with no table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ScalarOnlyPTF.class)
+                        .withScalarArgument("a", 10)
+                        .withScalarArgument("b", 20)
+                        .build()) {
+
+            harness.process();
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0).getField(0)).isEqualTo(30);
+        }
+    }
+
+    @Test
+    void testInvokeRejectsTableArguments() throws Exception {
+        // Verify that invoke() rejects PTFs with table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50)
+                        .build()) {
+
+            Exception exception =
+                    assertThrows(
+                            IllegalStateException.class,
+                            () -> {
+                                harness.process();
+                            });
+
+            assertThat(exception.getMessage()).contains("process() is only for scalar-only PTFs");
+        }
+    }
+
+    @Test
+    void testTableProcessingWithScalarArgument() throws Exception {
+        // Test a PTF that uses a scalar parameter
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50) // Scalar argument: threshold = 50
+                        .build()) {
+
+            harness.processElement(Row.of(25));
+            harness.processElement(Row.of(75));
+            harness.processElement(Row.of(50));
+            harness.processElement(Row.of(10));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0).getField(0)).isEqualTo(75);
+            assertThat(output.get(1).getField(0)).isEqualTo(50);
+            assertThat(output.get(2).getField(0)).isEqualTo(100);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Trait Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testProcessElementWithRowKind() throws Exception {
+        // Verify RowKind is preserved through processing (ROW_SEMANTIC_TABLE)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(RowKind.INSERT, 10);
+            harness.processElement(RowKind.UPDATE_BEFORE, 15);
+            harness.processElement(RowKind.UPDATE_AFTER, 20);
+            harness.processElement(RowKind.DELETE, 30);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+            assertThat(output.get(0).getKind()).isEqualTo(RowKind.INSERT);
+            assertThat(output.get(1).getKind()).isEqualTo(RowKind.UPDATE_BEFORE);
+            assertThat(output.get(2).getKind()).isEqualTo(RowKind.UPDATE_AFTER);
+            assertThat(output.get(3).getKind()).isEqualTo(RowKind.DELETE);
+        }
+    }
+
+    @Test
+    void testPassColumnsThroughTrait() throws Exception {
+        // Verify PASS_COLUMNS_THROUGH prepends ALL input columns (not just partition keys)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassColumnsThroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 10, 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("B", 20, 40));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithoutPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY allows omitting partition configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+            harness.processElement(Row.of("C", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of(20));
+            assertThat(output.get(1)).isEqualTo(Row.of(40));
+            assertThat(output.get(2)).isEqualTo(Row.of(60));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY still works when partition is configured
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("A", 5));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("A", 10));
+            assertThat(output.get(2)).isEqualTo(Row.of("B", 40));
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Data Type Conversion Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testNamedRowFieldOrdering() throws Exception {
+        // Test what happens when Row field order differs from DataType schema order
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row rowA = Row.withNames();
+            rowA.setField("value", 100);
+            rowA.setField("user", "Alice");
+
+            harness.processElement(rowA);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+
+            // Positional access follows schema order
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testPositionalRowWithWrongTypeOrder() throws Exception {
+        // Verify that type mismatches are caught when Row values don't match schema types
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row wrongOrderRow = Row.of(10, "Alice");
+
+            assertThrows(ClassCastException.class, () -> harness.processElement(wrongOrderRow));
+        }
+    }
+
+    @Test
+    void testStructuredTypeInput() throws Exception {
+        // Test PTF that accepts structured types instead of Row
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+            harness.processElement(Row.of("Bob", 17));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(25);
+        }
+    }
+
+    @Test
+    void testStructuredTypeInputAndOutput() throws Exception {
+        // Test PTF with structured type inputs and outputs
+        try (ProcessTableFunctionTestHarness<User> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserTransformPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+
+            List<User> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            User result = output.get(0);
+            assertThat(result.getClass()).isEqualTo(User.class);
+            assertThat(result.name).isEqualTo("Alice");
+            assertThat(result.age).isEqualTo(26);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Partitioning Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testSetSemanticWithPartitionByName() throws Exception {
+        // Verify set-semantic table with partition configuration by column name
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key") // Partition by "key" column name
+                        .build()) {
+
+            harness.processElement(Row.of("X", 10));
+            harness.processElement(Row.of("Y", 20));
+            harness.processElement(Row.of("X", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0)).isEqualTo(Row.of("X", 10));
+            assertThat(output.get(1)).isEqualTo(Row.of("Y", 20));
+            assertThat(output.get(2)).isEqualTo(Row.of("X", 30));
+        }
+    }
+
+    @Test
+    void testSetSemanticWithMultiplePartitionColumns() throws Exception {
+        // Verify composite partition key (multiple columns)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument(
+                                "input",
+                                DataTypes.of("ROW<region STRING, country STRING, value INT>"))
+                        .withPartitionBy("input", "region", "country")
+                        .build()) {
+
+            harness.processElement(Row.of("EU", "DE", 100));
+            harness.processElement(Row.of("EU", "DE", 200));
+            harness.processElement(Row.of("EU", "FR", 300));
+            harness.processElement(Row.of("US", "NY", 400));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+        }
+    }
+
+    @Test
+    void testMultipleSetSemanticTablesWithMatchingPartitionKeys() throws Exception {
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                        .withTableArgument("leftTable", DataTypes.of("ROW<name STRING, score INT>"))
+                        .withPartitionBy("leftTable", "name")
+                        .withTableArgument(
+                                "rightTable", DataTypes.of("ROW<name STRING, city STRING>"))
+                        .withPartitionBy("rightTable", "name")
+                        .build()) {
+
+            harness.processElementForTable("leftTable", Row.of("Alice", 100));
+            harness.processElementForTable("leftTable", Row.of("Bob", 200));
+
+            harness.processElementForTable("rightTable", Row.of("Alice", "Berlin"));
+            harness.processElementForTable("rightTable", Row.of("Bob", "London"));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+
+            assertThat(output.get(0).getField(0)).isEqualTo("Alice");
+            assertThat(output.get(0).getField(1)).isNull();
+            assertThat(output.get(0).getField(2)).isEqualTo("LEFT: +I[Alice, 100]");
+
+            assertThat(output.get(1).getField(0)).isEqualTo("Bob");
+            assertThat(output.get(1).getField(1)).isNull();
+            assertThat(output.get(1).getField(2)).isEqualTo("LEFT: +I[Bob, 200]");
+
+            assertThat(output.get(2).getField(0)).isNull();
+            assertThat(output.get(2).getField(1)).isEqualTo("Alice");
+            assertThat(output.get(2).getField(2)).isEqualTo("RIGHT: +I[Alice, Berlin]");
+
+            assertThat(output.get(3).getField(0)).isNull();
+            assertThat(output.get(3).getField(1)).isEqualTo("Bob");
+            assertThat(output.get(3).getField(2)).isEqualTo("RIGHT: +I[Bob, London]");
+        }
+    }
+
+    @Test
+    void testMultipleSetSemanticTablesWithMismatchedPartitionTypes() {
+        // Verify that multi-table PTFs with inconsistent partition types are rejected
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                                    .withPartitionBy("leftTable", "id")
+                                    .withTableArgument(
+                                            "rightTable",
+                                            DataTypes.of("ROW<key STRING, city STRING>"))
+                                    .withPartitionBy("rightTable", "key")
+                                    .build();
+                        });
+
+        assertThat(exception.getMessage()).contains("Inconsistent partitioning");
+    }
+
+    @Test
+    void testMultipleSetSemanticTablesWithMismatchedPartitionColumnCount() {
+        // Verify that multi-table PTFs with different partition column counts are rejected
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                                    .withTableArgument(
+                                            "leftTable",
+                                            DataTypes.of("ROW<id INT, region STRING, name STRING>"))
+                                    .withPartitionBy("leftTable", "id", "region")
+                                    .withTableArgument(
+                                            "rightTable", DataTypes.of("ROW<id INT, city STRING>"))
+                                    .withPartitionBy("rightTable", "id")
+                                    .build();
+                        });
+
+        assertThat(exception.getMessage()).contains("Inconsistent partitioning");
+    }
+
+    @Test
+    void testPassColumnsThroughWithMultipleTablesRejected() {
+        // Verify that PASS_COLUMNS_THROUGH is rejected when used with multiple table arguments
+        Exception exception =
+                assertThrows(
+                        org.apache.flink.table.api.ValidationException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(
+                                            InvalidPassColumnsThroughMultiTablePTF.class)
+                                    .withTableArgument("leftTable", DataTypes.of("ROW<a INT>"))
+                                    .withTableArgument("rightTable", DataTypes.of("ROW<b INT>"))
+                                    .build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Pass-through columns")
+                .contains("multiple table arguments");
+    }
+
+    @Test
+    void testInlineTypeAnnotation() throws Exception {
+        // Verify that PTFs can declare table argument types via @ArgumentHint(type = ...)
+        // without needing .withTableArgument() configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class).build()) {
+
+            harness.processElement(Row.of(5));
+            harness.processElement(Row.of(10));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0)).isEqualTo(Row.of(10));
+            assertThat(output.get(1)).isEqualTo(Row.of(20));
+        }
+    }
+
+    @Test
+    void testInlineTypeMatchesBuilderConfig() throws Exception {
+        // Verify that when both inline annotation and builder config are provided with matching
+        // types, the harness builds successfully
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(7));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0)).isEqualTo(Row.of(14));
+        }
+    }
+
+    @Test
+    void testInlineTypeMismatchWithBuilderConfigRejected() {
+        // Verify that when inline annotation and builder config specify different types,
+        // build() throws an exception
+        Exception exception =
+                assertThrows(
+                        IllegalStateException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class)
+                                    .withTableArgument(
+                                            "input", DataTypes.of("ROW<value BIGINT>")) // Mismatch!
+                                    .build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Type mismatch")
+                .contains("input")
+                .contains("INT")
+                .contains("BIGINT");
+    }
+
+    // -------------------------------------------------------------------------
+    // Element Processing Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testProcessElementOnMultiTableThrows() throws Exception {
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(MultiTableJoinPTF.class)
+                        .withTableArgument("leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                        .withTableArgument("rightTable", DataTypes.of("ROW<id INT, value STRING>"))
+                        .withPartitionBy("leftTable", "id")
+                        .withPartitionBy("rightTable", "id")
+                        .build()) {
+
+            Exception exception =
+                    assertThrows(
+                            IllegalStateException.class,
+                            () -> harness.processElement(Row.of(1, "Alice")));
+            assertThat(exception.getMessage())
+                    .contains("multiple table arguments")
+                    .contains("processElementForTable");
+        }
+    }
+
+    @Test
+    void testProcessElementForTableMultipleTables() throws Exception {

Review Comment:
   I think this test is overlapping with `testMultipleSetSemanticTablesWithMatchingPartitionKeys()` but using less accurate asserts.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "fhueske (via GitHub)" <gi...@apache.org>.
fhueske commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3232410899


##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {

Review Comment:
   That makes sense, thank you!



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "autophagy (via GitHub)" <gi...@apache.org>.
autophagy commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3217441231


##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);

Review Comment:
   I'm not sure - I think this was the result of experimentation and I didn't revisit it to verify whether it's necessary in the end. I'll remove it and see 



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "fhueske (via GitHub)" <gi...@apache.org>.
fhueske commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3208687907


##########
docs/content.zh/docs/dev/table/functions/ptfs.md:
##########
@@ -2034,3 +2034,336 @@ Limitations
 PTFs are in an early stage. The following limitations apply:
 - PTFs cannot run in batch mode.
 - Broadcast state
+
+Testing Process Table Functions
+-------------------------------
+
+The `ProcessTableFunctionTestHarness` provides a lightweight unit testing framework for Process Table
+Functions (PTFs). It is useful for unit testing and validating PTF business logic, multi-table PTF
+behaviour and validating errors.
+
+For end-to-end integration testing with the full Flink planner and runtime, use integration tests
+instead.
+
+{{< top >}}
+
+### Quick Start
+
+{{< tabs "quickstart" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.*;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.runtime.functions.ProcessTableFunctionTestHarness;
+import org.apache.flink.types.Row;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+// PTF under test
+@DataTypeHint("ROW<doubled INT>")
+public class DoublePTF extends ProcessTableFunction<Row> {
+  public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+    int value = input.getFieldAs("value");
+    collect(Row.of(value * 2));
+  }
+}
+
+// Test
+@Test
+void testDoublePTF() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(DoublePTF.class)
+          .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+          .build()) {
+
+    harness.processElement(Row.of(5));
+    harness.processElement(Row.of(10));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).hasSize(2);
+    assertThat(output.get(0)).isEqualTo(Row.of(10));
+    assertThat(output.get(1)).isEqualTo(Row.of(20));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+{{< top >}}
+
+### Common Testing Scenarios
+
+#### Testing Row-Semantic Tables
+
+Use `.withTableArgument()` to configure the input table schema:
+
+{{< tabs "row-semantic" >}}
+{{< tab "Java" >}}
+```java
+public class PassthroughPTF extends ProcessTableFunction<Integer> {
+  public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+    collect(input.getFieldAs("value"));
+  }
+}
+
+@Test
+void testPassthrough() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+          .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+          .build()) {
+
+    harness.processElement(Row.of(42));
+    harness.processElement(Row.of(100));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).containsExactly(42, 100);
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Testing Set-Semantic Tables with Partitioning
+
+For `SET_SEMANTIC_TABLE`, use `.withPartitionBy()` to configure partition columns:
+
+{{< tabs "set-semantic" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<doubled INT>")
+public class PartitionedPTF extends ProcessTableFunction<Row> {
+  public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+    int value = input.getFieldAs("value");
+    collect(Row.of(value * 2));
+  }
+}
+
+@Test
+void testPartitionedPTF() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+          .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+          .withPartitionBy("input", "key")
+          .build()) {
+
+    harness.processElement(Row.of("A", 10));
+    harness.processElement(Row.of("B", 20));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+    assertThat(output.get(1)).isEqualTo(Row.of("B", 40));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Testing Multiple Table Arguments
+
+Use `processElementForTable()` to specify which table receives each row:
+
+{{< tabs "multi-table" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<output STRING>")
+public class JoinPTF extends ProcessTableFunction<Row> {
+  public void eval(
+      @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row left,
+      @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row right) {
+    if (left != null) {
+      collect(Row.of("LEFT: " + left));
+    }
+    if (right != null) {
+      collect(Row.of("RIGHT: " + right));
+    }
+  }
+}
+
+@Test
+void testMultiTable() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(JoinPTF.class)
+          .withTableArgument("left", DataTypes.of("ROW<id INT, name STRING>"))
+          .withPartitionBy("left", "id")
+          .withTableArgument("right", DataTypes.of("ROW<id INT, city STRING>"))
+          .withPartitionBy("right", "id")
+          .build()) {
+
+    // Use processElementForTable() to target specific tables
+    harness.processElementForTable("left", Row.of(1, "Alice"));
+    harness.processElementForTable("right", Row.of(1, "Berlin"));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output.get(0)).isEqualTo(Row.of(1, null, "LEFT: +I[1, Alice]"));
+    assertThat(output.get(1)).isEqualTo(Row.of(null, 1, "RIGHT: +I[1, Berlin]"));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Testing with Scalar Arguments
+
+Use `.withScalarArgument()` to configure scalar parameter values:
+
+{{< tabs "scalar-args" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<value INT>")
+public class FilterPTF extends ProcessTableFunction<Row> {
+  public void eval(
+      @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+      int threshold) {
+    int value = input.getFieldAs("value");
+    if (value > threshold) {
+      collect(Row.of(value));
+    }
+  }
+}
+
+@Test
+void testFilter() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+          .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+          .withScalarArgument("threshold", 50)  // Configure scalar value
+          .build()) {
+
+    harness.processElement(Row.of(30));
+    harness.processElement(Row.of(70));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).containsExactly(Row.of(70));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+**Scalar-Only PTFs**: For PTFs with only scalar arguments, use `process()` to trigger evaluation:
+
+{{< tabs "scalar-only" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<sum INT>")
+public class AddPTF extends ProcessTableFunction<Row> {
+  public void eval(int a, int b) {
+    collect(Row.of(a + b));
+  }
+}
+
+@Test
+void testScalarOnly() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(AddPTF.class)
+          .withScalarArgument("a", 5)
+          .withScalarArgument("b", 7)
+          .build()) {
+
+    harness.process();  // Use process() instead of processElement()
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).containsExactly(Row.of(12));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Configuring Table Argument Types
+
+The harness supports two ways to specify table argument types:
+
+{{< tabs "type-config" >}}
+{{< tab "Java" >}}
+```java
+// Option 1: Inline type annotation using DataTypeHint
+@DataTypeHint("ROW<doubled INT>")
+public class InlineTypePTF extends ProcessTableFunction<Row> {
+  public void eval(
+      @ArgumentHint(
+        value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+        type = @DataTypeHint("ROW<value INT>")
+      ) Row input) {
+    int value = input.getFieldAs("value");
+    collect(Row.of(value * 2));
+  }
+}
+
+@Test
+void testInlineType() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class).build()) {
+
+    harness.processElement(Row.of(5));
+    assertThat(harness.getOutput()).containsExactly(Row.of(10));
+  }
+}
+
+// Option 2: Builder configuration
+@Test
+void testBuilderType() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(DoublePTF.class)
+          .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+          .build()) {
+
+    harness.processElement(Row.of(5));
+    assertThat(harness.getOutput()).containsExactly(Row.of(10));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}

Review Comment:
   The sentence 
   
   > The harness supports two ways to specify table argument types:
   
   suggests that the table arg types always need to be specified on the harness.
   However, users don't need to explicitly specify the types, if the PTF uses an `@ArgumentHint` (IIUC). I think the first example is a bit confusing because we don't need to specify anything for the harness (because the PTF declares the types itself).
   
   I think it would be easier to explain that types only need to be specified if the PTF doesn't do it.
   
   



##########
docs/content.zh/docs/dev/table/functions/ptfs.md:
##########
@@ -2034,3 +2034,336 @@ Limitations
 PTFs are in an early stage. The following limitations apply:
 - PTFs cannot run in batch mode.
 - Broadcast state
+
+Testing Process Table Functions
+-------------------------------
+
+The `ProcessTableFunctionTestHarness` provides a lightweight unit testing framework for Process Table
+Functions (PTFs). It is useful for unit testing and validating PTF business logic, multi-table PTF
+behaviour and validating errors.
+
+For end-to-end integration testing with the full Flink planner and runtime, use integration tests
+instead.
+
+{{< top >}}
+
+### Quick Start
+
+{{< tabs "quickstart" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.*;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.runtime.functions.ProcessTableFunctionTestHarness;
+import org.apache.flink.types.Row;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+// PTF under test
+@DataTypeHint("ROW<doubled INT>")
+public class DoublePTF extends ProcessTableFunction<Row> {
+  public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+    int value = input.getFieldAs("value");
+    collect(Row.of(value * 2));
+  }
+}
+
+// Test
+@Test
+void testDoublePTF() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(DoublePTF.class)
+          .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+          .build()) {
+
+    harness.processElement(Row.of(5));
+    harness.processElement(Row.of(10));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).hasSize(2);
+    assertThat(output.get(0)).isEqualTo(Row.of(10));
+    assertThat(output.get(1)).isEqualTo(Row.of(20));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+{{< top >}}
+
+### Common Testing Scenarios
+
+#### Testing Row-Semantic Tables
+
+Use `.withTableArgument()` to configure the input table schema:
+
+{{< tabs "row-semantic" >}}
+{{< tab "Java" >}}
+```java
+public class PassthroughPTF extends ProcessTableFunction<Integer> {
+  public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+    collect(input.getFieldAs("value"));
+  }
+}
+
+@Test
+void testPassthrough() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+          .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+          .build()) {
+
+    harness.processElement(Row.of(42));
+    harness.processElement(Row.of(100));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).containsExactly(42, 100);
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Testing Set-Semantic Tables with Partitioning
+
+For `SET_SEMANTIC_TABLE`, use `.withPartitionBy()` to configure partition columns:
+
+{{< tabs "set-semantic" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<doubled INT>")
+public class PartitionedPTF extends ProcessTableFunction<Row> {
+  public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+    int value = input.getFieldAs("value");
+    collect(Row.of(value * 2));
+  }
+}
+
+@Test
+void testPartitionedPTF() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+          .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+          .withPartitionBy("input", "key")
+          .build()) {
+
+    harness.processElement(Row.of("A", 10));
+    harness.processElement(Row.of("B", 20));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+    assertThat(output.get(1)).isEqualTo(Row.of("B", 40));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Testing Multiple Table Arguments
+
+Use `processElementForTable()` to specify which table receives each row:
+
+{{< tabs "multi-table" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<output STRING>")
+public class JoinPTF extends ProcessTableFunction<Row> {
+  public void eval(
+      @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row left,
+      @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row right) {
+    if (left != null) {
+      collect(Row.of("LEFT: " + left));
+    }
+    if (right != null) {
+      collect(Row.of("RIGHT: " + right));
+    }
+  }
+}
+
+@Test
+void testMultiTable() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(JoinPTF.class)
+          .withTableArgument("left", DataTypes.of("ROW<id INT, name STRING>"))
+          .withPartitionBy("left", "id")
+          .withTableArgument("right", DataTypes.of("ROW<id INT, city STRING>"))
+          .withPartitionBy("right", "id")
+          .build()) {
+
+    // Use processElementForTable() to target specific tables
+    harness.processElementForTable("left", Row.of(1, "Alice"));
+    harness.processElementForTable("right", Row.of(1, "Berlin"));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output.get(0)).isEqualTo(Row.of(1, null, "LEFT: +I[1, Alice]"));
+    assertThat(output.get(1)).isEqualTo(Row.of(null, 1, "RIGHT: +I[1, Berlin]"));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Testing with Scalar Arguments
+
+Use `.withScalarArgument()` to configure scalar parameter values:
+
+{{< tabs "scalar-args" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<value INT>")
+public class FilterPTF extends ProcessTableFunction<Row> {
+  public void eval(
+      @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+      int threshold) {
+    int value = input.getFieldAs("value");
+    if (value > threshold) {
+      collect(Row.of(value));
+    }
+  }
+}
+
+@Test
+void testFilter() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+          .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+          .withScalarArgument("threshold", 50)  // Configure scalar value
+          .build()) {
+
+    harness.processElement(Row.of(30));
+    harness.processElement(Row.of(70));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).containsExactly(Row.of(70));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+**Scalar-Only PTFs**: For PTFs with only scalar arguments, use `process()` to trigger evaluation:
+
+{{< tabs "scalar-only" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<sum INT>")
+public class AddPTF extends ProcessTableFunction<Row> {
+  public void eval(int a, int b) {
+    collect(Row.of(a + b));
+  }
+}
+
+@Test
+void testScalarOnly() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(AddPTF.class)
+          .withScalarArgument("a", 5)
+          .withScalarArgument("b", 7)
+          .build()) {
+
+    harness.process();  // Use process() instead of processElement()
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).containsExactly(Row.of(12));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Configuring Table Argument Types
+
+The harness supports two ways to specify table argument types:
+
+{{< tabs "type-config" >}}
+{{< tab "Java" >}}
+```java
+// Option 1: Inline type annotation using DataTypeHint
+@DataTypeHint("ROW<doubled INT>")
+public class InlineTypePTF extends ProcessTableFunction<Row> {
+  public void eval(
+      @ArgumentHint(
+        value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+        type = @DataTypeHint("ROW<value INT>")
+      ) Row input) {
+    int value = input.getFieldAs("value");
+    collect(Row.of(value * 2));
+  }
+}
+
+@Test
+void testInlineType() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class).build()) {
+
+    harness.processElement(Row.of(5));
+    assertThat(harness.getOutput()).containsExactly(Row.of(10));
+  }
+}
+
+// Option 2: Builder configuration
+@Test
+void testBuilderType() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(DoublePTF.class)
+          .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+          .build()) {
+
+    harness.processElement(Row.of(5));
+    assertThat(harness.getOutput()).containsExactly(Row.of(10));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+**Structured Types**: The harness supports structured POJO types in addition to `Row`, both as PTF inputs
+and outputs:
+
+{{< tabs "pojo-types" >}}
+{{< tab "Java" >}}
+```java
+public static class Customer {
+  public String name;
+  public int age;
+}
+
+public class CustomerPTF extends ProcessTableFunction<Customer> {
+  public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Customer c) {
+    collect(c);
+  }
+}
+
+@Test
+void testPOJO() throws Exception {
+  try (ProcessTableFunctionTestHarness<Customer> harness =
+      ProcessTableFunctionTestHarness.ofClass(CustomerPTF.class)
+          .withTableArgument("input", DataTypes.of(Customer.class))
+          .build()) {
+
+    harness.processElement(Row.of("Alice", 30));
+
+    List<Customer> output = harness.getOutput();
+    assertThat(output.get(0).name).isEqualTo("Alice");
+    assertThat(output.get(0).age).isEqualTo(30);
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+{{< top >}}
+
+### Unsupported Features

Review Comment:
   ```suggestion
   ### PTF Features Unsupported by the TestHarness
   ```
   be more explicit that these are gaps of the test harness? 
   Otherwise, readers might confuse these with PTF limitation if they are not aware that this section is in the context of the test harness.



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            LogicalType logicalType = dataType.getLogicalType();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                int index = 0;
+                for (RowType.RowField field : rowType.getFields()) {
+                    if (field.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                int index = 0;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    if (attr.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a table argument without an explicit schema.
+         *
+         * <p>Use this for structured type arguments where the type can be inferred from the PTF's
+         * eval() signature. For Row arguments, use {@link #withTableArgument(String,
+         * AbstractDataType)} with an explicit schema.
+         *
+         * @param argumentName The table argument name
+         */
+        public Builder<OUT> withTableArgument(String argumentName) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName) || tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException("Argument already configured: " + argumentName);
+            }
+
+            ScalarArgumentConfiguration config = new ScalarArgumentConfiguration(value);
+            scalarArgs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Partitioning
+        // ---------------------------------------------------------------------
+
+        /**
+         * Specifies partition columns for a set semantic table.
+         *
+         * @param argumentName The table argument name
+         * @param columnNames The partition column names
+         * @return This builder
+         */
+        public Builder<OUT> withPartitionBy(String argumentName, String... columnNames) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(columnNames, "columnNames must not be null");
+            checkArgument(columnNames.length > 0, "Must specify at least one column");
+
+            if (partitionConfigs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Partition config already exists for: " + argumentName);
+            }
+
+            PartitionConfiguration config = new PartitionConfiguration(columnNames);
+            partitionConfigs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Build
+        // ---------------------------------------------------------------------
+
+        /**
+         * Builds the test harness.
+         *
+         * <p>This instantiates the PTF, validates configuration via type inference, creates the
+         * FunctionContext, and opens the function.
+         *
+         * @return The configured test harness
+         * @throws Exception If instantiation or opening fails
+         */
+        public ProcessTableFunctionTestHarness<OUT> build() throws Exception {
+            ProcessTableFunction<OUT> function = instantiateFunction();
+
+            List<ArgumentInfo> arguments = extractAndValidateTypeInference(function);
+
+            FunctionContext functionContext =
+                    new FunctionContext(null, Thread.currentThread().getContextClassLoader(), null);
+
+            Method evalMethod = findEvalMethod();
+
+            validateEvalMethodSupported(evalMethod, arguments);
+            validatePartitionConsistency(arguments);
+
+            // In cases where PTFs have only a single table argument, set it as a default
+            // and mark as a single table function so that processElement without specifying
+            // a table argument can be used.
+            String defaultTableArg = null;
+            boolean isSingleTableFunction = false;
+
+            List<ArgumentInfo> tableArguments = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    tableArguments.add(arg);
+                }
+            }
+
+            if (tableArguments.size() == 1) {
+                defaultTableArg = tableArguments.get(0).name;
+                isSingleTableFunction = true;
+            }
+
+            Map<String, DataStructureConverter<Object, Object>> inputConverters = new HashMap<>();
+            Map<String, DataStructureConverter<Object, Object>> outputConverters = new HashMap<>();
+            createConverters(arguments, inputConverters, outputConverters);
+
+            Map<String, ArgumentInfo> argumentsByName = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    argumentsByName.put(arg.name, arg);
+                }
+            }
+
+            return new ProcessTableFunctionTestHarness<>(
+                    function,
+                    functionContext,
+                    defaultTableArg,
+                    evalMethod,
+                    arguments,
+                    argumentsByName,
+                    isSingleTableFunction,
+                    extractScalarValues(arguments),
+                    inputConverters,
+                    outputConverters);
+        }
+
+        /** Extracts scalar values from configs, creating a map keyed by argument name. */
+        private Map<String, Object> extractScalarValues(List<ArgumentInfo> arguments) {
+            Map<String, Object> values = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    ScalarArgumentConfiguration config = scalarArgs.get(arg.name);
+                    if (config != null) {
+                        values.put(arg.name, config.value);
+                    }
+                }
+            }
+            return values;
+        }
+
+        /**
+         * Creates and initializes data structure converters for all table arguments.
+         *
+         * <p>For Row types, both input and output converters are the same (between Row and
+         * RowData).
+         *
+         * <p>For structured types, input converter uses Row types (Row to RowData), and the output
+         * converter uses the structured type.
+         */
+        private void createConverters(
+                List<ArgumentInfo> arguments,
+                Map<String, DataStructureConverter<Object, Object>> inputConverters,
+                Map<String, DataStructureConverter<Object, Object>> outputConverters) {
+            ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    String converterKey = arg.name;
+
+                    LogicalType logicalType = arg.dataType.getLogicalType();
+                    boolean isStructuredType =
+                            logicalType instanceof StructuredType
+                                    && ((StructuredType) logicalType)
+                                            .getImplementationClass()
+                                            .isPresent();
+
+                    if (isStructuredType) {
+                        StructuredType structuredType = (StructuredType) logicalType;
+                        List<RowType.RowField> rowFields = new ArrayList<>();
+                        for (StructuredType.StructuredAttribute attr :
+                                structuredType.getAttributes()) {
+                            rowFields.add(new RowType.RowField(attr.getName(), attr.getType()));
+                        }
+                        RowType rowType = new RowType(logicalType.isNullable(), rowFields);
+                        DataType rowDataType = TypeConversions.fromLogicalToDataType(rowType);
+
+                        DataStructureConverter<Object, Object> inputConverter =
+                                DataStructureConverters.getConverter(rowDataType);
+                        inputConverter.open(classLoader);
+
+                        DataStructureConverter<Object, Object> outputConverter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        outputConverter.open(classLoader);
+
+                        inputConverters.put(converterKey, inputConverter);
+                        outputConverters.put(converterKey, outputConverter);
+                    } else {
+                        DataStructureConverter<Object, Object> converter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        converter.open(classLoader);
+
+                        inputConverters.put(converterKey, converter);
+                        outputConverters.put(converterKey, converter);
+                    }
+                }
+            }
+        }
+
+        private Method findEvalMethod() throws NoSuchMethodException {
+            Method[] methods = functionClass.getMethods();
+            Method evalMethod = null;
+            int evalMethodCount = 0;
+
+            for (Method method : methods) {
+                if (method.getName().equals("eval")) {
+                    evalMethod = method;
+                    evalMethodCount++;
+                }
+            }
+
+            if (evalMethodCount == 0) {
+                throw new NoSuchMethodException(
+                        "No eval() method found in " + functionClass.getSimpleName());
+            } else if (evalMethodCount > 1) {
+                throw new IllegalStateException(
+                        "Multiple eval() methods found in "
+                                + functionClass.getSimpleName()
+                                + ". ProcessTableFunction must have exactly one eval() method.");
+            } else {
+                return evalMethod;
+            }
+        }
+
+        /**
+         * Validates that the eval() method doesn't use unsupported features. Temporary, until state
+         * and context is supported.
+         */
+        private void validateEvalMethodSupported(Method evalMethod, List<ArgumentInfo> arguments) {
+            Parameter[] parameters = evalMethod.getParameters();
+
+            for (int i = 0; i < parameters.length; i++) {
+                Parameter param = parameters[i];
+                Class<?> paramType = param.getType();
+
+                if (ProcessTableFunction.Context.class.isAssignableFrom(paramType)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support Context parameters. "
+                                            + "Found Context parameter at position %d in eval() method. ",
+                                    i));
+                }
+
+                if (param.isAnnotationPresent(StateHint.class)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support state parameters. "
+                                            + "Found @StateHint parameter at position %d in eval() method. ",
+                                    i));
+                }
+            }
+
+            // Parameter count should also match our arguments list
+            if (parameters.length != arguments.size()) {
+                throw new IllegalStateException(
+                        String.format(
+                                "Parameter count mismatch: eval() has %d parameters but only %d arguments were extracted. "
+                                        + "This may indicate missing @ArgumentHint annotations.",
+                                parameters.length, arguments.size()));
+            }
+        }
+
+        /**
+         * Validates that all SET_SEMANTIC_TABLE arguments with partitioning use consistent
+         * partitioning. All such arguments must have the same number of partition columns with
+         * matching data types.
+         */
+        private void validatePartitionConsistency(List<ArgumentInfo> arguments) {
+            List<ArgumentInfo> partitionedTables = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    partitionedTables.add(arg);
+                }
+            }
+
+            if (partitionedTables.size() <= 1) {
+                return;
+            }
+
+            ArgumentInfo first = partitionedTables.get(0);
+            int expectedPartitionColumnCount = first.partitionColumnNames.length;
+
+            for (int i = 1; i < partitionedTables.size(); i++) {
+                ArgumentInfo current = partitionedTables.get(i);
+
+                if (current.partitionColumnNames.length != expectedPartitionColumnCount) {
+                    throw new IllegalArgumentException(
+                            String.format(
+                                    "Inconsistent partitioning: Table argument '%s' has %d partition column(s), "
+                                            + "but table argument '%s' has %d partition column(s). "
+                                            + "All SET_SEMANTIC_TABLE arguments must use consistent partitioning "
+                                            + "(same number of columns and matching data types).",
+                                    first.name,
+                                    expectedPartitionColumnCount,
+                                    current.name,
+                                    current.partitionColumnNames.length));
+                }
+
+                // Check that partition column types match
+                for (int colIdx = 0; colIdx < expectedPartitionColumnCount; colIdx++) {
+                    String firstColName = first.partitionColumnNames[colIdx];
+                    String currentColName = current.partitionColumnNames[colIdx];
+                    DataType firstColType = extractPartitionColumnType(first, firstColName);
+                    DataType currentColType = extractPartitionColumnType(current, currentColName);
+
+                    if (!firstColType.getLogicalType().equals(currentColType.getLogicalType())) {
+                        throw new IllegalArgumentException(
+                                String.format(
+                                        "Inconsistent partitioning: Partition column '%s' of table argument '%s' "
+                                                + "has type %s, but partition column '%s' of table argument '%s' "
+                                                + "has type %s. All SET_SEMANTIC_TABLE arguments must use "
+                                                + "consistent partitioning (same number of columns and matching data types).",
+                                        firstColName,
+                                        first.name,
+                                        firstColType,
+                                        currentColName,
+                                        current.name,
+                                        currentColType));
+                    }
+                }
+            }
+        }
+
+        private DataType extractPartitionColumnType(ArgumentInfo arg, String columnName) {
+            if (arg.dataType instanceof FieldsDataType) {
+                FieldsDataType fieldsDataType = (FieldsDataType) arg.dataType;
+                LogicalType logicalType = fieldsDataType.getLogicalType();
+                List<DataType> fieldDataTypes = fieldsDataType.getChildren();
+
+                if (logicalType instanceof RowType) {
+                    RowType rowType = (RowType) logicalType;
+                    int fieldIndex = 0;
+                    for (RowType.RowField field : rowType.getFields()) {
+                        if (field.getName().equals(columnName)) {
+                            return fieldDataTypes.get(fieldIndex);
+                        }
+                        fieldIndex++;
+                    }
+                } else if (logicalType instanceof StructuredType) {
+                    StructuredType structuredType = (StructuredType) logicalType;
+                    int attrIndex = 0;
+                    for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                        if (attr.getName().equals(columnName)) {
+                            return fieldDataTypes.get(attrIndex);
+                        }
+                        attrIndex++;
+                    }
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format(
+                            "Cannot extract data type for partition column '%s' of argument '%s'",
+                            columnName, arg.name));
+        }
+
+        // ---------------------------------------------------------------------
+        // Type Inference
+        // ---------------------------------------------------------------------
+
+        /**
+         * Extracts type inference from the PTF and validates builder configuration.
+         *
+         * <p>Uses SystemTypeInference to validate things like reserved argument names, multiple
+         * table argument rules, static argument trait validation, etc.
+         */
+        private List<ArgumentInfo> extractAndValidateTypeInference(
+                ProcessTableFunction<OUT> function) {
+
+            DataTypeFactory dataTypeFactory = createDataTypeFactory();
+            TypeInference baseTypeInference = function.getTypeInference(dataTypeFactory);
+            TypeInference systemTypeInference =
+                    SystemTypeInference.of(FunctionKind.PROCESS_TABLE, baseTypeInference);
+
+            Optional<List<StaticArgument>> staticArgsOpt = systemTypeInference.getStaticArguments();
+            if (staticArgsOpt.isEmpty()) {
+                throw new IllegalStateException(
+                        "PTF does not provide static argument information. "
+                                + "Ensure @ArgumentHint annotations are present on all eval() parameters.");
+            }
+
+            List<StaticArgument> allArgs = staticArgsOpt.get();
+            List<StaticArgument> userArgs = new ArrayList<>();
+            for (StaticArgument arg : allArgs) {
+                if (!isSystemArgument(arg.getName())) {
+                    userArgs.add(arg);
+                }
+            }
+
+            List<ArgumentInfo> arguments = new ArrayList<>();
+
+            for (StaticArgument staticArg : userArgs) {
+                boolean isScalar = staticArg.getTraits().contains(StaticArgumentTrait.SCALAR);
+                boolean isTableArg =
+                        staticArg.getTraits().contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)
+                                || staticArg
+                                        .getTraits()
+                                        .contains(StaticArgumentTrait.SET_SEMANTIC_TABLE);
+
+                if (isScalar || isTableArg) {
+                    ArgumentInfo argInfo = buildArgumentInfo(staticArg);
+                    arguments.add(argInfo);
+                } else {
+                    throw new IllegalStateException(
+                            "Unknown argument type for StaticArgument. "
+                                    + "Expected SCALAR, ROW_SEMANTIC_TABLE, or SET_SEMANTIC_TABLE trait.");
+                }
+            }
+
+            validateArgumentConfiguration(arguments);
+
+            return arguments;
+        }
+
+        /** Checks if an argument name is a system-reserved argument. */
+        private boolean isSystemArgument(String argName) {
+            return SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_ON_TIME.equals(argName)
+                    || SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_UID.equals(argName);
+        }
+
+        private DataTypeFactory createDataTypeFactory() {
+            return new TestHarnessDataTypeFactory();
+        }
+
+        private ArgumentInfo buildArgumentInfo(StaticArgument staticArg) {
+
+            String name = staticArg.getName();
+            ArgumentTrait primaryTrait = extractPrimaryTrait(staticArg.getTraits());
+
+            DataType dataType;
+            if (primaryTrait == ArgumentTrait.SCALAR) {
+                Optional<DataType> dataTypeOpt = staticArg.getDataType();
+                if (dataTypeOpt.isPresent()) {
+                    dataType = dataTypeOpt.get();
+                } else {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "Cannot determine data type for scalar argument '%s'", name));
+                }
+            } else {
+                // For table arguments, check both annotation and builder config
+                Optional<DataType> annotationTypeOpt = staticArg.getDataType();
+                TableArgumentConfiguration config = tableArgs.get(name);
+
+                if (annotationTypeOpt.isPresent()
+                        && config != null
+                        && config.explicitType != null) {
+                    // Both specified - validate they match
+                    DataTypeFactory factory = createDataTypeFactory();
+                    DataType builderType = factory.createDataType(config.explicitType);
+                    DataType annotationType = annotationTypeOpt.get();
+
+                    if (!annotationType.equals(builderType)) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Type mismatch for table argument '%s': "
+                                                + "annotation declares type %s but builder declares type %s. "
+                                                + "Use either @ArgumentHint(type = ...) OR .withTableArgument(...), not both.",
+                                        name, annotationType, builderType));
+                    }
+                    dataType = annotationType;
+                } else if (annotationTypeOpt.isPresent()) {
+                    dataType = annotationTypeOpt.get();
+                } else if (config != null && config.explicitType != null) {
+                    DataTypeFactory factory = createDataTypeFactory();
+                    dataType = factory.createDataType(config.explicitType);
+                } else {
+                    // Try to infer from Java parameter class (for structured types)
+                    Optional<Class<?>> conversionClassOpt = staticArg.getConversionClass();
+                    if (conversionClassOpt.isPresent()) {
+                        DataTypeFactory factory = createDataTypeFactory();
+                        dataType = factory.createDataType(conversionClassOpt.get());
+                    } else {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Table argument '%s' requires explicit type configuration. "
+                                                + "Use @ArgumentHint(type = @DataTypeHint(\"ROW<...>\")) or "
+                                                + ".withTableArgument(\"%s\", DataTypes.of(\"ROW<...>\"))",
+                                        name, name));
+                    }
+                }
+            }
+
+            String[] partitionColumnNames = null;
+            if (primaryTrait == ArgumentTrait.SET_SEMANTIC_TABLE) {
+                boolean hasOptionalPartitionBy =
+                        staticArg.getTraits().contains(StaticArgumentTrait.OPTIONAL_PARTITION_BY);
+                partitionColumnNames =
+                        extractAndValidatePartitionColumns(name, dataType, hasOptionalPartitionBy);
+            }
+
+            boolean hasPassColumnsThrough =
+                    staticArg.getTraits().contains(StaticArgumentTrait.PASS_COLUMNS_THROUGH);
+
+            return new ArgumentInfo(
+                    name, dataType, primaryTrait, partitionColumnNames, hasPassColumnsThrough);
+        }
+
+        private ArgumentTrait extractPrimaryTrait(EnumSet<StaticArgumentTrait> staticTraits) {
+            if (staticTraits.contains(StaticArgumentTrait.SCALAR)) {
+                return ArgumentTrait.SCALAR;
+            }
+            if (staticTraits.contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)) {
+                return ArgumentTrait.ROW_SEMANTIC_TABLE;
+            }
+            if (staticTraits.contains(StaticArgumentTrait.SET_SEMANTIC_TABLE)) {
+                return ArgumentTrait.SET_SEMANTIC_TABLE;
+            }
+            return ArgumentTrait.SCALAR;
+        }
+
+        private String[] extractAndValidatePartitionColumns(
+                String name, DataType dataType, boolean isOptionalPartitionBy) {
+            PartitionConfiguration config = partitionConfigs.get(name);
+            if (config == null) {
+                if (isOptionalPartitionBy) {
+                    return null;
+                }
+                throw new IllegalStateException(
+                        String.format(
+                                "No partition configuration found for table argument '%s'. "
+                                        + "Use withPartitionBy(\"%s\", ...) to configure partitioning.",
+                                name, name));
+            }
+
+            LogicalType logicalType = dataType.getLogicalType();
+            List<String> fieldNames = new ArrayList<>();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                for (RowType.RowField field : rowType.getFields()) {
+                    fieldNames.add(field.getName());
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    fieldNames.add(attr.getName());
+                }
+            } else {
+                throw new IllegalStateException(
+                        String.format(
+                                "Unsupported data type for partitioning: %s. "
+                                        + "Only Row and structured types (POJOs) support partitioning.",
+                                dataType));
+            }
+
+            for (String columnName : config.columnNames) {
+                if (!fieldNames.contains(columnName)) {
+                    throw new IllegalArgumentException(
+                            "Partition column '"
+                                    + columnName
+                                    + "' not found. "
+                                    + "Available columns: "
+                                    + fieldNames);
+                }
+            }
+            return config.columnNames;
+        }
+
+        private void validateArgumentConfiguration(List<ArgumentInfo> arguments) {
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    if (!scalarArgs.containsKey(arg.name)) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Missing required scalar argument '%s'. "
+                                                + "Use .withScalarArgument(\"%s\", ...)",
+                                        arg.name, arg.name));
+                    }
+                } else {
+                    // For table arguments: builder config is optional if type comes from annotation
+                    boolean hasBuilderConfig = tableArgs.containsKey(arg.name);
+                    boolean hasInlineType = arg.dataType != null;
+
+                    if (!hasBuilderConfig && !hasInlineType) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Missing required table argument '%s'. "
+                                                + "Either specify @ArgumentHint(type = @DataTypeHint(...)) "
+                                                + "or use .withTableArgument(\"%s\", ...)",
+                                        arg.name, arg.name));
+                    }
+                }
+            }
+
+            Set<String> validNames = new HashSet<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    validNames.add(arg.name);
+                }
+            }
+
+            for (String configuredScalar : scalarArgs.keySet()) {
+                if (!validNames.contains(configuredScalar)) {
+                    throw new IllegalStateException(
+                            "Unknown scalar argument: '"
+                                    + configuredScalar
+                                    + "'. Not found in PTF signature.");
+                }
+            }
+
+            for (String configuredTable : tableArgs.keySet()) {
+                if (!validNames.contains(configuredTable)) {
+                    throw new IllegalStateException(
+                            "Unknown table argument: '"
+                                    + configuredTable
+                                    + "'. Not found in PTF signature.");
+                }
+            }
+        }
+
+        private ProcessTableFunction<OUT> instantiateFunction() throws IllegalArgumentException {
+            try {
+                return functionClass.getDeclaredConstructor().newInstance();
+            } catch (NoSuchMethodException e) {
+                throw new IllegalArgumentException(
+                        "PTF class must have a no-arg constructor: " + functionClass.getName(), e);
+            } catch (Exception e) {
+                throw new IllegalArgumentException(
+                        "Failed to instantiate PTF: " + functionClass.getName(), e);
+            }
+        }
+    }
+
+    /**
+     * Metadata for a single argument extracted from type inference.
+     *
+     * <p>Represents validated argument information combining PTF signature, type inference results,
+     * and builder configuration.
+     *
+     * <p>Position in eval() signature is implicit from the list order.
+     */
+    private static class ArgumentInfo {
+        final String name;
+        final DataType dataType;
+        final String[] partitionColumnNames; // nullable - only for SET_SEMANTIC_TABLE
+        final boolean isScalar;
+        final boolean isTableArgument;
+        final boolean isSetSemantic;
+        final boolean hasPassColumnsThrough;
+
+        ArgumentInfo(
+                String name,
+                DataType dataType,
+                ArgumentTrait primaryTrait,
+                String[] partitionColumnNames,
+                boolean hasPassColumnsThrough) {
+            this.name = name;
+            this.dataType = dataType;
+            this.partitionColumnNames = partitionColumnNames;
+            this.isScalar = (primaryTrait == ArgumentTrait.SCALAR);
+            this.isTableArgument = (primaryTrait != ArgumentTrait.SCALAR);
+            this.isSetSemantic = (primaryTrait == ArgumentTrait.SET_SEMANTIC_TABLE);
+            this.hasPassColumnsThrough = hasPassColumnsThrough;
+        }
+    }
+
+    private static class TableArgumentConfiguration {
+        AbstractDataType<?> explicitType; // from withTableArgument
+    }
+
+    private static class ScalarArgumentConfiguration {
+        Object value;

Review Comment:
   should this be final?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            LogicalType logicalType = dataType.getLogicalType();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                int index = 0;
+                for (RowType.RowField field : rowType.getFields()) {
+                    if (field.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                int index = 0;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    if (attr.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a table argument without an explicit schema.
+         *
+         * <p>Use this for structured type arguments where the type can be inferred from the PTF's
+         * eval() signature. For Row arguments, use {@link #withTableArgument(String,
+         * AbstractDataType)} with an explicit schema.
+         *
+         * @param argumentName The table argument name
+         */
+        public Builder<OUT> withTableArgument(String argumentName) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName) || tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException("Argument already configured: " + argumentName);
+            }
+
+            ScalarArgumentConfiguration config = new ScalarArgumentConfiguration(value);
+            scalarArgs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Partitioning
+        // ---------------------------------------------------------------------
+
+        /**
+         * Specifies partition columns for a set semantic table.
+         *
+         * @param argumentName The table argument name
+         * @param columnNames The partition column names
+         * @return This builder
+         */
+        public Builder<OUT> withPartitionBy(String argumentName, String... columnNames) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(columnNames, "columnNames must not be null");
+            checkArgument(columnNames.length > 0, "Must specify at least one column");
+
+            if (partitionConfigs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Partition config already exists for: " + argumentName);
+            }
+
+            PartitionConfiguration config = new PartitionConfiguration(columnNames);
+            partitionConfigs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Build
+        // ---------------------------------------------------------------------
+
+        /**
+         * Builds the test harness.
+         *
+         * <p>This instantiates the PTF, validates configuration via type inference, creates the
+         * FunctionContext, and opens the function.
+         *
+         * @return The configured test harness
+         * @throws Exception If instantiation or opening fails
+         */
+        public ProcessTableFunctionTestHarness<OUT> build() throws Exception {
+            ProcessTableFunction<OUT> function = instantiateFunction();
+
+            List<ArgumentInfo> arguments = extractAndValidateTypeInference(function);
+
+            FunctionContext functionContext =
+                    new FunctionContext(null, Thread.currentThread().getContextClassLoader(), null);
+
+            Method evalMethod = findEvalMethod();
+
+            validateEvalMethodSupported(evalMethod, arguments);
+            validatePartitionConsistency(arguments);
+
+            // In cases where PTFs have only a single table argument, set it as a default
+            // and mark as a single table function so that processElement without specifying
+            // a table argument can be used.
+            String defaultTableArg = null;
+            boolean isSingleTableFunction = false;
+
+            List<ArgumentInfo> tableArguments = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    tableArguments.add(arg);
+                }
+            }
+
+            if (tableArguments.size() == 1) {
+                defaultTableArg = tableArguments.get(0).name;
+                isSingleTableFunction = true;
+            }
+
+            Map<String, DataStructureConverter<Object, Object>> inputConverters = new HashMap<>();
+            Map<String, DataStructureConverter<Object, Object>> outputConverters = new HashMap<>();
+            createConverters(arguments, inputConverters, outputConverters);
+
+            Map<String, ArgumentInfo> argumentsByName = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    argumentsByName.put(arg.name, arg);
+                }
+            }
+
+            return new ProcessTableFunctionTestHarness<>(
+                    function,
+                    functionContext,
+                    defaultTableArg,
+                    evalMethod,
+                    arguments,
+                    argumentsByName,
+                    isSingleTableFunction,
+                    extractScalarValues(arguments),
+                    inputConverters,
+                    outputConverters);
+        }
+
+        /** Extracts scalar values from configs, creating a map keyed by argument name. */
+        private Map<String, Object> extractScalarValues(List<ArgumentInfo> arguments) {
+            Map<String, Object> values = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    ScalarArgumentConfiguration config = scalarArgs.get(arg.name);
+                    if (config != null) {
+                        values.put(arg.name, config.value);
+                    }
+                }
+            }
+            return values;
+        }
+
+        /**
+         * Creates and initializes data structure converters for all table arguments.
+         *
+         * <p>For Row types, both input and output converters are the same (between Row and
+         * RowData).
+         *
+         * <p>For structured types, input converter uses Row types (Row to RowData), and the output
+         * converter uses the structured type.
+         */
+        private void createConverters(
+                List<ArgumentInfo> arguments,
+                Map<String, DataStructureConverter<Object, Object>> inputConverters,
+                Map<String, DataStructureConverter<Object, Object>> outputConverters) {
+            ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    String converterKey = arg.name;
+
+                    LogicalType logicalType = arg.dataType.getLogicalType();
+                    boolean isStructuredType =
+                            logicalType instanceof StructuredType
+                                    && ((StructuredType) logicalType)
+                                            .getImplementationClass()
+                                            .isPresent();
+
+                    if (isStructuredType) {
+                        StructuredType structuredType = (StructuredType) logicalType;
+                        List<RowType.RowField> rowFields = new ArrayList<>();
+                        for (StructuredType.StructuredAttribute attr :
+                                structuredType.getAttributes()) {
+                            rowFields.add(new RowType.RowField(attr.getName(), attr.getType()));
+                        }
+                        RowType rowType = new RowType(logicalType.isNullable(), rowFields);
+                        DataType rowDataType = TypeConversions.fromLogicalToDataType(rowType);
+
+                        DataStructureConverter<Object, Object> inputConverter =
+                                DataStructureConverters.getConverter(rowDataType);
+                        inputConverter.open(classLoader);
+
+                        DataStructureConverter<Object, Object> outputConverter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        outputConverter.open(classLoader);
+
+                        inputConverters.put(converterKey, inputConverter);
+                        outputConverters.put(converterKey, outputConverter);
+                    } else {
+                        DataStructureConverter<Object, Object> converter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        converter.open(classLoader);
+
+                        inputConverters.put(converterKey, converter);
+                        outputConverters.put(converterKey, converter);
+                    }
+                }
+            }
+        }
+
+        private Method findEvalMethod() throws NoSuchMethodException {
+            Method[] methods = functionClass.getMethods();
+            Method evalMethod = null;
+            int evalMethodCount = 0;
+
+            for (Method method : methods) {
+                if (method.getName().equals("eval")) {
+                    evalMethod = method;
+                    evalMethodCount++;
+                }
+            }
+
+            if (evalMethodCount == 0) {
+                throw new NoSuchMethodException(
+                        "No eval() method found in " + functionClass.getSimpleName());
+            } else if (evalMethodCount > 1) {
+                throw new IllegalStateException(
+                        "Multiple eval() methods found in "
+                                + functionClass.getSimpleName()
+                                + ". ProcessTableFunction must have exactly one eval() method.");
+            } else {
+                return evalMethod;
+            }
+        }
+
+        /**
+         * Validates that the eval() method doesn't use unsupported features. Temporary, until state
+         * and context is supported.
+         */
+        private void validateEvalMethodSupported(Method evalMethod, List<ArgumentInfo> arguments) {
+            Parameter[] parameters = evalMethod.getParameters();
+
+            for (int i = 0; i < parameters.length; i++) {
+                Parameter param = parameters[i];
+                Class<?> paramType = param.getType();
+
+                if (ProcessTableFunction.Context.class.isAssignableFrom(paramType)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support Context parameters. "
+                                            + "Found Context parameter at position %d in eval() method. ",
+                                    i));
+                }
+
+                if (param.isAnnotationPresent(StateHint.class)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support state parameters. "
+                                            + "Found @StateHint parameter at position %d in eval() method. ",
+                                    i));
+                }
+            }
+
+            // Parameter count should also match our arguments list
+            if (parameters.length != arguments.size()) {
+                throw new IllegalStateException(
+                        String.format(
+                                "Parameter count mismatch: eval() has %d parameters but only %d arguments were extracted. "
+                                        + "This may indicate missing @ArgumentHint annotations.",
+                                parameters.length, arguments.size()));
+            }
+        }
+
+        /**
+         * Validates that all SET_SEMANTIC_TABLE arguments with partitioning use consistent
+         * partitioning. All such arguments must have the same number of partition columns with
+         * matching data types.
+         */
+        private void validatePartitionConsistency(List<ArgumentInfo> arguments) {
+            List<ArgumentInfo> partitionedTables = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    partitionedTables.add(arg);
+                }
+            }
+
+            if (partitionedTables.size() <= 1) {
+                return;
+            }
+
+            ArgumentInfo first = partitionedTables.get(0);
+            int expectedPartitionColumnCount = first.partitionColumnNames.length;
+
+            for (int i = 1; i < partitionedTables.size(); i++) {
+                ArgumentInfo current = partitionedTables.get(i);
+
+                if (current.partitionColumnNames.length != expectedPartitionColumnCount) {
+                    throw new IllegalArgumentException(
+                            String.format(
+                                    "Inconsistent partitioning: Table argument '%s' has %d partition column(s), "
+                                            + "but table argument '%s' has %d partition column(s). "
+                                            + "All SET_SEMANTIC_TABLE arguments must use consistent partitioning "
+                                            + "(same number of columns and matching data types).",
+                                    first.name,
+                                    expectedPartitionColumnCount,
+                                    current.name,
+                                    current.partitionColumnNames.length));
+                }
+
+                // Check that partition column types match
+                for (int colIdx = 0; colIdx < expectedPartitionColumnCount; colIdx++) {
+                    String firstColName = first.partitionColumnNames[colIdx];
+                    String currentColName = current.partitionColumnNames[colIdx];
+                    DataType firstColType = extractPartitionColumnType(first, firstColName);
+                    DataType currentColType = extractPartitionColumnType(current, currentColName);
+
+                    if (!firstColType.getLogicalType().equals(currentColType.getLogicalType())) {
+                        throw new IllegalArgumentException(
+                                String.format(
+                                        "Inconsistent partitioning: Partition column '%s' of table argument '%s' "
+                                                + "has type %s, but partition column '%s' of table argument '%s' "
+                                                + "has type %s. All SET_SEMANTIC_TABLE arguments must use "
+                                                + "consistent partitioning (same number of columns and matching data types).",
+                                        firstColName,
+                                        first.name,
+                                        firstColType,
+                                        currentColName,
+                                        current.name,
+                                        currentColType));
+                    }
+                }
+            }
+        }
+
+        private DataType extractPartitionColumnType(ArgumentInfo arg, String columnName) {
+            if (arg.dataType instanceof FieldsDataType) {
+                FieldsDataType fieldsDataType = (FieldsDataType) arg.dataType;
+                LogicalType logicalType = fieldsDataType.getLogicalType();
+                List<DataType> fieldDataTypes = fieldsDataType.getChildren();
+
+                if (logicalType instanceof RowType) {
+                    RowType rowType = (RowType) logicalType;
+                    int fieldIndex = 0;
+                    for (RowType.RowField field : rowType.getFields()) {
+                        if (field.getName().equals(columnName)) {
+                            return fieldDataTypes.get(fieldIndex);
+                        }
+                        fieldIndex++;
+                    }
+                } else if (logicalType instanceof StructuredType) {
+                    StructuredType structuredType = (StructuredType) logicalType;
+                    int attrIndex = 0;
+                    for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                        if (attr.getName().equals(columnName)) {
+                            return fieldDataTypes.get(attrIndex);
+                        }
+                        attrIndex++;
+                    }
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format(
+                            "Cannot extract data type for partition column '%s' of argument '%s'",
+                            columnName, arg.name));
+        }
+
+        // ---------------------------------------------------------------------
+        // Type Inference
+        // ---------------------------------------------------------------------
+
+        /**
+         * Extracts type inference from the PTF and validates builder configuration.
+         *
+         * <p>Uses SystemTypeInference to validate things like reserved argument names, multiple
+         * table argument rules, static argument trait validation, etc.
+         */
+        private List<ArgumentInfo> extractAndValidateTypeInference(
+                ProcessTableFunction<OUT> function) {
+
+            DataTypeFactory dataTypeFactory = createDataTypeFactory();
+            TypeInference baseTypeInference = function.getTypeInference(dataTypeFactory);
+            TypeInference systemTypeInference =
+                    SystemTypeInference.of(FunctionKind.PROCESS_TABLE, baseTypeInference);
+
+            Optional<List<StaticArgument>> staticArgsOpt = systemTypeInference.getStaticArguments();
+            if (staticArgsOpt.isEmpty()) {
+                throw new IllegalStateException(
+                        "PTF does not provide static argument information. "
+                                + "Ensure @ArgumentHint annotations are present on all eval() parameters.");
+            }
+
+            List<StaticArgument> allArgs = staticArgsOpt.get();
+            List<StaticArgument> userArgs = new ArrayList<>();
+            for (StaticArgument arg : allArgs) {
+                if (!isSystemArgument(arg.getName())) {
+                    userArgs.add(arg);
+                }
+            }
+
+            List<ArgumentInfo> arguments = new ArrayList<>();
+
+            for (StaticArgument staticArg : userArgs) {
+                boolean isScalar = staticArg.getTraits().contains(StaticArgumentTrait.SCALAR);
+                boolean isTableArg =
+                        staticArg.getTraits().contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)
+                                || staticArg
+                                        .getTraits()
+                                        .contains(StaticArgumentTrait.SET_SEMANTIC_TABLE);
+
+                if (isScalar || isTableArg) {
+                    ArgumentInfo argInfo = buildArgumentInfo(staticArg);
+                    arguments.add(argInfo);
+                } else {
+                    throw new IllegalStateException(
+                            "Unknown argument type for StaticArgument. "
+                                    + "Expected SCALAR, ROW_SEMANTIC_TABLE, or SET_SEMANTIC_TABLE trait.");
+                }
+            }
+
+            validateArgumentConfiguration(arguments);
+
+            return arguments;
+        }
+
+        /** Checks if an argument name is a system-reserved argument. */
+        private boolean isSystemArgument(String argName) {
+            return SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_ON_TIME.equals(argName)
+                    || SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_UID.equals(argName);
+        }
+
+        private DataTypeFactory createDataTypeFactory() {
+            return new TestHarnessDataTypeFactory();
+        }
+
+        private ArgumentInfo buildArgumentInfo(StaticArgument staticArg) {
+
+            String name = staticArg.getName();
+            ArgumentTrait primaryTrait = extractPrimaryTrait(staticArg.getTraits());
+
+            DataType dataType;
+            if (primaryTrait == ArgumentTrait.SCALAR) {
+                Optional<DataType> dataTypeOpt = staticArg.getDataType();
+                if (dataTypeOpt.isPresent()) {
+                    dataType = dataTypeOpt.get();
+                } else {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "Cannot determine data type for scalar argument '%s'", name));
+                }
+            } else {
+                // For table arguments, check both annotation and builder config
+                Optional<DataType> annotationTypeOpt = staticArg.getDataType();
+                TableArgumentConfiguration config = tableArgs.get(name);
+
+                if (annotationTypeOpt.isPresent()
+                        && config != null
+                        && config.explicitType != null) {
+                    // Both specified - validate they match
+                    DataTypeFactory factory = createDataTypeFactory();
+                    DataType builderType = factory.createDataType(config.explicitType);
+                    DataType annotationType = annotationTypeOpt.get();
+
+                    if (!annotationType.equals(builderType)) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Type mismatch for table argument '%s': "
+                                                + "annotation declares type %s but builder declares type %s. "
+                                                + "Use either @ArgumentHint(type = ...) OR .withTableArgument(...), not both.",
+                                        name, annotationType, builderType));
+                    }
+                    dataType = annotationType;
+                } else if (annotationTypeOpt.isPresent()) {
+                    dataType = annotationTypeOpt.get();
+                } else if (config != null && config.explicitType != null) {
+                    DataTypeFactory factory = createDataTypeFactory();
+                    dataType = factory.createDataType(config.explicitType);
+                } else {
+                    // Try to infer from Java parameter class (for structured types)
+                    Optional<Class<?>> conversionClassOpt = staticArg.getConversionClass();
+                    if (conversionClassOpt.isPresent()) {
+                        DataTypeFactory factory = createDataTypeFactory();
+                        dataType = factory.createDataType(conversionClassOpt.get());
+                    } else {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Table argument '%s' requires explicit type configuration. "
+                                                + "Use @ArgumentHint(type = @DataTypeHint(\"ROW<...>\")) or "
+                                                + ".withTableArgument(\"%s\", DataTypes.of(\"ROW<...>\"))",
+                                        name, name));
+                    }
+                }
+            }
+
+            String[] partitionColumnNames = null;
+            if (primaryTrait == ArgumentTrait.SET_SEMANTIC_TABLE) {
+                boolean hasOptionalPartitionBy =
+                        staticArg.getTraits().contains(StaticArgumentTrait.OPTIONAL_PARTITION_BY);
+                partitionColumnNames =
+                        extractAndValidatePartitionColumns(name, dataType, hasOptionalPartitionBy);
+            }
+
+            boolean hasPassColumnsThrough =
+                    staticArg.getTraits().contains(StaticArgumentTrait.PASS_COLUMNS_THROUGH);
+
+            return new ArgumentInfo(
+                    name, dataType, primaryTrait, partitionColumnNames, hasPassColumnsThrough);
+        }
+
+        private ArgumentTrait extractPrimaryTrait(EnumSet<StaticArgumentTrait> staticTraits) {
+            if (staticTraits.contains(StaticArgumentTrait.SCALAR)) {
+                return ArgumentTrait.SCALAR;
+            }
+            if (staticTraits.contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)) {
+                return ArgumentTrait.ROW_SEMANTIC_TABLE;
+            }
+            if (staticTraits.contains(StaticArgumentTrait.SET_SEMANTIC_TABLE)) {
+                return ArgumentTrait.SET_SEMANTIC_TABLE;
+            }
+            return ArgumentTrait.SCALAR;
+        }
+
+        private String[] extractAndValidatePartitionColumns(
+                String name, DataType dataType, boolean isOptionalPartitionBy) {
+            PartitionConfiguration config = partitionConfigs.get(name);
+            if (config == null) {
+                if (isOptionalPartitionBy) {
+                    return null;
+                }
+                throw new IllegalStateException(
+                        String.format(
+                                "No partition configuration found for table argument '%s'. "
+                                        + "Use withPartitionBy(\"%s\", ...) to configure partitioning.",
+                                name, name));
+            }
+
+            LogicalType logicalType = dataType.getLogicalType();
+            List<String> fieldNames = new ArrayList<>();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                for (RowType.RowField field : rowType.getFields()) {
+                    fieldNames.add(field.getName());
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    fieldNames.add(attr.getName());
+                }
+            } else {
+                throw new IllegalStateException(
+                        String.format(
+                                "Unsupported data type for partitioning: %s. "
+                                        + "Only Row and structured types (POJOs) support partitioning.",
+                                dataType));
+            }
+
+            for (String columnName : config.columnNames) {
+                if (!fieldNames.contains(columnName)) {
+                    throw new IllegalArgumentException(
+                            "Partition column '"
+                                    + columnName
+                                    + "' not found. "
+                                    + "Available columns: "
+                                    + fieldNames);
+                }
+            }
+            return config.columnNames;
+        }
+
+        private void validateArgumentConfiguration(List<ArgumentInfo> arguments) {
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    if (!scalarArgs.containsKey(arg.name)) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Missing required scalar argument '%s'. "
+                                                + "Use .withScalarArgument(\"%s\", ...)",
+                                        arg.name, arg.name));
+                    }
+                } else {
+                    // For table arguments: builder config is optional if type comes from annotation
+                    boolean hasBuilderConfig = tableArgs.containsKey(arg.name);
+                    boolean hasInlineType = arg.dataType != null;
+
+                    if (!hasBuilderConfig && !hasInlineType) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Missing required table argument '%s'. "
+                                                + "Either specify @ArgumentHint(type = @DataTypeHint(...)) "
+                                                + "or use .withTableArgument(\"%s\", ...)",
+                                        arg.name, arg.name));
+                    }
+                }
+            }
+
+            Set<String> validNames = new HashSet<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    validNames.add(arg.name);
+                }
+            }
+
+            for (String configuredScalar : scalarArgs.keySet()) {
+                if (!validNames.contains(configuredScalar)) {
+                    throw new IllegalStateException(
+                            "Unknown scalar argument: '"
+                                    + configuredScalar
+                                    + "'. Not found in PTF signature.");
+                }
+            }
+
+            for (String configuredTable : tableArgs.keySet()) {
+                if (!validNames.contains(configuredTable)) {
+                    throw new IllegalStateException(
+                            "Unknown table argument: '"
+                                    + configuredTable
+                                    + "'. Not found in PTF signature.");
+                }
+            }
+        }
+
+        private ProcessTableFunction<OUT> instantiateFunction() throws IllegalArgumentException {
+            try {
+                return functionClass.getDeclaredConstructor().newInstance();
+            } catch (NoSuchMethodException e) {
+                throw new IllegalArgumentException(
+                        "PTF class must have a no-arg constructor: " + functionClass.getName(), e);
+            } catch (Exception e) {
+                throw new IllegalArgumentException(
+                        "Failed to instantiate PTF: " + functionClass.getName(), e);
+            }
+        }
+    }
+
+    /**
+     * Metadata for a single argument extracted from type inference.
+     *
+     * <p>Represents validated argument information combining PTF signature, type inference results,
+     * and builder configuration.
+     *
+     * <p>Position in eval() signature is implicit from the list order.

Review Comment:
   This comment only makes sense in the context in which this class is used (as `List<ArgumentInfo>`) in the harness.
   Remove?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);

Review Comment:
   Provide all `eval()` args here as well?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            LogicalType logicalType = dataType.getLogicalType();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                int index = 0;
+                for (RowType.RowField field : rowType.getFields()) {
+                    if (field.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                int index = 0;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    if (attr.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a table argument without an explicit schema.
+         *
+         * <p>Use this for structured type arguments where the type can be inferred from the PTF's
+         * eval() signature. For Row arguments, use {@link #withTableArgument(String,
+         * AbstractDataType)} with an explicit schema.
+         *
+         * @param argumentName The table argument name
+         */
+        public Builder<OUT> withTableArgument(String argumentName) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName) || tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException("Argument already configured: " + argumentName);
+            }
+
+            ScalarArgumentConfiguration config = new ScalarArgumentConfiguration(value);
+            scalarArgs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Partitioning
+        // ---------------------------------------------------------------------
+
+        /**
+         * Specifies partition columns for a set semantic table.
+         *
+         * @param argumentName The table argument name
+         * @param columnNames The partition column names
+         * @return This builder
+         */
+        public Builder<OUT> withPartitionBy(String argumentName, String... columnNames) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(columnNames, "columnNames must not be null");
+            checkArgument(columnNames.length > 0, "Must specify at least one column");
+
+            if (partitionConfigs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Partition config already exists for: " + argumentName);
+            }
+
+            PartitionConfiguration config = new PartitionConfiguration(columnNames);
+            partitionConfigs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Build
+        // ---------------------------------------------------------------------
+
+        /**
+         * Builds the test harness.
+         *
+         * <p>This instantiates the PTF, validates configuration via type inference, creates the
+         * FunctionContext, and opens the function.
+         *
+         * @return The configured test harness
+         * @throws Exception If instantiation or opening fails
+         */
+        public ProcessTableFunctionTestHarness<OUT> build() throws Exception {
+            ProcessTableFunction<OUT> function = instantiateFunction();
+
+            List<ArgumentInfo> arguments = extractAndValidateTypeInference(function);
+
+            FunctionContext functionContext =
+                    new FunctionContext(null, Thread.currentThread().getContextClassLoader(), null);
+
+            Method evalMethod = findEvalMethod();
+
+            validateEvalMethodSupported(evalMethod, arguments);
+            validatePartitionConsistency(arguments);
+
+            // In cases where PTFs have only a single table argument, set it as a default
+            // and mark as a single table function so that processElement without specifying
+            // a table argument can be used.
+            String defaultTableArg = null;
+            boolean isSingleTableFunction = false;
+
+            List<ArgumentInfo> tableArguments = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    tableArguments.add(arg);
+                }
+            }
+
+            if (tableArguments.size() == 1) {
+                defaultTableArg = tableArguments.get(0).name;
+                isSingleTableFunction = true;
+            }

Review Comment:
   I would move this into the harness constructor and only pass the `arguments`.



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            LogicalType logicalType = dataType.getLogicalType();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                int index = 0;
+                for (RowType.RowField field : rowType.getFields()) {
+                    if (field.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                int index = 0;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    if (attr.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a table argument without an explicit schema.
+         *
+         * <p>Use this for structured type arguments where the type can be inferred from the PTF's
+         * eval() signature. For Row arguments, use {@link #withTableArgument(String,
+         * AbstractDataType)} with an explicit schema.
+         *
+         * @param argumentName The table argument name
+         */
+        public Builder<OUT> withTableArgument(String argumentName) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName) || tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException("Argument already configured: " + argumentName);
+            }
+
+            ScalarArgumentConfiguration config = new ScalarArgumentConfiguration(value);
+            scalarArgs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Partitioning
+        // ---------------------------------------------------------------------
+
+        /**
+         * Specifies partition columns for a set semantic table.
+         *
+         * @param argumentName The table argument name
+         * @param columnNames The partition column names
+         * @return This builder
+         */
+        public Builder<OUT> withPartitionBy(String argumentName, String... columnNames) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(columnNames, "columnNames must not be null");
+            checkArgument(columnNames.length > 0, "Must specify at least one column");
+
+            if (partitionConfigs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Partition config already exists for: " + argumentName);
+            }
+
+            PartitionConfiguration config = new PartitionConfiguration(columnNames);
+            partitionConfigs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Build
+        // ---------------------------------------------------------------------
+
+        /**
+         * Builds the test harness.
+         *
+         * <p>This instantiates the PTF, validates configuration via type inference, creates the
+         * FunctionContext, and opens the function.
+         *
+         * @return The configured test harness
+         * @throws Exception If instantiation or opening fails
+         */
+        public ProcessTableFunctionTestHarness<OUT> build() throws Exception {
+            ProcessTableFunction<OUT> function = instantiateFunction();
+
+            List<ArgumentInfo> arguments = extractAndValidateTypeInference(function);
+
+            FunctionContext functionContext =
+                    new FunctionContext(null, Thread.currentThread().getContextClassLoader(), null);
+
+            Method evalMethod = findEvalMethod();
+
+            validateEvalMethodSupported(evalMethod, arguments);
+            validatePartitionConsistency(arguments);
+
+            // In cases where PTFs have only a single table argument, set it as a default
+            // and mark as a single table function so that processElement without specifying
+            // a table argument can be used.
+            String defaultTableArg = null;
+            boolean isSingleTableFunction = false;
+
+            List<ArgumentInfo> tableArguments = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    tableArguments.add(arg);
+                }
+            }
+
+            if (tableArguments.size() == 1) {
+                defaultTableArg = tableArguments.get(0).name;
+                isSingleTableFunction = true;
+            }
+
+            Map<String, DataStructureConverter<Object, Object>> inputConverters = new HashMap<>();
+            Map<String, DataStructureConverter<Object, Object>> outputConverters = new HashMap<>();
+            createConverters(arguments, inputConverters, outputConverters);
+
+            Map<String, ArgumentInfo> argumentsByName = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    argumentsByName.put(arg.name, arg);
+                }
+            }
+
+            return new ProcessTableFunctionTestHarness<>(
+                    function,
+                    functionContext,
+                    defaultTableArg,
+                    evalMethod,
+                    arguments,
+                    argumentsByName,
+                    isSingleTableFunction,
+                    extractScalarValues(arguments),
+                    inputConverters,
+                    outputConverters);
+        }
+
+        /** Extracts scalar values from configs, creating a map keyed by argument name. */
+        private Map<String, Object> extractScalarValues(List<ArgumentInfo> arguments) {
+            Map<String, Object> values = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    ScalarArgumentConfiguration config = scalarArgs.get(arg.name);
+                    if (config != null) {
+                        values.put(arg.name, config.value);
+                    }
+                }
+            }
+            return values;
+        }
+
+        /**
+         * Creates and initializes data structure converters for all table arguments.
+         *
+         * <p>For Row types, both input and output converters are the same (between Row and
+         * RowData).
+         *
+         * <p>For structured types, input converter uses Row types (Row to RowData), and the output
+         * converter uses the structured type.
+         */
+        private void createConverters(
+                List<ArgumentInfo> arguments,
+                Map<String, DataStructureConverter<Object, Object>> inputConverters,
+                Map<String, DataStructureConverter<Object, Object>> outputConverters) {
+            ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    String converterKey = arg.name;
+
+                    LogicalType logicalType = arg.dataType.getLogicalType();
+                    boolean isStructuredType =
+                            logicalType instanceof StructuredType
+                                    && ((StructuredType) logicalType)
+                                            .getImplementationClass()
+                                            .isPresent();
+
+                    if (isStructuredType) {
+                        StructuredType structuredType = (StructuredType) logicalType;
+                        List<RowType.RowField> rowFields = new ArrayList<>();
+                        for (StructuredType.StructuredAttribute attr :
+                                structuredType.getAttributes()) {
+                            rowFields.add(new RowType.RowField(attr.getName(), attr.getType()));
+                        }
+                        RowType rowType = new RowType(logicalType.isNullable(), rowFields);
+                        DataType rowDataType = TypeConversions.fromLogicalToDataType(rowType);
+
+                        DataStructureConverter<Object, Object> inputConverter =
+                                DataStructureConverters.getConverter(rowDataType);
+                        inputConverter.open(classLoader);
+
+                        DataStructureConverter<Object, Object> outputConverter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        outputConverter.open(classLoader);
+
+                        inputConverters.put(converterKey, inputConverter);
+                        outputConverters.put(converterKey, outputConverter);
+                    } else {
+                        DataStructureConverter<Object, Object> converter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        converter.open(classLoader);
+
+                        inputConverters.put(converterKey, converter);
+                        outputConverters.put(converterKey, converter);
+                    }
+                }
+            }
+        }
+
+        private Method findEvalMethod() throws NoSuchMethodException {
+            Method[] methods = functionClass.getMethods();
+            Method evalMethod = null;
+            int evalMethodCount = 0;
+
+            for (Method method : methods) {
+                if (method.getName().equals("eval")) {
+                    evalMethod = method;
+                    evalMethodCount++;
+                }
+            }
+
+            if (evalMethodCount == 0) {
+                throw new NoSuchMethodException(
+                        "No eval() method found in " + functionClass.getSimpleName());
+            } else if (evalMethodCount > 1) {
+                throw new IllegalStateException(
+                        "Multiple eval() methods found in "
+                                + functionClass.getSimpleName()
+                                + ". ProcessTableFunction must have exactly one eval() method.");
+            } else {
+                return evalMethod;
+            }
+        }
+
+        /**
+         * Validates that the eval() method doesn't use unsupported features. Temporary, until state
+         * and context is supported.
+         */
+        private void validateEvalMethodSupported(Method evalMethod, List<ArgumentInfo> arguments) {
+            Parameter[] parameters = evalMethod.getParameters();
+
+            for (int i = 0; i < parameters.length; i++) {
+                Parameter param = parameters[i];
+                Class<?> paramType = param.getType();
+
+                if (ProcessTableFunction.Context.class.isAssignableFrom(paramType)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support Context parameters. "
+                                            + "Found Context parameter at position %d in eval() method. ",
+                                    i));
+                }
+
+                if (param.isAnnotationPresent(StateHint.class)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support state parameters. "
+                                            + "Found @StateHint parameter at position %d in eval() method. ",
+                                    i));
+                }
+            }
+
+            // Parameter count should also match our arguments list
+            if (parameters.length != arguments.size()) {
+                throw new IllegalStateException(
+                        String.format(
+                                "Parameter count mismatch: eval() has %d parameters but only %d arguments were extracted. "
+                                        + "This may indicate missing @ArgumentHint annotations.",
+                                parameters.length, arguments.size()));
+            }
+        }
+
+        /**
+         * Validates that all SET_SEMANTIC_TABLE arguments with partitioning use consistent
+         * partitioning. All such arguments must have the same number of partition columns with
+         * matching data types.
+         */
+        private void validatePartitionConsistency(List<ArgumentInfo> arguments) {
+            List<ArgumentInfo> partitionedTables = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    partitionedTables.add(arg);
+                }
+            }
+
+            if (partitionedTables.size() <= 1) {
+                return;
+            }
+
+            ArgumentInfo first = partitionedTables.get(0);
+            int expectedPartitionColumnCount = first.partitionColumnNames.length;
+
+            for (int i = 1; i < partitionedTables.size(); i++) {
+                ArgumentInfo current = partitionedTables.get(i);
+
+                if (current.partitionColumnNames.length != expectedPartitionColumnCount) {
+                    throw new IllegalArgumentException(
+                            String.format(
+                                    "Inconsistent partitioning: Table argument '%s' has %d partition column(s), "
+                                            + "but table argument '%s' has %d partition column(s). "
+                                            + "All SET_SEMANTIC_TABLE arguments must use consistent partitioning "
+                                            + "(same number of columns and matching data types).",
+                                    first.name,
+                                    expectedPartitionColumnCount,
+                                    current.name,
+                                    current.partitionColumnNames.length));
+                }
+
+                // Check that partition column types match
+                for (int colIdx = 0; colIdx < expectedPartitionColumnCount; colIdx++) {
+                    String firstColName = first.partitionColumnNames[colIdx];
+                    String currentColName = current.partitionColumnNames[colIdx];
+                    DataType firstColType = extractPartitionColumnType(first, firstColName);
+                    DataType currentColType = extractPartitionColumnType(current, currentColName);
+
+                    if (!firstColType.getLogicalType().equals(currentColType.getLogicalType())) {
+                        throw new IllegalArgumentException(
+                                String.format(
+                                        "Inconsistent partitioning: Partition column '%s' of table argument '%s' "
+                                                + "has type %s, but partition column '%s' of table argument '%s' "
+                                                + "has type %s. All SET_SEMANTIC_TABLE arguments must use "
+                                                + "consistent partitioning (same number of columns and matching data types).",
+                                        firstColName,
+                                        first.name,
+                                        firstColType,
+                                        currentColName,
+                                        current.name,
+                                        currentColType));
+                    }
+                }
+            }
+        }
+
+        private DataType extractPartitionColumnType(ArgumentInfo arg, String columnName) {
+            if (arg.dataType instanceof FieldsDataType) {
+                FieldsDataType fieldsDataType = (FieldsDataType) arg.dataType;
+                LogicalType logicalType = fieldsDataType.getLogicalType();
+                List<DataType> fieldDataTypes = fieldsDataType.getChildren();
+
+                if (logicalType instanceof RowType) {
+                    RowType rowType = (RowType) logicalType;
+                    int fieldIndex = 0;
+                    for (RowType.RowField field : rowType.getFields()) {
+                        if (field.getName().equals(columnName)) {
+                            return fieldDataTypes.get(fieldIndex);
+                        }
+                        fieldIndex++;
+                    }
+                } else if (logicalType instanceof StructuredType) {
+                    StructuredType structuredType = (StructuredType) logicalType;
+                    int attrIndex = 0;
+                    for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                        if (attr.getName().equals(columnName)) {
+                            return fieldDataTypes.get(attrIndex);
+                        }
+                        attrIndex++;
+                    }
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format(
+                            "Cannot extract data type for partition column '%s' of argument '%s'",
+                            columnName, arg.name));
+        }
+
+        // ---------------------------------------------------------------------
+        // Type Inference
+        // ---------------------------------------------------------------------
+
+        /**
+         * Extracts type inference from the PTF and validates builder configuration.
+         *
+         * <p>Uses SystemTypeInference to validate things like reserved argument names, multiple
+         * table argument rules, static argument trait validation, etc.
+         */
+        private List<ArgumentInfo> extractAndValidateTypeInference(
+                ProcessTableFunction<OUT> function) {
+
+            DataTypeFactory dataTypeFactory = createDataTypeFactory();
+            TypeInference baseTypeInference = function.getTypeInference(dataTypeFactory);
+            TypeInference systemTypeInference =
+                    SystemTypeInference.of(FunctionKind.PROCESS_TABLE, baseTypeInference);
+
+            Optional<List<StaticArgument>> staticArgsOpt = systemTypeInference.getStaticArguments();
+            if (staticArgsOpt.isEmpty()) {
+                throw new IllegalStateException(
+                        "PTF does not provide static argument information. "
+                                + "Ensure @ArgumentHint annotations are present on all eval() parameters.");
+            }
+
+            List<StaticArgument> allArgs = staticArgsOpt.get();
+            List<StaticArgument> userArgs = new ArrayList<>();
+            for (StaticArgument arg : allArgs) {
+                if (!isSystemArgument(arg.getName())) {
+                    userArgs.add(arg);
+                }
+            }
+
+            List<ArgumentInfo> arguments = new ArrayList<>();
+
+            for (StaticArgument staticArg : userArgs) {
+                boolean isScalar = staticArg.getTraits().contains(StaticArgumentTrait.SCALAR);
+                boolean isTableArg =
+                        staticArg.getTraits().contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)
+                                || staticArg
+                                        .getTraits()
+                                        .contains(StaticArgumentTrait.SET_SEMANTIC_TABLE);
+
+                if (isScalar || isTableArg) {
+                    ArgumentInfo argInfo = buildArgumentInfo(staticArg);
+                    arguments.add(argInfo);
+                } else {
+                    throw new IllegalStateException(
+                            "Unknown argument type for StaticArgument. "
+                                    + "Expected SCALAR, ROW_SEMANTIC_TABLE, or SET_SEMANTIC_TABLE trait.");
+                }
+            }
+
+            validateArgumentConfiguration(arguments);
+
+            return arguments;
+        }
+
+        /** Checks if an argument name is a system-reserved argument. */
+        private boolean isSystemArgument(String argName) {
+            return SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_ON_TIME.equals(argName)
+                    || SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_UID.equals(argName);
+        }
+
+        private DataTypeFactory createDataTypeFactory() {
+            return new TestHarnessDataTypeFactory();
+        }
+
+        private ArgumentInfo buildArgumentInfo(StaticArgument staticArg) {
+
+            String name = staticArg.getName();
+            ArgumentTrait primaryTrait = extractPrimaryTrait(staticArg.getTraits());
+
+            DataType dataType;
+            if (primaryTrait == ArgumentTrait.SCALAR) {
+                Optional<DataType> dataTypeOpt = staticArg.getDataType();
+                if (dataTypeOpt.isPresent()) {
+                    dataType = dataTypeOpt.get();
+                } else {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "Cannot determine data type for scalar argument '%s'", name));
+                }
+            } else {
+                // For table arguments, check both annotation and builder config
+                Optional<DataType> annotationTypeOpt = staticArg.getDataType();
+                TableArgumentConfiguration config = tableArgs.get(name);
+
+                if (annotationTypeOpt.isPresent()
+                        && config != null
+                        && config.explicitType != null) {
+                    // Both specified - validate they match
+                    DataTypeFactory factory = createDataTypeFactory();
+                    DataType builderType = factory.createDataType(config.explicitType);
+                    DataType annotationType = annotationTypeOpt.get();
+
+                    if (!annotationType.equals(builderType)) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Type mismatch for table argument '%s': "
+                                                + "annotation declares type %s but builder declares type %s. "
+                                                + "Use either @ArgumentHint(type = ...) OR .withTableArgument(...), not both.",
+                                        name, annotationType, builderType));
+                    }
+                    dataType = annotationType;
+                } else if (annotationTypeOpt.isPresent()) {
+                    dataType = annotationTypeOpt.get();
+                } else if (config != null && config.explicitType != null) {
+                    DataTypeFactory factory = createDataTypeFactory();
+                    dataType = factory.createDataType(config.explicitType);
+                } else {
+                    // Try to infer from Java parameter class (for structured types)
+                    Optional<Class<?>> conversionClassOpt = staticArg.getConversionClass();
+                    if (conversionClassOpt.isPresent()) {
+                        DataTypeFactory factory = createDataTypeFactory();
+                        dataType = factory.createDataType(conversionClassOpt.get());
+                    } else {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Table argument '%s' requires explicit type configuration. "
+                                                + "Use @ArgumentHint(type = @DataTypeHint(\"ROW<...>\")) or "
+                                                + ".withTableArgument(\"%s\", DataTypes.of(\"ROW<...>\"))",
+                                        name, name));
+                    }
+                }
+            }
+
+            String[] partitionColumnNames = null;
+            if (primaryTrait == ArgumentTrait.SET_SEMANTIC_TABLE) {
+                boolean hasOptionalPartitionBy =
+                        staticArg.getTraits().contains(StaticArgumentTrait.OPTIONAL_PARTITION_BY);
+                partitionColumnNames =
+                        extractAndValidatePartitionColumns(name, dataType, hasOptionalPartitionBy);
+            }
+
+            boolean hasPassColumnsThrough =
+                    staticArg.getTraits().contains(StaticArgumentTrait.PASS_COLUMNS_THROUGH);
+
+            return new ArgumentInfo(
+                    name, dataType, primaryTrait, partitionColumnNames, hasPassColumnsThrough);
+        }
+
+        private ArgumentTrait extractPrimaryTrait(EnumSet<StaticArgumentTrait> staticTraits) {
+            if (staticTraits.contains(StaticArgumentTrait.SCALAR)) {
+                return ArgumentTrait.SCALAR;
+            }
+            if (staticTraits.contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)) {
+                return ArgumentTrait.ROW_SEMANTIC_TABLE;
+            }
+            if (staticTraits.contains(StaticArgumentTrait.SET_SEMANTIC_TABLE)) {
+                return ArgumentTrait.SET_SEMANTIC_TABLE;
+            }
+            return ArgumentTrait.SCALAR;
+        }
+
+        private String[] extractAndValidatePartitionColumns(
+                String name, DataType dataType, boolean isOptionalPartitionBy) {
+            PartitionConfiguration config = partitionConfigs.get(name);
+            if (config == null) {
+                if (isOptionalPartitionBy) {
+                    return null;
+                }
+                throw new IllegalStateException(
+                        String.format(
+                                "No partition configuration found for table argument '%s'. "

Review Comment:
   Include SET_SEMANTIC_TABLE in the error message? 
   AFAIK, partitioning config is only required for these (unless OPTIONAL is specified).



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            LogicalType logicalType = dataType.getLogicalType();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                int index = 0;
+                for (RowType.RowField field : rowType.getFields()) {
+                    if (field.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                int index = 0;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    if (attr.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a table argument without an explicit schema.
+         *
+         * <p>Use this for structured type arguments where the type can be inferred from the PTF's
+         * eval() signature. For Row arguments, use {@link #withTableArgument(String,
+         * AbstractDataType)} with an explicit schema.
+         *
+         * @param argumentName The table argument name
+         */
+        public Builder<OUT> withTableArgument(String argumentName) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName) || tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException("Argument already configured: " + argumentName);
+            }
+
+            ScalarArgumentConfiguration config = new ScalarArgumentConfiguration(value);
+            scalarArgs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Partitioning
+        // ---------------------------------------------------------------------
+
+        /**
+         * Specifies partition columns for a set semantic table.
+         *
+         * @param argumentName The table argument name
+         * @param columnNames The partition column names
+         * @return This builder
+         */
+        public Builder<OUT> withPartitionBy(String argumentName, String... columnNames) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(columnNames, "columnNames must not be null");
+            checkArgument(columnNames.length > 0, "Must specify at least one column");
+
+            if (partitionConfigs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Partition config already exists for: " + argumentName);
+            }
+
+            PartitionConfiguration config = new PartitionConfiguration(columnNames);
+            partitionConfigs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Build
+        // ---------------------------------------------------------------------
+
+        /**
+         * Builds the test harness.
+         *
+         * <p>This instantiates the PTF, validates configuration via type inference, creates the
+         * FunctionContext, and opens the function.
+         *
+         * @return The configured test harness
+         * @throws Exception If instantiation or opening fails
+         */
+        public ProcessTableFunctionTestHarness<OUT> build() throws Exception {
+            ProcessTableFunction<OUT> function = instantiateFunction();
+
+            List<ArgumentInfo> arguments = extractAndValidateTypeInference(function);
+
+            FunctionContext functionContext =
+                    new FunctionContext(null, Thread.currentThread().getContextClassLoader(), null);
+
+            Method evalMethod = findEvalMethod();
+
+            validateEvalMethodSupported(evalMethod, arguments);
+            validatePartitionConsistency(arguments);
+
+            // In cases where PTFs have only a single table argument, set it as a default
+            // and mark as a single table function so that processElement without specifying
+            // a table argument can be used.
+            String defaultTableArg = null;
+            boolean isSingleTableFunction = false;
+
+            List<ArgumentInfo> tableArguments = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    tableArguments.add(arg);
+                }
+            }
+
+            if (tableArguments.size() == 1) {
+                defaultTableArg = tableArguments.get(0).name;
+                isSingleTableFunction = true;
+            }
+
+            Map<String, DataStructureConverter<Object, Object>> inputConverters = new HashMap<>();
+            Map<String, DataStructureConverter<Object, Object>> outputConverters = new HashMap<>();
+            createConverters(arguments, inputConverters, outputConverters);
+
+            Map<String, ArgumentInfo> argumentsByName = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    argumentsByName.put(arg.name, arg);
+                }
+            }
+
+            return new ProcessTableFunctionTestHarness<>(
+                    function,
+                    functionContext,
+                    defaultTableArg,
+                    evalMethod,
+                    arguments,
+                    argumentsByName,
+                    isSingleTableFunction,
+                    extractScalarValues(arguments),
+                    inputConverters,
+                    outputConverters);
+        }
+
+        /** Extracts scalar values from configs, creating a map keyed by argument name. */
+        private Map<String, Object> extractScalarValues(List<ArgumentInfo> arguments) {
+            Map<String, Object> values = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    ScalarArgumentConfiguration config = scalarArgs.get(arg.name);
+                    if (config != null) {
+                        values.put(arg.name, config.value);
+                    }
+                }
+            }
+            return values;
+        }
+
+        /**
+         * Creates and initializes data structure converters for all table arguments.
+         *
+         * <p>For Row types, both input and output converters are the same (between Row and
+         * RowData).
+         *
+         * <p>For structured types, input converter uses Row types (Row to RowData), and the output
+         * converter uses the structured type.
+         */
+        private void createConverters(
+                List<ArgumentInfo> arguments,
+                Map<String, DataStructureConverter<Object, Object>> inputConverters,
+                Map<String, DataStructureConverter<Object, Object>> outputConverters) {
+            ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    String converterKey = arg.name;
+
+                    LogicalType logicalType = arg.dataType.getLogicalType();
+                    boolean isStructuredType =
+                            logicalType instanceof StructuredType
+                                    && ((StructuredType) logicalType)
+                                            .getImplementationClass()
+                                            .isPresent();
+
+                    if (isStructuredType) {
+                        StructuredType structuredType = (StructuredType) logicalType;
+                        List<RowType.RowField> rowFields = new ArrayList<>();
+                        for (StructuredType.StructuredAttribute attr :
+                                structuredType.getAttributes()) {
+                            rowFields.add(new RowType.RowField(attr.getName(), attr.getType()));
+                        }
+                        RowType rowType = new RowType(logicalType.isNullable(), rowFields);
+                        DataType rowDataType = TypeConversions.fromLogicalToDataType(rowType);
+
+                        DataStructureConverter<Object, Object> inputConverter =
+                                DataStructureConverters.getConverter(rowDataType);
+                        inputConverter.open(classLoader);
+
+                        DataStructureConverter<Object, Object> outputConverter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        outputConverter.open(classLoader);
+
+                        inputConverters.put(converterKey, inputConverter);
+                        outputConverters.put(converterKey, outputConverter);
+                    } else {
+                        DataStructureConverter<Object, Object> converter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        converter.open(classLoader);
+
+                        inputConverters.put(converterKey, converter);
+                        outputConverters.put(converterKey, converter);
+                    }
+                }
+            }
+        }
+
+        private Method findEvalMethod() throws NoSuchMethodException {
+            Method[] methods = functionClass.getMethods();
+            Method evalMethod = null;
+            int evalMethodCount = 0;
+
+            for (Method method : methods) {
+                if (method.getName().equals("eval")) {
+                    evalMethod = method;
+                    evalMethodCount++;
+                }
+            }
+
+            if (evalMethodCount == 0) {
+                throw new NoSuchMethodException(
+                        "No eval() method found in " + functionClass.getSimpleName());
+            } else if (evalMethodCount > 1) {
+                throw new IllegalStateException(
+                        "Multiple eval() methods found in "
+                                + functionClass.getSimpleName()
+                                + ". ProcessTableFunction must have exactly one eval() method.");
+            } else {
+                return evalMethod;
+            }
+        }
+
+        /**
+         * Validates that the eval() method doesn't use unsupported features. Temporary, until state
+         * and context is supported.
+         */
+        private void validateEvalMethodSupported(Method evalMethod, List<ArgumentInfo> arguments) {
+            Parameter[] parameters = evalMethod.getParameters();
+
+            for (int i = 0; i < parameters.length; i++) {
+                Parameter param = parameters[i];
+                Class<?> paramType = param.getType();
+
+                if (ProcessTableFunction.Context.class.isAssignableFrom(paramType)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support Context parameters. "
+                                            + "Found Context parameter at position %d in eval() method. ",
+                                    i));
+                }
+
+                if (param.isAnnotationPresent(StateHint.class)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support state parameters. "
+                                            + "Found @StateHint parameter at position %d in eval() method. ",
+                                    i));
+                }
+            }
+
+            // Parameter count should also match our arguments list
+            if (parameters.length != arguments.size()) {
+                throw new IllegalStateException(
+                        String.format(
+                                "Parameter count mismatch: eval() has %d parameters but only %d arguments were extracted. "
+                                        + "This may indicate missing @ArgumentHint annotations.",
+                                parameters.length, arguments.size()));
+            }
+        }
+
+        /**
+         * Validates that all SET_SEMANTIC_TABLE arguments with partitioning use consistent
+         * partitioning. All such arguments must have the same number of partition columns with
+         * matching data types.
+         */
+        private void validatePartitionConsistency(List<ArgumentInfo> arguments) {
+            List<ArgumentInfo> partitionedTables = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    partitionedTables.add(arg);
+                }
+            }
+
+            if (partitionedTables.size() <= 1) {
+                return;
+            }
+
+            ArgumentInfo first = partitionedTables.get(0);
+            int expectedPartitionColumnCount = first.partitionColumnNames.length;
+
+            for (int i = 1; i < partitionedTables.size(); i++) {
+                ArgumentInfo current = partitionedTables.get(i);
+
+                if (current.partitionColumnNames.length != expectedPartitionColumnCount) {
+                    throw new IllegalArgumentException(
+                            String.format(
+                                    "Inconsistent partitioning: Table argument '%s' has %d partition column(s), "
+                                            + "but table argument '%s' has %d partition column(s). "
+                                            + "All SET_SEMANTIC_TABLE arguments must use consistent partitioning "
+                                            + "(same number of columns and matching data types).",
+                                    first.name,
+                                    expectedPartitionColumnCount,
+                                    current.name,
+                                    current.partitionColumnNames.length));
+                }
+
+                // Check that partition column types match
+                for (int colIdx = 0; colIdx < expectedPartitionColumnCount; colIdx++) {
+                    String firstColName = first.partitionColumnNames[colIdx];
+                    String currentColName = current.partitionColumnNames[colIdx];
+                    DataType firstColType = extractPartitionColumnType(first, firstColName);
+                    DataType currentColType = extractPartitionColumnType(current, currentColName);
+
+                    if (!firstColType.getLogicalType().equals(currentColType.getLogicalType())) {
+                        throw new IllegalArgumentException(
+                                String.format(
+                                        "Inconsistent partitioning: Partition column '%s' of table argument '%s' "
+                                                + "has type %s, but partition column '%s' of table argument '%s' "
+                                                + "has type %s. All SET_SEMANTIC_TABLE arguments must use "
+                                                + "consistent partitioning (same number of columns and matching data types).",
+                                        firstColName,
+                                        first.name,
+                                        firstColType,
+                                        currentColName,
+                                        current.name,
+                                        currentColType));
+                    }
+                }
+            }
+        }
+
+        private DataType extractPartitionColumnType(ArgumentInfo arg, String columnName) {
+            if (arg.dataType instanceof FieldsDataType) {
+                FieldsDataType fieldsDataType = (FieldsDataType) arg.dataType;
+                LogicalType logicalType = fieldsDataType.getLogicalType();
+                List<DataType> fieldDataTypes = fieldsDataType.getChildren();
+
+                if (logicalType instanceof RowType) {
+                    RowType rowType = (RowType) logicalType;
+                    int fieldIndex = 0;
+                    for (RowType.RowField field : rowType.getFields()) {
+                        if (field.getName().equals(columnName)) {
+                            return fieldDataTypes.get(fieldIndex);
+                        }
+                        fieldIndex++;
+                    }
+                } else if (logicalType instanceof StructuredType) {
+                    StructuredType structuredType = (StructuredType) logicalType;
+                    int attrIndex = 0;
+                    for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                        if (attr.getName().equals(columnName)) {
+                            return fieldDataTypes.get(attrIndex);
+                        }
+                        attrIndex++;
+                    }
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format(
+                            "Cannot extract data type for partition column '%s' of argument '%s'",
+                            columnName, arg.name));
+        }
+
+        // ---------------------------------------------------------------------
+        // Type Inference
+        // ---------------------------------------------------------------------
+
+        /**
+         * Extracts type inference from the PTF and validates builder configuration.
+         *
+         * <p>Uses SystemTypeInference to validate things like reserved argument names, multiple
+         * table argument rules, static argument trait validation, etc.
+         */
+        private List<ArgumentInfo> extractAndValidateTypeInference(
+                ProcessTableFunction<OUT> function) {
+
+            DataTypeFactory dataTypeFactory = createDataTypeFactory();
+            TypeInference baseTypeInference = function.getTypeInference(dataTypeFactory);
+            TypeInference systemTypeInference =
+                    SystemTypeInference.of(FunctionKind.PROCESS_TABLE, baseTypeInference);
+
+            Optional<List<StaticArgument>> staticArgsOpt = systemTypeInference.getStaticArguments();
+            if (staticArgsOpt.isEmpty()) {
+                throw new IllegalStateException(
+                        "PTF does not provide static argument information. "
+                                + "Ensure @ArgumentHint annotations are present on all eval() parameters.");
+            }
+
+            List<StaticArgument> allArgs = staticArgsOpt.get();
+            List<StaticArgument> userArgs = new ArrayList<>();
+            for (StaticArgument arg : allArgs) {
+                if (!isSystemArgument(arg.getName())) {
+                    userArgs.add(arg);
+                }
+            }
+
+            List<ArgumentInfo> arguments = new ArrayList<>();
+
+            for (StaticArgument staticArg : userArgs) {
+                boolean isScalar = staticArg.getTraits().contains(StaticArgumentTrait.SCALAR);
+                boolean isTableArg =
+                        staticArg.getTraits().contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)
+                                || staticArg
+                                        .getTraits()
+                                        .contains(StaticArgumentTrait.SET_SEMANTIC_TABLE);
+
+                if (isScalar || isTableArg) {
+                    ArgumentInfo argInfo = buildArgumentInfo(staticArg);
+                    arguments.add(argInfo);
+                } else {
+                    throw new IllegalStateException(
+                            "Unknown argument type for StaticArgument. "
+                                    + "Expected SCALAR, ROW_SEMANTIC_TABLE, or SET_SEMANTIC_TABLE trait.");
+                }
+            }
+
+            validateArgumentConfiguration(arguments);
+
+            return arguments;
+        }
+
+        /** Checks if an argument name is a system-reserved argument. */
+        private boolean isSystemArgument(String argName) {
+            return SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_ON_TIME.equals(argName)
+                    || SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_UID.equals(argName);
+        }
+
+        private DataTypeFactory createDataTypeFactory() {
+            return new TestHarnessDataTypeFactory();
+        }
+
+        private ArgumentInfo buildArgumentInfo(StaticArgument staticArg) {
+
+            String name = staticArg.getName();
+            ArgumentTrait primaryTrait = extractPrimaryTrait(staticArg.getTraits());
+
+            DataType dataType;
+            if (primaryTrait == ArgumentTrait.SCALAR) {
+                Optional<DataType> dataTypeOpt = staticArg.getDataType();
+                if (dataTypeOpt.isPresent()) {
+                    dataType = dataTypeOpt.get();
+                } else {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "Cannot determine data type for scalar argument '%s'", name));
+                }
+            } else {
+                // For table arguments, check both annotation and builder config
+                Optional<DataType> annotationTypeOpt = staticArg.getDataType();
+                TableArgumentConfiguration config = tableArgs.get(name);
+
+                if (annotationTypeOpt.isPresent()
+                        && config != null
+                        && config.explicitType != null) {
+                    // Both specified - validate they match
+                    DataTypeFactory factory = createDataTypeFactory();
+                    DataType builderType = factory.createDataType(config.explicitType);
+                    DataType annotationType = annotationTypeOpt.get();
+
+                    if (!annotationType.equals(builderType)) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Type mismatch for table argument '%s': "
+                                                + "annotation declares type %s but builder declares type %s. "
+                                                + "Use either @ArgumentHint(type = ...) OR .withTableArgument(...), not both.",
+                                        name, annotationType, builderType));
+                    }
+                    dataType = annotationType;
+                } else if (annotationTypeOpt.isPresent()) {
+                    dataType = annotationTypeOpt.get();
+                } else if (config != null && config.explicitType != null) {
+                    DataTypeFactory factory = createDataTypeFactory();
+                    dataType = factory.createDataType(config.explicitType);
+                } else {
+                    // Try to infer from Java parameter class (for structured types)
+                    Optional<Class<?>> conversionClassOpt = staticArg.getConversionClass();
+                    if (conversionClassOpt.isPresent()) {
+                        DataTypeFactory factory = createDataTypeFactory();
+                        dataType = factory.createDataType(conversionClassOpt.get());
+                    } else {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Table argument '%s' requires explicit type configuration. "
+                                                + "Use @ArgumentHint(type = @DataTypeHint(\"ROW<...>\")) or "
+                                                + ".withTableArgument(\"%s\", DataTypes.of(\"ROW<...>\"))",

Review Comment:
   Not sure if we should present these as equivalent alternatives. 
   `@ArgumentHint` is effectively changing the PTF (and how it can be used) while the other option is just a different configuration of the test harness.



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,

Review Comment:
   could this be derived from `arguments` like
   ```
   arguments.stream().filter(a -> a.isTableArgument()).count() == 1
   ```
   ?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,

Review Comment:
   derivable from `arguments`?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,

Review Comment:
   could also be derived from `arguments`?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            LogicalType logicalType = dataType.getLogicalType();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                int index = 0;
+                for (RowType.RowField field : rowType.getFields()) {
+                    if (field.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                int index = 0;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    if (attr.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a table argument without an explicit schema.
+         *
+         * <p>Use this for structured type arguments where the type can be inferred from the PTF's
+         * eval() signature. For Row arguments, use {@link #withTableArgument(String,
+         * AbstractDataType)} with an explicit schema.
+         *
+         * @param argumentName The table argument name
+         */
+        public Builder<OUT> withTableArgument(String argumentName) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName) || tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException("Argument already configured: " + argumentName);
+            }
+
+            ScalarArgumentConfiguration config = new ScalarArgumentConfiguration(value);
+            scalarArgs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Partitioning
+        // ---------------------------------------------------------------------
+
+        /**
+         * Specifies partition columns for a set semantic table.
+         *
+         * @param argumentName The table argument name
+         * @param columnNames The partition column names
+         * @return This builder
+         */
+        public Builder<OUT> withPartitionBy(String argumentName, String... columnNames) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(columnNames, "columnNames must not be null");
+            checkArgument(columnNames.length > 0, "Must specify at least one column");
+
+            if (partitionConfigs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Partition config already exists for: " + argumentName);
+            }
+
+            PartitionConfiguration config = new PartitionConfiguration(columnNames);
+            partitionConfigs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Build
+        // ---------------------------------------------------------------------
+
+        /**
+         * Builds the test harness.
+         *
+         * <p>This instantiates the PTF, validates configuration via type inference, creates the
+         * FunctionContext, and opens the function.
+         *
+         * @return The configured test harness
+         * @throws Exception If instantiation or opening fails
+         */
+        public ProcessTableFunctionTestHarness<OUT> build() throws Exception {
+            ProcessTableFunction<OUT> function = instantiateFunction();
+
+            List<ArgumentInfo> arguments = extractAndValidateTypeInference(function);
+
+            FunctionContext functionContext =
+                    new FunctionContext(null, Thread.currentThread().getContextClassLoader(), null);
+
+            Method evalMethod = findEvalMethod();
+
+            validateEvalMethodSupported(evalMethod, arguments);
+            validatePartitionConsistency(arguments);
+
+            // In cases where PTFs have only a single table argument, set it as a default
+            // and mark as a single table function so that processElement without specifying
+            // a table argument can be used.
+            String defaultTableArg = null;
+            boolean isSingleTableFunction = false;
+
+            List<ArgumentInfo> tableArguments = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    tableArguments.add(arg);
+                }
+            }
+
+            if (tableArguments.size() == 1) {
+                defaultTableArg = tableArguments.get(0).name;
+                isSingleTableFunction = true;
+            }
+
+            Map<String, DataStructureConverter<Object, Object>> inputConverters = new HashMap<>();
+            Map<String, DataStructureConverter<Object, Object>> outputConverters = new HashMap<>();
+            createConverters(arguments, inputConverters, outputConverters);
+
+            Map<String, ArgumentInfo> argumentsByName = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    argumentsByName.put(arg.name, arg);
+                }
+            }
+
+            return new ProcessTableFunctionTestHarness<>(
+                    function,
+                    functionContext,
+                    defaultTableArg,
+                    evalMethod,
+                    arguments,
+                    argumentsByName,
+                    isSingleTableFunction,
+                    extractScalarValues(arguments),
+                    inputConverters,
+                    outputConverters);
+        }
+
+        /** Extracts scalar values from configs, creating a map keyed by argument name. */
+        private Map<String, Object> extractScalarValues(List<ArgumentInfo> arguments) {
+            Map<String, Object> values = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    ScalarArgumentConfiguration config = scalarArgs.get(arg.name);
+                    if (config != null) {
+                        values.put(arg.name, config.value);
+                    }
+                }
+            }
+            return values;
+        }
+
+        /**
+         * Creates and initializes data structure converters for all table arguments.
+         *
+         * <p>For Row types, both input and output converters are the same (between Row and
+         * RowData).
+         *
+         * <p>For structured types, input converter uses Row types (Row to RowData), and the output
+         * converter uses the structured type.
+         */
+        private void createConverters(
+                List<ArgumentInfo> arguments,
+                Map<String, DataStructureConverter<Object, Object>> inputConverters,
+                Map<String, DataStructureConverter<Object, Object>> outputConverters) {
+            ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    String converterKey = arg.name;
+
+                    LogicalType logicalType = arg.dataType.getLogicalType();
+                    boolean isStructuredType =
+                            logicalType instanceof StructuredType
+                                    && ((StructuredType) logicalType)
+                                            .getImplementationClass()
+                                            .isPresent();
+
+                    if (isStructuredType) {
+                        StructuredType structuredType = (StructuredType) logicalType;
+                        List<RowType.RowField> rowFields = new ArrayList<>();
+                        for (StructuredType.StructuredAttribute attr :
+                                structuredType.getAttributes()) {
+                            rowFields.add(new RowType.RowField(attr.getName(), attr.getType()));
+                        }
+                        RowType rowType = new RowType(logicalType.isNullable(), rowFields);
+                        DataType rowDataType = TypeConversions.fromLogicalToDataType(rowType);
+
+                        DataStructureConverter<Object, Object> inputConverter =
+                                DataStructureConverters.getConverter(rowDataType);
+                        inputConverter.open(classLoader);
+
+                        DataStructureConverter<Object, Object> outputConverter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        outputConverter.open(classLoader);
+
+                        inputConverters.put(converterKey, inputConverter);
+                        outputConverters.put(converterKey, outputConverter);
+                    } else {
+                        DataStructureConverter<Object, Object> converter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        converter.open(classLoader);
+
+                        inputConverters.put(converterKey, converter);
+                        outputConverters.put(converterKey, converter);
+                    }
+                }
+            }
+        }
+
+        private Method findEvalMethod() throws NoSuchMethodException {
+            Method[] methods = functionClass.getMethods();
+            Method evalMethod = null;
+            int evalMethodCount = 0;
+
+            for (Method method : methods) {
+                if (method.getName().equals("eval")) {
+                    evalMethod = method;
+                    evalMethodCount++;
+                }
+            }
+
+            if (evalMethodCount == 0) {
+                throw new NoSuchMethodException(
+                        "No eval() method found in " + functionClass.getSimpleName());
+            } else if (evalMethodCount > 1) {
+                throw new IllegalStateException(
+                        "Multiple eval() methods found in "
+                                + functionClass.getSimpleName()
+                                + ". ProcessTableFunction must have exactly one eval() method.");
+            } else {
+                return evalMethod;
+            }
+        }
+
+        /**
+         * Validates that the eval() method doesn't use unsupported features. Temporary, until state
+         * and context is supported.
+         */
+        private void validateEvalMethodSupported(Method evalMethod, List<ArgumentInfo> arguments) {
+            Parameter[] parameters = evalMethod.getParameters();
+
+            for (int i = 0; i < parameters.length; i++) {
+                Parameter param = parameters[i];
+                Class<?> paramType = param.getType();
+
+                if (ProcessTableFunction.Context.class.isAssignableFrom(paramType)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support Context parameters. "
+                                            + "Found Context parameter at position %d in eval() method. ",
+                                    i));
+                }
+
+                if (param.isAnnotationPresent(StateHint.class)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support state parameters. "
+                                            + "Found @StateHint parameter at position %d in eval() method. ",
+                                    i));
+                }
+            }
+
+            // Parameter count should also match our arguments list
+            if (parameters.length != arguments.size()) {
+                throw new IllegalStateException(
+                        String.format(
+                                "Parameter count mismatch: eval() has %d parameters but only %d arguments were extracted. "
+                                        + "This may indicate missing @ArgumentHint annotations.",
+                                parameters.length, arguments.size()));
+            }
+        }
+
+        /**
+         * Validates that all SET_SEMANTIC_TABLE arguments with partitioning use consistent
+         * partitioning. All such arguments must have the same number of partition columns with
+         * matching data types.
+         */
+        private void validatePartitionConsistency(List<ArgumentInfo> arguments) {
+            List<ArgumentInfo> partitionedTables = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    partitionedTables.add(arg);
+                }
+            }
+
+            if (partitionedTables.size() <= 1) {
+                return;
+            }
+
+            ArgumentInfo first = partitionedTables.get(0);
+            int expectedPartitionColumnCount = first.partitionColumnNames.length;
+
+            for (int i = 1; i < partitionedTables.size(); i++) {
+                ArgumentInfo current = partitionedTables.get(i);
+
+                if (current.partitionColumnNames.length != expectedPartitionColumnCount) {
+                    throw new IllegalArgumentException(
+                            String.format(
+                                    "Inconsistent partitioning: Table argument '%s' has %d partition column(s), "
+                                            + "but table argument '%s' has %d partition column(s). "
+                                            + "All SET_SEMANTIC_TABLE arguments must use consistent partitioning "
+                                            + "(same number of columns and matching data types).",
+                                    first.name,
+                                    expectedPartitionColumnCount,
+                                    current.name,
+                                    current.partitionColumnNames.length));
+                }
+
+                // Check that partition column types match
+                for (int colIdx = 0; colIdx < expectedPartitionColumnCount; colIdx++) {
+                    String firstColName = first.partitionColumnNames[colIdx];
+                    String currentColName = current.partitionColumnNames[colIdx];
+                    DataType firstColType = extractPartitionColumnType(first, firstColName);
+                    DataType currentColType = extractPartitionColumnType(current, currentColName);
+
+                    if (!firstColType.getLogicalType().equals(currentColType.getLogicalType())) {
+                        throw new IllegalArgumentException(
+                                String.format(
+                                        "Inconsistent partitioning: Partition column '%s' of table argument '%s' "
+                                                + "has type %s, but partition column '%s' of table argument '%s' "
+                                                + "has type %s. All SET_SEMANTIC_TABLE arguments must use "
+                                                + "consistent partitioning (same number of columns and matching data types).",
+                                        firstColName,
+                                        first.name,
+                                        firstColType,
+                                        currentColName,
+                                        current.name,
+                                        currentColType));
+                    }
+                }
+            }
+        }
+
+        private DataType extractPartitionColumnType(ArgumentInfo arg, String columnName) {
+            if (arg.dataType instanceof FieldsDataType) {
+                FieldsDataType fieldsDataType = (FieldsDataType) arg.dataType;
+                LogicalType logicalType = fieldsDataType.getLogicalType();
+                List<DataType> fieldDataTypes = fieldsDataType.getChildren();
+
+                if (logicalType instanceof RowType) {
+                    RowType rowType = (RowType) logicalType;
+                    int fieldIndex = 0;
+                    for (RowType.RowField field : rowType.getFields()) {
+                        if (field.getName().equals(columnName)) {
+                            return fieldDataTypes.get(fieldIndex);
+                        }
+                        fieldIndex++;
+                    }
+                } else if (logicalType instanceof StructuredType) {
+                    StructuredType structuredType = (StructuredType) logicalType;
+                    int attrIndex = 0;
+                    for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                        if (attr.getName().equals(columnName)) {
+                            return fieldDataTypes.get(attrIndex);
+                        }
+                        attrIndex++;
+                    }
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format(
+                            "Cannot extract data type for partition column '%s' of argument '%s'",
+                            columnName, arg.name));
+        }
+
+        // ---------------------------------------------------------------------
+        // Type Inference
+        // ---------------------------------------------------------------------
+
+        /**
+         * Extracts type inference from the PTF and validates builder configuration.
+         *
+         * <p>Uses SystemTypeInference to validate things like reserved argument names, multiple
+         * table argument rules, static argument trait validation, etc.
+         */
+        private List<ArgumentInfo> extractAndValidateTypeInference(
+                ProcessTableFunction<OUT> function) {
+
+            DataTypeFactory dataTypeFactory = createDataTypeFactory();
+            TypeInference baseTypeInference = function.getTypeInference(dataTypeFactory);
+            TypeInference systemTypeInference =
+                    SystemTypeInference.of(FunctionKind.PROCESS_TABLE, baseTypeInference);
+
+            Optional<List<StaticArgument>> staticArgsOpt = systemTypeInference.getStaticArguments();
+            if (staticArgsOpt.isEmpty()) {
+                throw new IllegalStateException(
+                        "PTF does not provide static argument information. "
+                                + "Ensure @ArgumentHint annotations are present on all eval() parameters.");
+            }
+
+            List<StaticArgument> allArgs = staticArgsOpt.get();
+            List<StaticArgument> userArgs = new ArrayList<>();
+            for (StaticArgument arg : allArgs) {
+                if (!isSystemArgument(arg.getName())) {
+                    userArgs.add(arg);
+                }
+            }
+
+            List<ArgumentInfo> arguments = new ArrayList<>();
+
+            for (StaticArgument staticArg : userArgs) {
+                boolean isScalar = staticArg.getTraits().contains(StaticArgumentTrait.SCALAR);
+                boolean isTableArg =
+                        staticArg.getTraits().contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)
+                                || staticArg
+                                        .getTraits()
+                                        .contains(StaticArgumentTrait.SET_SEMANTIC_TABLE);
+
+                if (isScalar || isTableArg) {
+                    ArgumentInfo argInfo = buildArgumentInfo(staticArg);
+                    arguments.add(argInfo);
+                } else {
+                    throw new IllegalStateException(
+                            "Unknown argument type for StaticArgument. "
+                                    + "Expected SCALAR, ROW_SEMANTIC_TABLE, or SET_SEMANTIC_TABLE trait.");
+                }
+            }
+
+            validateArgumentConfiguration(arguments);
+
+            return arguments;
+        }
+
+        /** Checks if an argument name is a system-reserved argument. */
+        private boolean isSystemArgument(String argName) {
+            return SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_ON_TIME.equals(argName)
+                    || SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_UID.equals(argName);
+        }
+
+        private DataTypeFactory createDataTypeFactory() {
+            return new TestHarnessDataTypeFactory();
+        }
+
+        private ArgumentInfo buildArgumentInfo(StaticArgument staticArg) {
+
+            String name = staticArg.getName();
+            ArgumentTrait primaryTrait = extractPrimaryTrait(staticArg.getTraits());
+
+            DataType dataType;
+            if (primaryTrait == ArgumentTrait.SCALAR) {
+                Optional<DataType> dataTypeOpt = staticArg.getDataType();
+                if (dataTypeOpt.isPresent()) {
+                    dataType = dataTypeOpt.get();
+                } else {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "Cannot determine data type for scalar argument '%s'", name));
+                }
+            } else {
+                // For table arguments, check both annotation and builder config
+                Optional<DataType> annotationTypeOpt = staticArg.getDataType();
+                TableArgumentConfiguration config = tableArgs.get(name);
+
+                if (annotationTypeOpt.isPresent()
+                        && config != null
+                        && config.explicitType != null) {
+                    // Both specified - validate they match
+                    DataTypeFactory factory = createDataTypeFactory();
+                    DataType builderType = factory.createDataType(config.explicitType);
+                    DataType annotationType = annotationTypeOpt.get();
+
+                    if (!annotationType.equals(builderType)) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Type mismatch for table argument '%s': "
+                                                + "annotation declares type %s but builder declares type %s. "
+                                                + "Use either @ArgumentHint(type = ...) OR .withTableArgument(...), not both.",
+                                        name, annotationType, builderType));
+                    }
+                    dataType = annotationType;
+                } else if (annotationTypeOpt.isPresent()) {
+                    dataType = annotationTypeOpt.get();
+                } else if (config != null && config.explicitType != null) {
+                    DataTypeFactory factory = createDataTypeFactory();
+                    dataType = factory.createDataType(config.explicitType);
+                } else {
+                    // Try to infer from Java parameter class (for structured types)
+                    Optional<Class<?>> conversionClassOpt = staticArg.getConversionClass();
+                    if (conversionClassOpt.isPresent()) {
+                        DataTypeFactory factory = createDataTypeFactory();
+                        dataType = factory.createDataType(conversionClassOpt.get());
+                    } else {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Table argument '%s' requires explicit type configuration. "
+                                                + "Use @ArgumentHint(type = @DataTypeHint(\"ROW<...>\")) or "
+                                                + ".withTableArgument(\"%s\", DataTypes.of(\"ROW<...>\"))",
+                                        name, name));
+                    }
+                }
+            }
+
+            String[] partitionColumnNames = null;
+            if (primaryTrait == ArgumentTrait.SET_SEMANTIC_TABLE) {
+                boolean hasOptionalPartitionBy =
+                        staticArg.getTraits().contains(StaticArgumentTrait.OPTIONAL_PARTITION_BY);
+                partitionColumnNames =
+                        extractAndValidatePartitionColumns(name, dataType, hasOptionalPartitionBy);
+            }
+
+            boolean hasPassColumnsThrough =
+                    staticArg.getTraits().contains(StaticArgumentTrait.PASS_COLUMNS_THROUGH);
+
+            return new ArgumentInfo(
+                    name, dataType, primaryTrait, partitionColumnNames, hasPassColumnsThrough);
+        }
+
+        private ArgumentTrait extractPrimaryTrait(EnumSet<StaticArgumentTrait> staticTraits) {
+            if (staticTraits.contains(StaticArgumentTrait.SCALAR)) {
+                return ArgumentTrait.SCALAR;
+            }
+            if (staticTraits.contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)) {
+                return ArgumentTrait.ROW_SEMANTIC_TABLE;
+            }
+            if (staticTraits.contains(StaticArgumentTrait.SET_SEMANTIC_TABLE)) {
+                return ArgumentTrait.SET_SEMANTIC_TABLE;
+            }
+            return ArgumentTrait.SCALAR;
+        }
+
+        private String[] extractAndValidatePartitionColumns(
+                String name, DataType dataType, boolean isOptionalPartitionBy) {
+            PartitionConfiguration config = partitionConfigs.get(name);
+            if (config == null) {
+                if (isOptionalPartitionBy) {
+                    return null;
+                }
+                throw new IllegalStateException(
+                        String.format(
+                                "No partition configuration found for table argument '%s'. "
+                                        + "Use withPartitionBy(\"%s\", ...) to configure partitioning.",
+                                name, name));
+            }
+
+            LogicalType logicalType = dataType.getLogicalType();
+            List<String> fieldNames = new ArrayList<>();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                for (RowType.RowField field : rowType.getFields()) {
+                    fieldNames.add(field.getName());
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    fieldNames.add(attr.getName());
+                }
+            } else {
+                throw new IllegalStateException(
+                        String.format(
+                                "Unsupported data type for partitioning: %s. "
+                                        + "Only Row and structured types (POJOs) support partitioning.",
+                                dataType));
+            }
+
+            for (String columnName : config.columnNames) {
+                if (!fieldNames.contains(columnName)) {
+                    throw new IllegalArgumentException(
+                            "Partition column '"
+                                    + columnName
+                                    + "' not found. "
+                                    + "Available columns: "
+                                    + fieldNames);
+                }
+            }
+            return config.columnNames;
+        }
+
+        private void validateArgumentConfiguration(List<ArgumentInfo> arguments) {
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    if (!scalarArgs.containsKey(arg.name)) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Missing required scalar argument '%s'. "
+                                                + "Use .withScalarArgument(\"%s\", ...)",
+                                        arg.name, arg.name));
+                    }
+                } else {
+                    // For table arguments: builder config is optional if type comes from annotation
+                    boolean hasBuilderConfig = tableArgs.containsKey(arg.name);
+                    boolean hasInlineType = arg.dataType != null;
+
+                    if (!hasBuilderConfig && !hasInlineType) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Missing required table argument '%s'. "
+                                                + "Either specify @ArgumentHint(type = @DataTypeHint(...)) "
+                                                + "or use .withTableArgument(\"%s\", ...)",
+                                        arg.name, arg.name));
+                    }
+                }
+            }
+
+            Set<String> validNames = new HashSet<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    validNames.add(arg.name);
+                }
+            }
+
+            for (String configuredScalar : scalarArgs.keySet()) {
+                if (!validNames.contains(configuredScalar)) {
+                    throw new IllegalStateException(
+                            "Unknown scalar argument: '"
+                                    + configuredScalar
+                                    + "'. Not found in PTF signature.");
+                }
+            }
+
+            for (String configuredTable : tableArgs.keySet()) {
+                if (!validNames.contains(configuredTable)) {
+                    throw new IllegalStateException(
+                            "Unknown table argument: '"
+                                    + configuredTable
+                                    + "'. Not found in PTF signature.");
+                }
+            }
+        }
+
+        private ProcessTableFunction<OUT> instantiateFunction() throws IllegalArgumentException {
+            try {
+                return functionClass.getDeclaredConstructor().newInstance();
+            } catch (NoSuchMethodException e) {
+                throw new IllegalArgumentException(
+                        "PTF class must have a no-arg constructor: " + functionClass.getName(), e);
+            } catch (Exception e) {
+                throw new IllegalArgumentException(
+                        "Failed to instantiate PTF: " + functionClass.getName(), e);
+            }
+        }
+    }
+
+    /**
+     * Metadata for a single argument extracted from type inference.
+     *
+     * <p>Represents validated argument information combining PTF signature, type inference results,
+     * and builder configuration.
+     *
+     * <p>Position in eval() signature is implicit from the list order.
+     */
+    private static class ArgumentInfo {
+        final String name;
+        final DataType dataType;
+        final String[] partitionColumnNames; // nullable - only for SET_SEMANTIC_TABLE
+        final boolean isScalar;
+        final boolean isTableArgument;
+        final boolean isSetSemantic;
+        final boolean hasPassColumnsThrough;
+
+        ArgumentInfo(
+                String name,
+                DataType dataType,
+                ArgumentTrait primaryTrait,
+                String[] partitionColumnNames,
+                boolean hasPassColumnsThrough) {
+            this.name = name;
+            this.dataType = dataType;
+            this.partitionColumnNames = partitionColumnNames;
+            this.isScalar = (primaryTrait == ArgumentTrait.SCALAR);
+            this.isTableArgument = (primaryTrait != ArgumentTrait.SCALAR);
+            this.isSetSemantic = (primaryTrait == ArgumentTrait.SET_SEMANTIC_TABLE);
+            this.hasPassColumnsThrough = hasPassColumnsThrough;
+        }
+    }
+
+    private static class TableArgumentConfiguration {
+        AbstractDataType<?> explicitType; // from withTableArgument

Review Comment:
   ```suggestion
           final AbstractDataType<?> explicitType;
           
           TableArgumentConfiguration(AbstractDataType<?> explicitType) {
             this.explicitType = explicitType;
           }
   ```
   make final and initialize with constructor?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);

Review Comment:
   Is this needed? 
   IIUC, it shouldn't be possible to set the collector context for a PTF without table args (all `processElement()` calls should fail and the collector doesn't have an initial context).



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {

Review Comment:
   shouldn't this always be the case if `!hasTableArguments`?
   
   I think we would need fewer checks if we derive all these properties from `arguments` in the constructor because this would guarantee consistency of the internal properties of the harness.



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {

Review Comment:
   does it make sense to catch an `IllegalArgumentException` here (same as suggested above)?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {

Review Comment:
   should we also catch `IllegalArgumentException()` which would be thrown if the argument types are not matching the signature of the `eval()` method?
   Can we improve the error message in that case  or is it already good enough?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",

Review Comment:
   Provide all `eval()` args including scalar and nulls for inactive table inputs?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);

Review Comment:
   Does it make sense to had the arg vals here as well?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            LogicalType logicalType = dataType.getLogicalType();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                int index = 0;
+                for (RowType.RowField field : rowType.getFields()) {
+                    if (field.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                int index = 0;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    if (attr.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();

Review Comment:
   IIUC, the order in which the args are added to the builder does not matter.
   Could we use a plain `HashMap` instead of `LinkedHashMap`?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            LogicalType logicalType = dataType.getLogicalType();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                int index = 0;
+                for (RowType.RowField field : rowType.getFields()) {
+                    if (field.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                int index = 0;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    if (attr.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }

Review Comment:
   Move this into a helper function?
   This logic is called several times.



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls

Review Comment:
   Curious why it is done this way? All table inputs need to have the same key types / values if rows are processed in a keyed context. So why having different fields for the same key from different input tables? 🤔 



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            LogicalType logicalType = dataType.getLogicalType();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                int index = 0;
+                for (RowType.RowField field : rowType.getFields()) {
+                    if (field.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                int index = 0;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    if (attr.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a table argument without an explicit schema.
+         *
+         * <p>Use this for structured type arguments where the type can be inferred from the PTF's
+         * eval() signature. For Row arguments, use {@link #withTableArgument(String,
+         * AbstractDataType)} with an explicit schema.
+         *
+         * @param argumentName The table argument name
+         */
+        public Builder<OUT> withTableArgument(String argumentName) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName) || tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException("Argument already configured: " + argumentName);
+            }
+
+            ScalarArgumentConfiguration config = new ScalarArgumentConfiguration(value);
+            scalarArgs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Partitioning
+        // ---------------------------------------------------------------------
+
+        /**
+         * Specifies partition columns for a set semantic table.
+         *
+         * @param argumentName The table argument name
+         * @param columnNames The partition column names
+         * @return This builder
+         */
+        public Builder<OUT> withPartitionBy(String argumentName, String... columnNames) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(columnNames, "columnNames must not be null");
+            checkArgument(columnNames.length > 0, "Must specify at least one column");
+
+            if (partitionConfigs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Partition config already exists for: " + argumentName);
+            }
+
+            PartitionConfiguration config = new PartitionConfiguration(columnNames);
+            partitionConfigs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Build
+        // ---------------------------------------------------------------------
+
+        /**
+         * Builds the test harness.
+         *
+         * <p>This instantiates the PTF, validates configuration via type inference, creates the
+         * FunctionContext, and opens the function.
+         *
+         * @return The configured test harness
+         * @throws Exception If instantiation or opening fails
+         */
+        public ProcessTableFunctionTestHarness<OUT> build() throws Exception {
+            ProcessTableFunction<OUT> function = instantiateFunction();
+
+            List<ArgumentInfo> arguments = extractAndValidateTypeInference(function);
+
+            FunctionContext functionContext =
+                    new FunctionContext(null, Thread.currentThread().getContextClassLoader(), null);
+
+            Method evalMethod = findEvalMethod();
+
+            validateEvalMethodSupported(evalMethod, arguments);
+            validatePartitionConsistency(arguments);
+
+            // In cases where PTFs have only a single table argument, set it as a default
+            // and mark as a single table function so that processElement without specifying
+            // a table argument can be used.
+            String defaultTableArg = null;
+            boolean isSingleTableFunction = false;
+
+            List<ArgumentInfo> tableArguments = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    tableArguments.add(arg);
+                }
+            }
+
+            if (tableArguments.size() == 1) {
+                defaultTableArg = tableArguments.get(0).name;
+                isSingleTableFunction = true;
+            }
+
+            Map<String, DataStructureConverter<Object, Object>> inputConverters = new HashMap<>();
+            Map<String, DataStructureConverter<Object, Object>> outputConverters = new HashMap<>();
+            createConverters(arguments, inputConverters, outputConverters);
+
+            Map<String, ArgumentInfo> argumentsByName = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    argumentsByName.put(arg.name, arg);
+                }
+            }

Review Comment:
   Move into harness constructor?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            LogicalType logicalType = dataType.getLogicalType();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                int index = 0;
+                for (RowType.RowField field : rowType.getFields()) {
+                    if (field.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                int index = 0;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    if (attr.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a table argument without an explicit schema.
+         *
+         * <p>Use this for structured type arguments where the type can be inferred from the PTF's
+         * eval() signature. For Row arguments, use {@link #withTableArgument(String,
+         * AbstractDataType)} with an explicit schema.
+         *
+         * @param argumentName The table argument name
+         */
+        public Builder<OUT> withTableArgument(String argumentName) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName) || tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException("Argument already configured: " + argumentName);
+            }
+
+            ScalarArgumentConfiguration config = new ScalarArgumentConfiguration(value);
+            scalarArgs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Partitioning
+        // ---------------------------------------------------------------------
+
+        /**
+         * Specifies partition columns for a set semantic table.
+         *
+         * @param argumentName The table argument name
+         * @param columnNames The partition column names
+         * @return This builder
+         */
+        public Builder<OUT> withPartitionBy(String argumentName, String... columnNames) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(columnNames, "columnNames must not be null");
+            checkArgument(columnNames.length > 0, "Must specify at least one column");
+
+            if (partitionConfigs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Partition config already exists for: " + argumentName);
+            }
+
+            PartitionConfiguration config = new PartitionConfiguration(columnNames);
+            partitionConfigs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Build
+        // ---------------------------------------------------------------------
+
+        /**
+         * Builds the test harness.
+         *
+         * <p>This instantiates the PTF, validates configuration via type inference, creates the
+         * FunctionContext, and opens the function.
+         *
+         * @return The configured test harness
+         * @throws Exception If instantiation or opening fails
+         */
+        public ProcessTableFunctionTestHarness<OUT> build() throws Exception {
+            ProcessTableFunction<OUT> function = instantiateFunction();
+
+            List<ArgumentInfo> arguments = extractAndValidateTypeInference(function);
+
+            FunctionContext functionContext =
+                    new FunctionContext(null, Thread.currentThread().getContextClassLoader(), null);
+
+            Method evalMethod = findEvalMethod();
+
+            validateEvalMethodSupported(evalMethod, arguments);
+            validatePartitionConsistency(arguments);
+
+            // In cases where PTFs have only a single table argument, set it as a default
+            // and mark as a single table function so that processElement without specifying
+            // a table argument can be used.
+            String defaultTableArg = null;
+            boolean isSingleTableFunction = false;
+
+            List<ArgumentInfo> tableArguments = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    tableArguments.add(arg);
+                }
+            }
+
+            if (tableArguments.size() == 1) {
+                defaultTableArg = tableArguments.get(0).name;
+                isSingleTableFunction = true;
+            }
+
+            Map<String, DataStructureConverter<Object, Object>> inputConverters = new HashMap<>();
+            Map<String, DataStructureConverter<Object, Object>> outputConverters = new HashMap<>();
+            createConverters(arguments, inputConverters, outputConverters);
+
+            Map<String, ArgumentInfo> argumentsByName = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    argumentsByName.put(arg.name, arg);
+                }
+            }
+
+            return new ProcessTableFunctionTestHarness<>(
+                    function,
+                    functionContext,
+                    defaultTableArg,
+                    evalMethod,
+                    arguments,
+                    argumentsByName,
+                    isSingleTableFunction,
+                    extractScalarValues(arguments),
+                    inputConverters,
+                    outputConverters);
+        }
+
+        /** Extracts scalar values from configs, creating a map keyed by argument name. */
+        private Map<String, Object> extractScalarValues(List<ArgumentInfo> arguments) {
+            Map<String, Object> values = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    ScalarArgumentConfiguration config = scalarArgs.get(arg.name);
+                    if (config != null) {
+                        values.put(arg.name, config.value);
+                    }
+                }
+            }
+            return values;
+        }
+
+        /**
+         * Creates and initializes data structure converters for all table arguments.
+         *
+         * <p>For Row types, both input and output converters are the same (between Row and
+         * RowData).
+         *
+         * <p>For structured types, input converter uses Row types (Row to RowData), and the output
+         * converter uses the structured type.
+         */
+        private void createConverters(
+                List<ArgumentInfo> arguments,
+                Map<String, DataStructureConverter<Object, Object>> inputConverters,
+                Map<String, DataStructureConverter<Object, Object>> outputConverters) {
+            ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    String converterKey = arg.name;
+
+                    LogicalType logicalType = arg.dataType.getLogicalType();
+                    boolean isStructuredType =
+                            logicalType instanceof StructuredType
+                                    && ((StructuredType) logicalType)
+                                            .getImplementationClass()
+                                            .isPresent();
+
+                    if (isStructuredType) {
+                        StructuredType structuredType = (StructuredType) logicalType;
+                        List<RowType.RowField> rowFields = new ArrayList<>();
+                        for (StructuredType.StructuredAttribute attr :
+                                structuredType.getAttributes()) {
+                            rowFields.add(new RowType.RowField(attr.getName(), attr.getType()));
+                        }
+                        RowType rowType = new RowType(logicalType.isNullable(), rowFields);
+                        DataType rowDataType = TypeConversions.fromLogicalToDataType(rowType);
+
+                        DataStructureConverter<Object, Object> inputConverter =
+                                DataStructureConverters.getConverter(rowDataType);
+                        inputConverter.open(classLoader);
+
+                        DataStructureConverter<Object, Object> outputConverter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        outputConverter.open(classLoader);
+
+                        inputConverters.put(converterKey, inputConverter);
+                        outputConverters.put(converterKey, outputConverter);
+                    } else {
+                        DataStructureConverter<Object, Object> converter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        converter.open(classLoader);
+
+                        inputConverters.put(converterKey, converter);
+                        outputConverters.put(converterKey, converter);
+                    }
+                }
+            }
+        }
+
+        private Method findEvalMethod() throws NoSuchMethodException {
+            Method[] methods = functionClass.getMethods();
+            Method evalMethod = null;
+            int evalMethodCount = 0;
+
+            for (Method method : methods) {
+                if (method.getName().equals("eval")) {
+                    evalMethod = method;
+                    evalMethodCount++;
+                }
+            }
+
+            if (evalMethodCount == 0) {
+                throw new NoSuchMethodException(
+                        "No eval() method found in " + functionClass.getSimpleName());
+            } else if (evalMethodCount > 1) {
+                throw new IllegalStateException(
+                        "Multiple eval() methods found in "
+                                + functionClass.getSimpleName()
+                                + ". ProcessTableFunction must have exactly one eval() method.");
+            } else {
+                return evalMethod;
+            }
+        }
+
+        /**
+         * Validates that the eval() method doesn't use unsupported features. Temporary, until state
+         * and context is supported.
+         */
+        private void validateEvalMethodSupported(Method evalMethod, List<ArgumentInfo> arguments) {
+            Parameter[] parameters = evalMethod.getParameters();
+
+            for (int i = 0; i < parameters.length; i++) {
+                Parameter param = parameters[i];
+                Class<?> paramType = param.getType();
+
+                if (ProcessTableFunction.Context.class.isAssignableFrom(paramType)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support Context parameters. "
+                                            + "Found Context parameter at position %d in eval() method. ",
+                                    i));
+                }
+
+                if (param.isAnnotationPresent(StateHint.class)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support state parameters. "
+                                            + "Found @StateHint parameter at position %d in eval() method. ",
+                                    i));
+                }
+            }
+
+            // Parameter count should also match our arguments list
+            if (parameters.length != arguments.size()) {
+                throw new IllegalStateException(
+                        String.format(
+                                "Parameter count mismatch: eval() has %d parameters but only %d arguments were extracted. "
+                                        + "This may indicate missing @ArgumentHint annotations.",
+                                parameters.length, arguments.size()));
+            }
+        }
+
+        /**
+         * Validates that all SET_SEMANTIC_TABLE arguments with partitioning use consistent
+         * partitioning. All such arguments must have the same number of partition columns with
+         * matching data types.
+         */
+        private void validatePartitionConsistency(List<ArgumentInfo> arguments) {
+            List<ArgumentInfo> partitionedTables = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    partitionedTables.add(arg);
+                }
+            }
+
+            if (partitionedTables.size() <= 1) {
+                return;
+            }
+
+            ArgumentInfo first = partitionedTables.get(0);
+            int expectedPartitionColumnCount = first.partitionColumnNames.length;
+
+            for (int i = 1; i < partitionedTables.size(); i++) {
+                ArgumentInfo current = partitionedTables.get(i);
+
+                if (current.partitionColumnNames.length != expectedPartitionColumnCount) {
+                    throw new IllegalArgumentException(
+                            String.format(
+                                    "Inconsistent partitioning: Table argument '%s' has %d partition column(s), "
+                                            + "but table argument '%s' has %d partition column(s). "
+                                            + "All SET_SEMANTIC_TABLE arguments must use consistent partitioning "
+                                            + "(same number of columns and matching data types).",
+                                    first.name,
+                                    expectedPartitionColumnCount,
+                                    current.name,
+                                    current.partitionColumnNames.length));
+                }
+
+                // Check that partition column types match
+                for (int colIdx = 0; colIdx < expectedPartitionColumnCount; colIdx++) {
+                    String firstColName = first.partitionColumnNames[colIdx];
+                    String currentColName = current.partitionColumnNames[colIdx];
+                    DataType firstColType = extractPartitionColumnType(first, firstColName);
+                    DataType currentColType = extractPartitionColumnType(current, currentColName);
+
+                    if (!firstColType.getLogicalType().equals(currentColType.getLogicalType())) {
+                        throw new IllegalArgumentException(
+                                String.format(
+                                        "Inconsistent partitioning: Partition column '%s' of table argument '%s' "
+                                                + "has type %s, but partition column '%s' of table argument '%s' "
+                                                + "has type %s. All SET_SEMANTIC_TABLE arguments must use "
+                                                + "consistent partitioning (same number of columns and matching data types).",
+                                        firstColName,
+                                        first.name,
+                                        firstColType,
+                                        currentColName,
+                                        current.name,
+                                        currentColType));
+                    }
+                }
+            }
+        }
+
+        private DataType extractPartitionColumnType(ArgumentInfo arg, String columnName) {
+            if (arg.dataType instanceof FieldsDataType) {
+                FieldsDataType fieldsDataType = (FieldsDataType) arg.dataType;
+                LogicalType logicalType = fieldsDataType.getLogicalType();
+                List<DataType> fieldDataTypes = fieldsDataType.getChildren();
+
+                if (logicalType instanceof RowType) {
+                    RowType rowType = (RowType) logicalType;
+                    int fieldIndex = 0;
+                    for (RowType.RowField field : rowType.getFields()) {
+                        if (field.getName().equals(columnName)) {
+                            return fieldDataTypes.get(fieldIndex);
+                        }
+                        fieldIndex++;
+                    }
+                } else if (logicalType instanceof StructuredType) {
+                    StructuredType structuredType = (StructuredType) logicalType;
+                    int attrIndex = 0;
+                    for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                        if (attr.getName().equals(columnName)) {
+                            return fieldDataTypes.get(attrIndex);
+                        }
+                        attrIndex++;
+                    }
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format(
+                            "Cannot extract data type for partition column '%s' of argument '%s'",
+                            columnName, arg.name));
+        }
+
+        // ---------------------------------------------------------------------
+        // Type Inference
+        // ---------------------------------------------------------------------
+
+        /**
+         * Extracts type inference from the PTF and validates builder configuration.
+         *
+         * <p>Uses SystemTypeInference to validate things like reserved argument names, multiple
+         * table argument rules, static argument trait validation, etc.
+         */
+        private List<ArgumentInfo> extractAndValidateTypeInference(
+                ProcessTableFunction<OUT> function) {
+
+            DataTypeFactory dataTypeFactory = createDataTypeFactory();
+            TypeInference baseTypeInference = function.getTypeInference(dataTypeFactory);
+            TypeInference systemTypeInference =
+                    SystemTypeInference.of(FunctionKind.PROCESS_TABLE, baseTypeInference);
+
+            Optional<List<StaticArgument>> staticArgsOpt = systemTypeInference.getStaticArguments();
+            if (staticArgsOpt.isEmpty()) {
+                throw new IllegalStateException(
+                        "PTF does not provide static argument information. "
+                                + "Ensure @ArgumentHint annotations are present on all eval() parameters.");
+            }
+
+            List<StaticArgument> allArgs = staticArgsOpt.get();
+            List<StaticArgument> userArgs = new ArrayList<>();
+            for (StaticArgument arg : allArgs) {
+                if (!isSystemArgument(arg.getName())) {
+                    userArgs.add(arg);
+                }
+            }
+
+            List<ArgumentInfo> arguments = new ArrayList<>();
+
+            for (StaticArgument staticArg : userArgs) {
+                boolean isScalar = staticArg.getTraits().contains(StaticArgumentTrait.SCALAR);
+                boolean isTableArg =
+                        staticArg.getTraits().contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)
+                                || staticArg
+                                        .getTraits()
+                                        .contains(StaticArgumentTrait.SET_SEMANTIC_TABLE);
+
+                if (isScalar || isTableArg) {
+                    ArgumentInfo argInfo = buildArgumentInfo(staticArg);
+                    arguments.add(argInfo);
+                } else {
+                    throw new IllegalStateException(
+                            "Unknown argument type for StaticArgument. "
+                                    + "Expected SCALAR, ROW_SEMANTIC_TABLE, or SET_SEMANTIC_TABLE trait.");
+                }
+            }
+
+            validateArgumentConfiguration(arguments);
+
+            return arguments;
+        }
+
+        /** Checks if an argument name is a system-reserved argument. */
+        private boolean isSystemArgument(String argName) {
+            return SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_ON_TIME.equals(argName)
+                    || SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_UID.equals(argName);
+        }
+
+        private DataTypeFactory createDataTypeFactory() {
+            return new TestHarnessDataTypeFactory();
+        }
+
+        private ArgumentInfo buildArgumentInfo(StaticArgument staticArg) {
+
+            String name = staticArg.getName();
+            ArgumentTrait primaryTrait = extractPrimaryTrait(staticArg.getTraits());
+
+            DataType dataType;
+            if (primaryTrait == ArgumentTrait.SCALAR) {
+                Optional<DataType> dataTypeOpt = staticArg.getDataType();
+                if (dataTypeOpt.isPresent()) {
+                    dataType = dataTypeOpt.get();
+                } else {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "Cannot determine data type for scalar argument '%s'", name));
+                }
+            } else {
+                // For table arguments, check both annotation and builder config
+                Optional<DataType> annotationTypeOpt = staticArg.getDataType();
+                TableArgumentConfiguration config = tableArgs.get(name);
+
+                if (annotationTypeOpt.isPresent()
+                        && config != null
+                        && config.explicitType != null) {
+                    // Both specified - validate they match
+                    DataTypeFactory factory = createDataTypeFactory();
+                    DataType builderType = factory.createDataType(config.explicitType);
+                    DataType annotationType = annotationTypeOpt.get();
+
+                    if (!annotationType.equals(builderType)) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Type mismatch for table argument '%s': "
+                                                + "annotation declares type %s but builder declares type %s. "
+                                                + "Use either @ArgumentHint(type = ...) OR .withTableArgument(...), not both.",

Review Comment:
   Reword this sentence? The user could use both if they set the correct type.
   Maybe something along the lines of: "You don't need to provide type information to the harness if the PTF explicitly declares it."?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {

Review Comment:
   are pass-through columns and partitioning columns mutually exclusive?
   If yes, do we need to check the argInfos that not both are set?
   If no, wouldn't we need to add the partitioning columns of the other table inputs as well?
   



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            LogicalType logicalType = dataType.getLogicalType();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                int index = 0;
+                for (RowType.RowField field : rowType.getFields()) {
+                    if (field.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                int index = 0;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    if (attr.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a table argument without an explicit schema.
+         *
+         * <p>Use this for structured type arguments where the type can be inferred from the PTF's
+         * eval() signature. For Row arguments, use {@link #withTableArgument(String,
+         * AbstractDataType)} with an explicit schema.
+         *
+         * @param argumentName The table argument name
+         */
+        public Builder<OUT> withTableArgument(String argumentName) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName) || tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException("Argument already configured: " + argumentName);
+            }
+
+            ScalarArgumentConfiguration config = new ScalarArgumentConfiguration(value);
+            scalarArgs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Partitioning
+        // ---------------------------------------------------------------------
+
+        /**
+         * Specifies partition columns for a set semantic table.
+         *
+         * @param argumentName The table argument name
+         * @param columnNames The partition column names
+         * @return This builder
+         */
+        public Builder<OUT> withPartitionBy(String argumentName, String... columnNames) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(columnNames, "columnNames must not be null");
+            checkArgument(columnNames.length > 0, "Must specify at least one column");
+
+            if (partitionConfigs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Partition config already exists for: " + argumentName);
+            }
+
+            PartitionConfiguration config = new PartitionConfiguration(columnNames);
+            partitionConfigs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Build
+        // ---------------------------------------------------------------------
+
+        /**
+         * Builds the test harness.
+         *
+         * <p>This instantiates the PTF, validates configuration via type inference, creates the
+         * FunctionContext, and opens the function.
+         *
+         * @return The configured test harness
+         * @throws Exception If instantiation or opening fails
+         */
+        public ProcessTableFunctionTestHarness<OUT> build() throws Exception {
+            ProcessTableFunction<OUT> function = instantiateFunction();
+
+            List<ArgumentInfo> arguments = extractAndValidateTypeInference(function);
+
+            FunctionContext functionContext =
+                    new FunctionContext(null, Thread.currentThread().getContextClassLoader(), null);
+
+            Method evalMethod = findEvalMethod();
+
+            validateEvalMethodSupported(evalMethod, arguments);
+            validatePartitionConsistency(arguments);
+
+            // In cases where PTFs have only a single table argument, set it as a default
+            // and mark as a single table function so that processElement without specifying
+            // a table argument can be used.
+            String defaultTableArg = null;
+            boolean isSingleTableFunction = false;
+
+            List<ArgumentInfo> tableArguments = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    tableArguments.add(arg);
+                }
+            }
+
+            if (tableArguments.size() == 1) {
+                defaultTableArg = tableArguments.get(0).name;
+                isSingleTableFunction = true;
+            }
+
+            Map<String, DataStructureConverter<Object, Object>> inputConverters = new HashMap<>();
+            Map<String, DataStructureConverter<Object, Object>> outputConverters = new HashMap<>();
+            createConverters(arguments, inputConverters, outputConverters);
+
+            Map<String, ArgumentInfo> argumentsByName = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    argumentsByName.put(arg.name, arg);
+                }
+            }
+
+            return new ProcessTableFunctionTestHarness<>(
+                    function,
+                    functionContext,
+                    defaultTableArg,
+                    evalMethod,
+                    arguments,
+                    argumentsByName,
+                    isSingleTableFunction,
+                    extractScalarValues(arguments),
+                    inputConverters,
+                    outputConverters);
+        }
+
+        /** Extracts scalar values from configs, creating a map keyed by argument name. */
+        private Map<String, Object> extractScalarValues(List<ArgumentInfo> arguments) {
+            Map<String, Object> values = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    ScalarArgumentConfiguration config = scalarArgs.get(arg.name);
+                    if (config != null) {
+                        values.put(arg.name, config.value);
+                    }
+                }
+            }
+            return values;
+        }
+
+        /**
+         * Creates and initializes data structure converters for all table arguments.
+         *
+         * <p>For Row types, both input and output converters are the same (between Row and
+         * RowData).
+         *
+         * <p>For structured types, input converter uses Row types (Row to RowData), and the output
+         * converter uses the structured type.
+         */
+        private void createConverters(
+                List<ArgumentInfo> arguments,
+                Map<String, DataStructureConverter<Object, Object>> inputConverters,
+                Map<String, DataStructureConverter<Object, Object>> outputConverters) {
+            ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    String converterKey = arg.name;
+
+                    LogicalType logicalType = arg.dataType.getLogicalType();
+                    boolean isStructuredType =
+                            logicalType instanceof StructuredType
+                                    && ((StructuredType) logicalType)
+                                            .getImplementationClass()
+                                            .isPresent();
+
+                    if (isStructuredType) {
+                        StructuredType structuredType = (StructuredType) logicalType;
+                        List<RowType.RowField> rowFields = new ArrayList<>();
+                        for (StructuredType.StructuredAttribute attr :
+                                structuredType.getAttributes()) {
+                            rowFields.add(new RowType.RowField(attr.getName(), attr.getType()));
+                        }
+                        RowType rowType = new RowType(logicalType.isNullable(), rowFields);
+                        DataType rowDataType = TypeConversions.fromLogicalToDataType(rowType);
+
+                        DataStructureConverter<Object, Object> inputConverter =
+                                DataStructureConverters.getConverter(rowDataType);
+                        inputConverter.open(classLoader);
+
+                        DataStructureConverter<Object, Object> outputConverter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        outputConverter.open(classLoader);
+
+                        inputConverters.put(converterKey, inputConverter);
+                        outputConverters.put(converterKey, outputConverter);
+                    } else {
+                        DataStructureConverter<Object, Object> converter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        converter.open(classLoader);
+
+                        inputConverters.put(converterKey, converter);
+                        outputConverters.put(converterKey, converter);
+                    }
+                }
+            }
+        }
+
+        private Method findEvalMethod() throws NoSuchMethodException {
+            Method[] methods = functionClass.getMethods();
+            Method evalMethod = null;
+            int evalMethodCount = 0;
+
+            for (Method method : methods) {
+                if (method.getName().equals("eval")) {
+                    evalMethod = method;
+                    evalMethodCount++;
+                }
+            }
+
+            if (evalMethodCount == 0) {
+                throw new NoSuchMethodException(
+                        "No eval() method found in " + functionClass.getSimpleName());
+            } else if (evalMethodCount > 1) {
+                throw new IllegalStateException(
+                        "Multiple eval() methods found in "
+                                + functionClass.getSimpleName()
+                                + ". ProcessTableFunction must have exactly one eval() method.");
+            } else {
+                return evalMethod;
+            }
+        }
+
+        /**
+         * Validates that the eval() method doesn't use unsupported features. Temporary, until state
+         * and context is supported.
+         */
+        private void validateEvalMethodSupported(Method evalMethod, List<ArgumentInfo> arguments) {
+            Parameter[] parameters = evalMethod.getParameters();
+
+            for (int i = 0; i < parameters.length; i++) {
+                Parameter param = parameters[i];
+                Class<?> paramType = param.getType();
+
+                if (ProcessTableFunction.Context.class.isAssignableFrom(paramType)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support Context parameters. "
+                                            + "Found Context parameter at position %d in eval() method. ",
+                                    i));
+                }
+
+                if (param.isAnnotationPresent(StateHint.class)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support state parameters. "
+                                            + "Found @StateHint parameter at position %d in eval() method. ",
+                                    i));
+                }
+            }
+
+            // Parameter count should also match our arguments list
+            if (parameters.length != arguments.size()) {
+                throw new IllegalStateException(
+                        String.format(
+                                "Parameter count mismatch: eval() has %d parameters but only %d arguments were extracted. "
+                                        + "This may indicate missing @ArgumentHint annotations.",
+                                parameters.length, arguments.size()));
+            }
+        }
+
+        /**
+         * Validates that all SET_SEMANTIC_TABLE arguments with partitioning use consistent
+         * partitioning. All such arguments must have the same number of partition columns with
+         * matching data types.
+         */
+        private void validatePartitionConsistency(List<ArgumentInfo> arguments) {
+            List<ArgumentInfo> partitionedTables = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    partitionedTables.add(arg);
+                }
+            }
+
+            if (partitionedTables.size() <= 1) {
+                return;
+            }
+
+            ArgumentInfo first = partitionedTables.get(0);
+            int expectedPartitionColumnCount = first.partitionColumnNames.length;
+
+            for (int i = 1; i < partitionedTables.size(); i++) {
+                ArgumentInfo current = partitionedTables.get(i);
+
+                if (current.partitionColumnNames.length != expectedPartitionColumnCount) {
+                    throw new IllegalArgumentException(
+                            String.format(
+                                    "Inconsistent partitioning: Table argument '%s' has %d partition column(s), "
+                                            + "but table argument '%s' has %d partition column(s). "
+                                            + "All SET_SEMANTIC_TABLE arguments must use consistent partitioning "
+                                            + "(same number of columns and matching data types).",
+                                    first.name,
+                                    expectedPartitionColumnCount,
+                                    current.name,
+                                    current.partitionColumnNames.length));
+                }
+
+                // Check that partition column types match
+                for (int colIdx = 0; colIdx < expectedPartitionColumnCount; colIdx++) {
+                    String firstColName = first.partitionColumnNames[colIdx];
+                    String currentColName = current.partitionColumnNames[colIdx];
+                    DataType firstColType = extractPartitionColumnType(first, firstColName);
+                    DataType currentColType = extractPartitionColumnType(current, currentColName);
+
+                    if (!firstColType.getLogicalType().equals(currentColType.getLogicalType())) {
+                        throw new IllegalArgumentException(
+                                String.format(
+                                        "Inconsistent partitioning: Partition column '%s' of table argument '%s' "
+                                                + "has type %s, but partition column '%s' of table argument '%s' "
+                                                + "has type %s. All SET_SEMANTIC_TABLE arguments must use "
+                                                + "consistent partitioning (same number of columns and matching data types).",
+                                        firstColName,
+                                        first.name,
+                                        firstColType,
+                                        currentColName,
+                                        current.name,
+                                        currentColType));
+                    }
+                }
+            }
+        }
+
+        private DataType extractPartitionColumnType(ArgumentInfo arg, String columnName) {
+            if (arg.dataType instanceof FieldsDataType) {
+                FieldsDataType fieldsDataType = (FieldsDataType) arg.dataType;
+                LogicalType logicalType = fieldsDataType.getLogicalType();
+                List<DataType> fieldDataTypes = fieldsDataType.getChildren();
+
+                if (logicalType instanceof RowType) {
+                    RowType rowType = (RowType) logicalType;
+                    int fieldIndex = 0;
+                    for (RowType.RowField field : rowType.getFields()) {
+                        if (field.getName().equals(columnName)) {
+                            return fieldDataTypes.get(fieldIndex);
+                        }
+                        fieldIndex++;
+                    }
+                } else if (logicalType instanceof StructuredType) {
+                    StructuredType structuredType = (StructuredType) logicalType;
+                    int attrIndex = 0;
+                    for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                        if (attr.getName().equals(columnName)) {
+                            return fieldDataTypes.get(attrIndex);
+                        }
+                        attrIndex++;
+                    }
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format(
+                            "Cannot extract data type for partition column '%s' of argument '%s'",
+                            columnName, arg.name));
+        }
+
+        // ---------------------------------------------------------------------
+        // Type Inference
+        // ---------------------------------------------------------------------
+
+        /**
+         * Extracts type inference from the PTF and validates builder configuration.
+         *
+         * <p>Uses SystemTypeInference to validate things like reserved argument names, multiple
+         * table argument rules, static argument trait validation, etc.
+         */
+        private List<ArgumentInfo> extractAndValidateTypeInference(
+                ProcessTableFunction<OUT> function) {
+
+            DataTypeFactory dataTypeFactory = createDataTypeFactory();
+            TypeInference baseTypeInference = function.getTypeInference(dataTypeFactory);
+            TypeInference systemTypeInference =
+                    SystemTypeInference.of(FunctionKind.PROCESS_TABLE, baseTypeInference);
+
+            Optional<List<StaticArgument>> staticArgsOpt = systemTypeInference.getStaticArguments();
+            if (staticArgsOpt.isEmpty()) {
+                throw new IllegalStateException(
+                        "PTF does not provide static argument information. "
+                                + "Ensure @ArgumentHint annotations are present on all eval() parameters.");
+            }
+
+            List<StaticArgument> allArgs = staticArgsOpt.get();
+            List<StaticArgument> userArgs = new ArrayList<>();
+            for (StaticArgument arg : allArgs) {
+                if (!isSystemArgument(arg.getName())) {
+                    userArgs.add(arg);
+                }
+            }
+
+            List<ArgumentInfo> arguments = new ArrayList<>();
+
+            for (StaticArgument staticArg : userArgs) {
+                boolean isScalar = staticArg.getTraits().contains(StaticArgumentTrait.SCALAR);
+                boolean isTableArg =
+                        staticArg.getTraits().contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)
+                                || staticArg
+                                        .getTraits()
+                                        .contains(StaticArgumentTrait.SET_SEMANTIC_TABLE);
+
+                if (isScalar || isTableArg) {
+                    ArgumentInfo argInfo = buildArgumentInfo(staticArg);
+                    arguments.add(argInfo);
+                } else {
+                    throw new IllegalStateException(
+                            "Unknown argument type for StaticArgument. "
+                                    + "Expected SCALAR, ROW_SEMANTIC_TABLE, or SET_SEMANTIC_TABLE trait.");
+                }
+            }
+
+            validateArgumentConfiguration(arguments);
+
+            return arguments;
+        }
+
+        /** Checks if an argument name is a system-reserved argument. */
+        private boolean isSystemArgument(String argName) {
+            return SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_ON_TIME.equals(argName)
+                    || SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_UID.equals(argName);
+        }
+
+        private DataTypeFactory createDataTypeFactory() {
+            return new TestHarnessDataTypeFactory();
+        }
+
+        private ArgumentInfo buildArgumentInfo(StaticArgument staticArg) {
+
+            String name = staticArg.getName();
+            ArgumentTrait primaryTrait = extractPrimaryTrait(staticArg.getTraits());
+
+            DataType dataType;
+            if (primaryTrait == ArgumentTrait.SCALAR) {
+                Optional<DataType> dataTypeOpt = staticArg.getDataType();
+                if (dataTypeOpt.isPresent()) {
+                    dataType = dataTypeOpt.get();
+                } else {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "Cannot determine data type for scalar argument '%s'", name));
+                }
+            } else {
+                // For table arguments, check both annotation and builder config
+                Optional<DataType> annotationTypeOpt = staticArg.getDataType();
+                TableArgumentConfiguration config = tableArgs.get(name);
+
+                if (annotationTypeOpt.isPresent()
+                        && config != null
+                        && config.explicitType != null) {
+                    // Both specified - validate they match
+                    DataTypeFactory factory = createDataTypeFactory();
+                    DataType builderType = factory.createDataType(config.explicitType);
+                    DataType annotationType = annotationTypeOpt.get();
+
+                    if (!annotationType.equals(builderType)) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Type mismatch for table argument '%s': "
+                                                + "annotation declares type %s but builder declares type %s. "
+                                                + "Use either @ArgumentHint(type = ...) OR .withTableArgument(...), not both.",
+                                        name, annotationType, builderType));
+                    }
+                    dataType = annotationType;
+                } else if (annotationTypeOpt.isPresent()) {
+                    dataType = annotationTypeOpt.get();
+                } else if (config != null && config.explicitType != null) {
+                    DataTypeFactory factory = createDataTypeFactory();
+                    dataType = factory.createDataType(config.explicitType);
+                } else {
+                    // Try to infer from Java parameter class (for structured types)
+                    Optional<Class<?>> conversionClassOpt = staticArg.getConversionClass();
+                    if (conversionClassOpt.isPresent()) {
+                        DataTypeFactory factory = createDataTypeFactory();
+                        dataType = factory.createDataType(conversionClassOpt.get());
+                    } else {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Table argument '%s' requires explicit type configuration. "
+                                                + "Use @ArgumentHint(type = @DataTypeHint(\"ROW<...>\")) or "
+                                                + ".withTableArgument(\"%s\", DataTypes.of(\"ROW<...>\"))",
+                                        name, name));
+                    }
+                }
+            }
+
+            String[] partitionColumnNames = null;
+            if (primaryTrait == ArgumentTrait.SET_SEMANTIC_TABLE) {
+                boolean hasOptionalPartitionBy =
+                        staticArg.getTraits().contains(StaticArgumentTrait.OPTIONAL_PARTITION_BY);
+                partitionColumnNames =
+                        extractAndValidatePartitionColumns(name, dataType, hasOptionalPartitionBy);
+            }
+
+            boolean hasPassColumnsThrough =
+                    staticArg.getTraits().contains(StaticArgumentTrait.PASS_COLUMNS_THROUGH);
+
+            return new ArgumentInfo(
+                    name, dataType, primaryTrait, partitionColumnNames, hasPassColumnsThrough);
+        }
+
+        private ArgumentTrait extractPrimaryTrait(EnumSet<StaticArgumentTrait> staticTraits) {
+            if (staticTraits.contains(StaticArgumentTrait.SCALAR)) {
+                return ArgumentTrait.SCALAR;
+            }
+            if (staticTraits.contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)) {
+                return ArgumentTrait.ROW_SEMANTIC_TABLE;
+            }
+            if (staticTraits.contains(StaticArgumentTrait.SET_SEMANTIC_TABLE)) {
+                return ArgumentTrait.SET_SEMANTIC_TABLE;
+            }

Review Comment:
   it seems that the API allows us to set multiple primary traits.
   Not sure if this would be captured somewhere else when using the test harness.
   If not, we should assert that here.



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            LogicalType logicalType = dataType.getLogicalType();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                int index = 0;
+                for (RowType.RowField field : rowType.getFields()) {
+                    if (field.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                int index = 0;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    if (attr.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a table argument without an explicit schema.
+         *
+         * <p>Use this for structured type arguments where the type can be inferred from the PTF's
+         * eval() signature. For Row arguments, use {@link #withTableArgument(String,
+         * AbstractDataType)} with an explicit schema.
+         *
+         * @param argumentName The table argument name
+         */
+        public Builder<OUT> withTableArgument(String argumentName) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName) || tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException("Argument already configured: " + argumentName);
+            }
+
+            ScalarArgumentConfiguration config = new ScalarArgumentConfiguration(value);
+            scalarArgs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Partitioning
+        // ---------------------------------------------------------------------
+
+        /**
+         * Specifies partition columns for a set semantic table.
+         *
+         * @param argumentName The table argument name
+         * @param columnNames The partition column names
+         * @return This builder
+         */
+        public Builder<OUT> withPartitionBy(String argumentName, String... columnNames) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(columnNames, "columnNames must not be null");
+            checkArgument(columnNames.length > 0, "Must specify at least one column");
+
+            if (partitionConfigs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Partition config already exists for: " + argumentName);
+            }
+
+            PartitionConfiguration config = new PartitionConfiguration(columnNames);
+            partitionConfigs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Build
+        // ---------------------------------------------------------------------
+
+        /**
+         * Builds the test harness.
+         *
+         * <p>This instantiates the PTF, validates configuration via type inference, creates the
+         * FunctionContext, and opens the function.
+         *
+         * @return The configured test harness
+         * @throws Exception If instantiation or opening fails
+         */
+        public ProcessTableFunctionTestHarness<OUT> build() throws Exception {
+            ProcessTableFunction<OUT> function = instantiateFunction();
+
+            List<ArgumentInfo> arguments = extractAndValidateTypeInference(function);
+
+            FunctionContext functionContext =
+                    new FunctionContext(null, Thread.currentThread().getContextClassLoader(), null);
+
+            Method evalMethod = findEvalMethod();
+
+            validateEvalMethodSupported(evalMethod, arguments);
+            validatePartitionConsistency(arguments);
+
+            // In cases where PTFs have only a single table argument, set it as a default
+            // and mark as a single table function so that processElement without specifying
+            // a table argument can be used.
+            String defaultTableArg = null;
+            boolean isSingleTableFunction = false;
+
+            List<ArgumentInfo> tableArguments = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    tableArguments.add(arg);
+                }
+            }
+
+            if (tableArguments.size() == 1) {
+                defaultTableArg = tableArguments.get(0).name;
+                isSingleTableFunction = true;
+            }
+
+            Map<String, DataStructureConverter<Object, Object>> inputConverters = new HashMap<>();
+            Map<String, DataStructureConverter<Object, Object>> outputConverters = new HashMap<>();
+            createConverters(arguments, inputConverters, outputConverters);
+
+            Map<String, ArgumentInfo> argumentsByName = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    argumentsByName.put(arg.name, arg);
+                }
+            }
+
+            return new ProcessTableFunctionTestHarness<>(
+                    function,
+                    functionContext,
+                    defaultTableArg,
+                    evalMethod,
+                    arguments,
+                    argumentsByName,
+                    isSingleTableFunction,
+                    extractScalarValues(arguments),
+                    inputConverters,
+                    outputConverters);
+        }
+
+        /** Extracts scalar values from configs, creating a map keyed by argument name. */
+        private Map<String, Object> extractScalarValues(List<ArgumentInfo> arguments) {
+            Map<String, Object> values = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    ScalarArgumentConfiguration config = scalarArgs.get(arg.name);
+                    if (config != null) {
+                        values.put(arg.name, config.value);
+                    }
+                }
+            }
+            return values;
+        }
+
+        /**
+         * Creates and initializes data structure converters for all table arguments.
+         *
+         * <p>For Row types, both input and output converters are the same (between Row and
+         * RowData).
+         *
+         * <p>For structured types, input converter uses Row types (Row to RowData), and the output
+         * converter uses the structured type.
+         */
+        private void createConverters(
+                List<ArgumentInfo> arguments,
+                Map<String, DataStructureConverter<Object, Object>> inputConverters,
+                Map<String, DataStructureConverter<Object, Object>> outputConverters) {
+            ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    String converterKey = arg.name;
+
+                    LogicalType logicalType = arg.dataType.getLogicalType();
+                    boolean isStructuredType =
+                            logicalType instanceof StructuredType
+                                    && ((StructuredType) logicalType)
+                                            .getImplementationClass()
+                                            .isPresent();
+
+                    if (isStructuredType) {
+                        StructuredType structuredType = (StructuredType) logicalType;
+                        List<RowType.RowField> rowFields = new ArrayList<>();
+                        for (StructuredType.StructuredAttribute attr :
+                                structuredType.getAttributes()) {
+                            rowFields.add(new RowType.RowField(attr.getName(), attr.getType()));
+                        }
+                        RowType rowType = new RowType(logicalType.isNullable(), rowFields);
+                        DataType rowDataType = TypeConversions.fromLogicalToDataType(rowType);
+
+                        DataStructureConverter<Object, Object> inputConverter =
+                                DataStructureConverters.getConverter(rowDataType);
+                        inputConverter.open(classLoader);
+
+                        DataStructureConverter<Object, Object> outputConverter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        outputConverter.open(classLoader);
+
+                        inputConverters.put(converterKey, inputConverter);
+                        outputConverters.put(converterKey, outputConverter);
+                    } else {
+                        DataStructureConverter<Object, Object> converter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        converter.open(classLoader);
+
+                        inputConverters.put(converterKey, converter);
+                        outputConverters.put(converterKey, converter);
+                    }
+                }
+            }
+        }
+
+        private Method findEvalMethod() throws NoSuchMethodException {
+            Method[] methods = functionClass.getMethods();
+            Method evalMethod = null;
+            int evalMethodCount = 0;
+
+            for (Method method : methods) {
+                if (method.getName().equals("eval")) {
+                    evalMethod = method;
+                    evalMethodCount++;
+                }
+            }
+
+            if (evalMethodCount == 0) {
+                throw new NoSuchMethodException(
+                        "No eval() method found in " + functionClass.getSimpleName());
+            } else if (evalMethodCount > 1) {
+                throw new IllegalStateException(
+                        "Multiple eval() methods found in "
+                                + functionClass.getSimpleName()
+                                + ". ProcessTableFunction must have exactly one eval() method.");
+            } else {
+                return evalMethod;
+            }
+        }
+
+        /**
+         * Validates that the eval() method doesn't use unsupported features. Temporary, until state
+         * and context is supported.
+         */
+        private void validateEvalMethodSupported(Method evalMethod, List<ArgumentInfo> arguments) {
+            Parameter[] parameters = evalMethod.getParameters();
+
+            for (int i = 0; i < parameters.length; i++) {
+                Parameter param = parameters[i];
+                Class<?> paramType = param.getType();
+
+                if (ProcessTableFunction.Context.class.isAssignableFrom(paramType)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support Context parameters. "
+                                            + "Found Context parameter at position %d in eval() method. ",
+                                    i));
+                }
+
+                if (param.isAnnotationPresent(StateHint.class)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support state parameters. "
+                                            + "Found @StateHint parameter at position %d in eval() method. ",
+                                    i));
+                }
+            }
+
+            // Parameter count should also match our arguments list
+            if (parameters.length != arguments.size()) {
+                throw new IllegalStateException(
+                        String.format(
+                                "Parameter count mismatch: eval() has %d parameters but only %d arguments were extracted. "
+                                        + "This may indicate missing @ArgumentHint annotations.",
+                                parameters.length, arguments.size()));
+            }
+        }
+
+        /**
+         * Validates that all SET_SEMANTIC_TABLE arguments with partitioning use consistent
+         * partitioning. All such arguments must have the same number of partition columns with
+         * matching data types.
+         */
+        private void validatePartitionConsistency(List<ArgumentInfo> arguments) {
+            List<ArgumentInfo> partitionedTables = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    partitionedTables.add(arg);
+                }
+            }
+
+            if (partitionedTables.size() <= 1) {
+                return;
+            }
+
+            ArgumentInfo first = partitionedTables.get(0);
+            int expectedPartitionColumnCount = first.partitionColumnNames.length;
+
+            for (int i = 1; i < partitionedTables.size(); i++) {
+                ArgumentInfo current = partitionedTables.get(i);
+
+                if (current.partitionColumnNames.length != expectedPartitionColumnCount) {
+                    throw new IllegalArgumentException(
+                            String.format(
+                                    "Inconsistent partitioning: Table argument '%s' has %d partition column(s), "
+                                            + "but table argument '%s' has %d partition column(s). "
+                                            + "All SET_SEMANTIC_TABLE arguments must use consistent partitioning "
+                                            + "(same number of columns and matching data types).",
+                                    first.name,
+                                    expectedPartitionColumnCount,
+                                    current.name,
+                                    current.partitionColumnNames.length));
+                }
+
+                // Check that partition column types match
+                for (int colIdx = 0; colIdx < expectedPartitionColumnCount; colIdx++) {
+                    String firstColName = first.partitionColumnNames[colIdx];
+                    String currentColName = current.partitionColumnNames[colIdx];
+                    DataType firstColType = extractPartitionColumnType(first, firstColName);
+                    DataType currentColType = extractPartitionColumnType(current, currentColName);
+
+                    if (!firstColType.getLogicalType().equals(currentColType.getLogicalType())) {
+                        throw new IllegalArgumentException(
+                                String.format(
+                                        "Inconsistent partitioning: Partition column '%s' of table argument '%s' "
+                                                + "has type %s, but partition column '%s' of table argument '%s' "
+                                                + "has type %s. All SET_SEMANTIC_TABLE arguments must use "
+                                                + "consistent partitioning (same number of columns and matching data types).",
+                                        firstColName,
+                                        first.name,
+                                        firstColType,
+                                        currentColName,
+                                        current.name,
+                                        currentColType));
+                    }
+                }
+            }
+        }
+
+        private DataType extractPartitionColumnType(ArgumentInfo arg, String columnName) {
+            if (arg.dataType instanceof FieldsDataType) {
+                FieldsDataType fieldsDataType = (FieldsDataType) arg.dataType;
+                LogicalType logicalType = fieldsDataType.getLogicalType();
+                List<DataType> fieldDataTypes = fieldsDataType.getChildren();
+
+                if (logicalType instanceof RowType) {
+                    RowType rowType = (RowType) logicalType;
+                    int fieldIndex = 0;
+                    for (RowType.RowField field : rowType.getFields()) {
+                        if (field.getName().equals(columnName)) {
+                            return fieldDataTypes.get(fieldIndex);
+                        }
+                        fieldIndex++;
+                    }
+                } else if (logicalType instanceof StructuredType) {
+                    StructuredType structuredType = (StructuredType) logicalType;
+                    int attrIndex = 0;
+                    for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                        if (attr.getName().equals(columnName)) {
+                            return fieldDataTypes.get(attrIndex);
+                        }
+                        attrIndex++;
+                    }
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format(
+                            "Cannot extract data type for partition column '%s' of argument '%s'",
+                            columnName, arg.name));
+        }
+
+        // ---------------------------------------------------------------------
+        // Type Inference
+        // ---------------------------------------------------------------------
+
+        /**
+         * Extracts type inference from the PTF and validates builder configuration.
+         *
+         * <p>Uses SystemTypeInference to validate things like reserved argument names, multiple
+         * table argument rules, static argument trait validation, etc.
+         */
+        private List<ArgumentInfo> extractAndValidateTypeInference(
+                ProcessTableFunction<OUT> function) {
+
+            DataTypeFactory dataTypeFactory = createDataTypeFactory();
+            TypeInference baseTypeInference = function.getTypeInference(dataTypeFactory);
+            TypeInference systemTypeInference =
+                    SystemTypeInference.of(FunctionKind.PROCESS_TABLE, baseTypeInference);
+
+            Optional<List<StaticArgument>> staticArgsOpt = systemTypeInference.getStaticArguments();
+            if (staticArgsOpt.isEmpty()) {
+                throw new IllegalStateException(
+                        "PTF does not provide static argument information. "
+                                + "Ensure @ArgumentHint annotations are present on all eval() parameters.");
+            }
+
+            List<StaticArgument> allArgs = staticArgsOpt.get();
+            List<StaticArgument> userArgs = new ArrayList<>();
+            for (StaticArgument arg : allArgs) {
+                if (!isSystemArgument(arg.getName())) {
+                    userArgs.add(arg);
+                }
+            }
+
+            List<ArgumentInfo> arguments = new ArrayList<>();
+
+            for (StaticArgument staticArg : userArgs) {
+                boolean isScalar = staticArg.getTraits().contains(StaticArgumentTrait.SCALAR);
+                boolean isTableArg =
+                        staticArg.getTraits().contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)
+                                || staticArg
+                                        .getTraits()
+                                        .contains(StaticArgumentTrait.SET_SEMANTIC_TABLE);
+
+                if (isScalar || isTableArg) {
+                    ArgumentInfo argInfo = buildArgumentInfo(staticArg);
+                    arguments.add(argInfo);
+                } else {
+                    throw new IllegalStateException(
+                            "Unknown argument type for StaticArgument. "
+                                    + "Expected SCALAR, ROW_SEMANTIC_TABLE, or SET_SEMANTIC_TABLE trait.");
+                }
+            }
+
+            validateArgumentConfiguration(arguments);
+
+            return arguments;
+        }
+
+        /** Checks if an argument name is a system-reserved argument. */
+        private boolean isSystemArgument(String argName) {
+            return SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_ON_TIME.equals(argName)
+                    || SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_UID.equals(argName);
+        }
+
+        private DataTypeFactory createDataTypeFactory() {
+            return new TestHarnessDataTypeFactory();
+        }
+
+        private ArgumentInfo buildArgumentInfo(StaticArgument staticArg) {
+
+            String name = staticArg.getName();
+            ArgumentTrait primaryTrait = extractPrimaryTrait(staticArg.getTraits());
+
+            DataType dataType;
+            if (primaryTrait == ArgumentTrait.SCALAR) {
+                Optional<DataType> dataTypeOpt = staticArg.getDataType();
+                if (dataTypeOpt.isPresent()) {
+                    dataType = dataTypeOpt.get();
+                } else {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "Cannot determine data type for scalar argument '%s'", name));
+                }
+            } else {
+                // For table arguments, check both annotation and builder config
+                Optional<DataType> annotationTypeOpt = staticArg.getDataType();
+                TableArgumentConfiguration config = tableArgs.get(name);
+
+                if (annotationTypeOpt.isPresent()
+                        && config != null
+                        && config.explicitType != null) {
+                    // Both specified - validate they match
+                    DataTypeFactory factory = createDataTypeFactory();
+                    DataType builderType = factory.createDataType(config.explicitType);
+                    DataType annotationType = annotationTypeOpt.get();
+
+                    if (!annotationType.equals(builderType)) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Type mismatch for table argument '%s': "
+                                                + "annotation declares type %s but builder declares type %s. "
+                                                + "Use either @ArgumentHint(type = ...) OR .withTableArgument(...), not both.",
+                                        name, annotationType, builderType));
+                    }
+                    dataType = annotationType;
+                } else if (annotationTypeOpt.isPresent()) {
+                    dataType = annotationTypeOpt.get();
+                } else if (config != null && config.explicitType != null) {
+                    DataTypeFactory factory = createDataTypeFactory();
+                    dataType = factory.createDataType(config.explicitType);
+                } else {
+                    // Try to infer from Java parameter class (for structured types)
+                    Optional<Class<?>> conversionClassOpt = staticArg.getConversionClass();
+                    if (conversionClassOpt.isPresent()) {
+                        DataTypeFactory factory = createDataTypeFactory();
+                        dataType = factory.createDataType(conversionClassOpt.get());
+                    } else {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Table argument '%s' requires explicit type configuration. "
+                                                + "Use @ArgumentHint(type = @DataTypeHint(\"ROW<...>\")) or "
+                                                + ".withTableArgument(\"%s\", DataTypes.of(\"ROW<...>\"))",
+                                        name, name));
+                    }
+                }
+            }
+
+            String[] partitionColumnNames = null;
+            if (primaryTrait == ArgumentTrait.SET_SEMANTIC_TABLE) {
+                boolean hasOptionalPartitionBy =
+                        staticArg.getTraits().contains(StaticArgumentTrait.OPTIONAL_PARTITION_BY);
+                partitionColumnNames =
+                        extractAndValidatePartitionColumns(name, dataType, hasOptionalPartitionBy);
+            }
+
+            boolean hasPassColumnsThrough =
+                    staticArg.getTraits().contains(StaticArgumentTrait.PASS_COLUMNS_THROUGH);
+
+            return new ArgumentInfo(
+                    name, dataType, primaryTrait, partitionColumnNames, hasPassColumnsThrough);
+        }
+
+        private ArgumentTrait extractPrimaryTrait(EnumSet<StaticArgumentTrait> staticTraits) {
+            if (staticTraits.contains(StaticArgumentTrait.SCALAR)) {
+                return ArgumentTrait.SCALAR;
+            }
+            if (staticTraits.contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)) {
+                return ArgumentTrait.ROW_SEMANTIC_TABLE;
+            }
+            if (staticTraits.contains(StaticArgumentTrait.SET_SEMANTIC_TABLE)) {
+                return ArgumentTrait.SET_SEMANTIC_TABLE;
+            }
+            return ArgumentTrait.SCALAR;
+        }
+
+        private String[] extractAndValidatePartitionColumns(
+                String name, DataType dataType, boolean isOptionalPartitionBy) {
+            PartitionConfiguration config = partitionConfigs.get(name);
+            if (config == null) {
+                if (isOptionalPartitionBy) {
+                    return null;
+                }
+                throw new IllegalStateException(
+                        String.format(
+                                "No partition configuration found for table argument '%s'. "
+                                        + "Use withPartitionBy(\"%s\", ...) to configure partitioning.",
+                                name, name));
+            }
+
+            LogicalType logicalType = dataType.getLogicalType();
+            List<String> fieldNames = new ArrayList<>();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                for (RowType.RowField field : rowType.getFields()) {
+                    fieldNames.add(field.getName());
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    fieldNames.add(attr.getName());
+                }

Review Comment:
   This distinction of `RowType` and `StructuredType` when accessing nested fields is done several times in this file. Can this be factored out into a helper method that returns a list of field names?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls

Review Comment:
   Or is the assumption that different table inputs use different partitionings?
   Is that really possible with PTFs?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            LogicalType logicalType = dataType.getLogicalType();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                int index = 0;
+                for (RowType.RowField field : rowType.getFields()) {
+                    if (field.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                int index = 0;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    if (attr.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a table argument without an explicit schema.
+         *
+         * <p>Use this for structured type arguments where the type can be inferred from the PTF's
+         * eval() signature. For Row arguments, use {@link #withTableArgument(String,
+         * AbstractDataType)} with an explicit schema.
+         *
+         * @param argumentName The table argument name
+         */
+        public Builder<OUT> withTableArgument(String argumentName) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName) || tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException("Argument already configured: " + argumentName);
+            }
+
+            ScalarArgumentConfiguration config = new ScalarArgumentConfiguration(value);
+            scalarArgs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Partitioning
+        // ---------------------------------------------------------------------
+
+        /**
+         * Specifies partition columns for a set semantic table.
+         *
+         * @param argumentName The table argument name
+         * @param columnNames The partition column names
+         * @return This builder
+         */
+        public Builder<OUT> withPartitionBy(String argumentName, String... columnNames) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(columnNames, "columnNames must not be null");
+            checkArgument(columnNames.length > 0, "Must specify at least one column");
+
+            if (partitionConfigs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Partition config already exists for: " + argumentName);
+            }
+
+            PartitionConfiguration config = new PartitionConfiguration(columnNames);
+            partitionConfigs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Build
+        // ---------------------------------------------------------------------
+
+        /**
+         * Builds the test harness.
+         *
+         * <p>This instantiates the PTF, validates configuration via type inference, creates the
+         * FunctionContext, and opens the function.
+         *
+         * @return The configured test harness
+         * @throws Exception If instantiation or opening fails
+         */
+        public ProcessTableFunctionTestHarness<OUT> build() throws Exception {
+            ProcessTableFunction<OUT> function = instantiateFunction();
+
+            List<ArgumentInfo> arguments = extractAndValidateTypeInference(function);
+
+            FunctionContext functionContext =
+                    new FunctionContext(null, Thread.currentThread().getContextClassLoader(), null);
+
+            Method evalMethod = findEvalMethod();
+
+            validateEvalMethodSupported(evalMethod, arguments);
+            validatePartitionConsistency(arguments);
+
+            // In cases where PTFs have only a single table argument, set it as a default
+            // and mark as a single table function so that processElement without specifying
+            // a table argument can be used.
+            String defaultTableArg = null;
+            boolean isSingleTableFunction = false;
+
+            List<ArgumentInfo> tableArguments = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    tableArguments.add(arg);
+                }
+            }
+
+            if (tableArguments.size() == 1) {
+                defaultTableArg = tableArguments.get(0).name;
+                isSingleTableFunction = true;
+            }
+
+            Map<String, DataStructureConverter<Object, Object>> inputConverters = new HashMap<>();
+            Map<String, DataStructureConverter<Object, Object>> outputConverters = new HashMap<>();
+            createConverters(arguments, inputConverters, outputConverters);
+
+            Map<String, ArgumentInfo> argumentsByName = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    argumentsByName.put(arg.name, arg);
+                }
+            }
+
+            return new ProcessTableFunctionTestHarness<>(
+                    function,
+                    functionContext,
+                    defaultTableArg,
+                    evalMethod,
+                    arguments,
+                    argumentsByName,
+                    isSingleTableFunction,
+                    extractScalarValues(arguments),
+                    inputConverters,
+                    outputConverters);
+        }
+
+        /** Extracts scalar values from configs, creating a map keyed by argument name. */
+        private Map<String, Object> extractScalarValues(List<ArgumentInfo> arguments) {
+            Map<String, Object> values = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    ScalarArgumentConfiguration config = scalarArgs.get(arg.name);
+                    if (config != null) {
+                        values.put(arg.name, config.value);
+                    }
+                }
+            }
+            return values;
+        }
+
+        /**
+         * Creates and initializes data structure converters for all table arguments.
+         *
+         * <p>For Row types, both input and output converters are the same (between Row and
+         * RowData).
+         *
+         * <p>For structured types, input converter uses Row types (Row to RowData), and the output
+         * converter uses the structured type.
+         */
+        private void createConverters(
+                List<ArgumentInfo> arguments,
+                Map<String, DataStructureConverter<Object, Object>> inputConverters,
+                Map<String, DataStructureConverter<Object, Object>> outputConverters) {
+            ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    String converterKey = arg.name;
+
+                    LogicalType logicalType = arg.dataType.getLogicalType();
+                    boolean isStructuredType =
+                            logicalType instanceof StructuredType
+                                    && ((StructuredType) logicalType)
+                                            .getImplementationClass()
+                                            .isPresent();
+
+                    if (isStructuredType) {
+                        StructuredType structuredType = (StructuredType) logicalType;
+                        List<RowType.RowField> rowFields = new ArrayList<>();
+                        for (StructuredType.StructuredAttribute attr :
+                                structuredType.getAttributes()) {
+                            rowFields.add(new RowType.RowField(attr.getName(), attr.getType()));
+                        }
+                        RowType rowType = new RowType(logicalType.isNullable(), rowFields);
+                        DataType rowDataType = TypeConversions.fromLogicalToDataType(rowType);
+
+                        DataStructureConverter<Object, Object> inputConverter =
+                                DataStructureConverters.getConverter(rowDataType);
+                        inputConverter.open(classLoader);
+
+                        DataStructureConverter<Object, Object> outputConverter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        outputConverter.open(classLoader);
+
+                        inputConverters.put(converterKey, inputConverter);
+                        outputConverters.put(converterKey, outputConverter);
+                    } else {
+                        DataStructureConverter<Object, Object> converter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        converter.open(classLoader);
+
+                        inputConverters.put(converterKey, converter);
+                        outputConverters.put(converterKey, converter);
+                    }
+                }
+            }
+        }
+
+        private Method findEvalMethod() throws NoSuchMethodException {
+            Method[] methods = functionClass.getMethods();
+            Method evalMethod = null;
+            int evalMethodCount = 0;
+
+            for (Method method : methods) {
+                if (method.getName().equals("eval")) {
+                    evalMethod = method;
+                    evalMethodCount++;
+                }
+            }
+
+            if (evalMethodCount == 0) {
+                throw new NoSuchMethodException(
+                        "No eval() method found in " + functionClass.getSimpleName());
+            } else if (evalMethodCount > 1) {
+                throw new IllegalStateException(
+                        "Multiple eval() methods found in "
+                                + functionClass.getSimpleName()
+                                + ". ProcessTableFunction must have exactly one eval() method.");
+            } else {
+                return evalMethod;
+            }
+        }
+
+        /**
+         * Validates that the eval() method doesn't use unsupported features. Temporary, until state
+         * and context is supported.
+         */
+        private void validateEvalMethodSupported(Method evalMethod, List<ArgumentInfo> arguments) {
+            Parameter[] parameters = evalMethod.getParameters();
+
+            for (int i = 0; i < parameters.length; i++) {
+                Parameter param = parameters[i];
+                Class<?> paramType = param.getType();
+
+                if (ProcessTableFunction.Context.class.isAssignableFrom(paramType)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support Context parameters. "
+                                            + "Found Context parameter at position %d in eval() method. ",
+                                    i));
+                }
+
+                if (param.isAnnotationPresent(StateHint.class)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support state parameters. "
+                                            + "Found @StateHint parameter at position %d in eval() method. ",
+                                    i));
+                }
+            }
+
+            // Parameter count should also match our arguments list
+            if (parameters.length != arguments.size()) {
+                throw new IllegalStateException(
+                        String.format(
+                                "Parameter count mismatch: eval() has %d parameters but only %d arguments were extracted. "
+                                        + "This may indicate missing @ArgumentHint annotations.",
+                                parameters.length, arguments.size()));
+            }

Review Comment:
   Would it make sense to also check if the parameter classes match the argument types?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            LogicalType logicalType = dataType.getLogicalType();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                int index = 0;
+                for (RowType.RowField field : rowType.getFields()) {
+                    if (field.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                int index = 0;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    if (attr.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a table argument without an explicit schema.
+         *
+         * <p>Use this for structured type arguments where the type can be inferred from the PTF's
+         * eval() signature. For Row arguments, use {@link #withTableArgument(String,
+         * AbstractDataType)} with an explicit schema.
+         *
+         * @param argumentName The table argument name
+         */
+        public Builder<OUT> withTableArgument(String argumentName) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName) || tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException("Argument already configured: " + argumentName);
+            }
+
+            ScalarArgumentConfiguration config = new ScalarArgumentConfiguration(value);
+            scalarArgs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Partitioning
+        // ---------------------------------------------------------------------
+
+        /**
+         * Specifies partition columns for a set semantic table.
+         *
+         * @param argumentName The table argument name
+         * @param columnNames The partition column names
+         * @return This builder
+         */
+        public Builder<OUT> withPartitionBy(String argumentName, String... columnNames) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(columnNames, "columnNames must not be null");
+            checkArgument(columnNames.length > 0, "Must specify at least one column");
+
+            if (partitionConfigs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Partition config already exists for: " + argumentName);
+            }
+
+            PartitionConfiguration config = new PartitionConfiguration(columnNames);
+            partitionConfigs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Build
+        // ---------------------------------------------------------------------
+
+        /**
+         * Builds the test harness.
+         *
+         * <p>This instantiates the PTF, validates configuration via type inference, creates the
+         * FunctionContext, and opens the function.
+         *
+         * @return The configured test harness
+         * @throws Exception If instantiation or opening fails
+         */
+        public ProcessTableFunctionTestHarness<OUT> build() throws Exception {
+            ProcessTableFunction<OUT> function = instantiateFunction();
+
+            List<ArgumentInfo> arguments = extractAndValidateTypeInference(function);
+
+            FunctionContext functionContext =
+                    new FunctionContext(null, Thread.currentThread().getContextClassLoader(), null);
+
+            Method evalMethod = findEvalMethod();
+
+            validateEvalMethodSupported(evalMethod, arguments);
+            validatePartitionConsistency(arguments);
+
+            // In cases where PTFs have only a single table argument, set it as a default
+            // and mark as a single table function so that processElement without specifying
+            // a table argument can be used.
+            String defaultTableArg = null;
+            boolean isSingleTableFunction = false;
+
+            List<ArgumentInfo> tableArguments = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    tableArguments.add(arg);
+                }
+            }
+
+            if (tableArguments.size() == 1) {
+                defaultTableArg = tableArguments.get(0).name;
+                isSingleTableFunction = true;
+            }
+
+            Map<String, DataStructureConverter<Object, Object>> inputConverters = new HashMap<>();
+            Map<String, DataStructureConverter<Object, Object>> outputConverters = new HashMap<>();
+            createConverters(arguments, inputConverters, outputConverters);
+
+            Map<String, ArgumentInfo> argumentsByName = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    argumentsByName.put(arg.name, arg);
+                }
+            }
+
+            return new ProcessTableFunctionTestHarness<>(
+                    function,
+                    functionContext,
+                    defaultTableArg,
+                    evalMethod,
+                    arguments,
+                    argumentsByName,
+                    isSingleTableFunction,
+                    extractScalarValues(arguments),
+                    inputConverters,
+                    outputConverters);
+        }
+
+        /** Extracts scalar values from configs, creating a map keyed by argument name. */
+        private Map<String, Object> extractScalarValues(List<ArgumentInfo> arguments) {
+            Map<String, Object> values = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    ScalarArgumentConfiguration config = scalarArgs.get(arg.name);
+                    if (config != null) {
+                        values.put(arg.name, config.value);
+                    }
+                }
+            }
+            return values;
+        }
+
+        /**
+         * Creates and initializes data structure converters for all table arguments.
+         *
+         * <p>For Row types, both input and output converters are the same (between Row and
+         * RowData).
+         *
+         * <p>For structured types, input converter uses Row types (Row to RowData), and the output
+         * converter uses the structured type.
+         */
+        private void createConverters(
+                List<ArgumentInfo> arguments,
+                Map<String, DataStructureConverter<Object, Object>> inputConverters,
+                Map<String, DataStructureConverter<Object, Object>> outputConverters) {
+            ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    String converterKey = arg.name;
+
+                    LogicalType logicalType = arg.dataType.getLogicalType();
+                    boolean isStructuredType =
+                            logicalType instanceof StructuredType
+                                    && ((StructuredType) logicalType)
+                                            .getImplementationClass()
+                                            .isPresent();
+
+                    if (isStructuredType) {
+                        StructuredType structuredType = (StructuredType) logicalType;
+                        List<RowType.RowField> rowFields = new ArrayList<>();
+                        for (StructuredType.StructuredAttribute attr :
+                                structuredType.getAttributes()) {
+                            rowFields.add(new RowType.RowField(attr.getName(), attr.getType()));
+                        }
+                        RowType rowType = new RowType(logicalType.isNullable(), rowFields);
+                        DataType rowDataType = TypeConversions.fromLogicalToDataType(rowType);
+
+                        DataStructureConverter<Object, Object> inputConverter =
+                                DataStructureConverters.getConverter(rowDataType);
+                        inputConverter.open(classLoader);
+
+                        DataStructureConverter<Object, Object> outputConverter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        outputConverter.open(classLoader);
+
+                        inputConverters.put(converterKey, inputConverter);
+                        outputConverters.put(converterKey, outputConverter);
+                    } else {
+                        DataStructureConverter<Object, Object> converter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        converter.open(classLoader);
+
+                        inputConverters.put(converterKey, converter);
+                        outputConverters.put(converterKey, converter);
+                    }
+                }
+            }
+        }
+
+        private Method findEvalMethod() throws NoSuchMethodException {
+            Method[] methods = functionClass.getMethods();
+            Method evalMethod = null;
+            int evalMethodCount = 0;
+
+            for (Method method : methods) {
+                if (method.getName().equals("eval")) {
+                    evalMethod = method;
+                    evalMethodCount++;
+                }
+            }
+
+            if (evalMethodCount == 0) {
+                throw new NoSuchMethodException(
+                        "No eval() method found in " + functionClass.getSimpleName());
+            } else if (evalMethodCount > 1) {
+                throw new IllegalStateException(
+                        "Multiple eval() methods found in "
+                                + functionClass.getSimpleName()
+                                + ". ProcessTableFunction must have exactly one eval() method.");
+            } else {
+                return evalMethod;
+            }
+        }
+
+        /**
+         * Validates that the eval() method doesn't use unsupported features. Temporary, until state
+         * and context is supported.
+         */
+        private void validateEvalMethodSupported(Method evalMethod, List<ArgumentInfo> arguments) {
+            Parameter[] parameters = evalMethod.getParameters();
+
+            for (int i = 0; i < parameters.length; i++) {
+                Parameter param = parameters[i];
+                Class<?> paramType = param.getType();
+
+                if (ProcessTableFunction.Context.class.isAssignableFrom(paramType)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support Context parameters. "
+                                            + "Found Context parameter at position %d in eval() method. ",
+                                    i));
+                }
+
+                if (param.isAnnotationPresent(StateHint.class)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support state parameters. "
+                                            + "Found @StateHint parameter at position %d in eval() method. ",
+                                    i));
+                }
+            }
+
+            // Parameter count should also match our arguments list
+            if (parameters.length != arguments.size()) {
+                throw new IllegalStateException(
+                        String.format(
+                                "Parameter count mismatch: eval() has %d parameters but only %d arguments were extracted. "
+                                        + "This may indicate missing @ArgumentHint annotations.",
+                                parameters.length, arguments.size()));
+            }
+        }
+
+        /**
+         * Validates that all SET_SEMANTIC_TABLE arguments with partitioning use consistent
+         * partitioning. All such arguments must have the same number of partition columns with
+         * matching data types.
+         */
+        private void validatePartitionConsistency(List<ArgumentInfo> arguments) {
+            List<ArgumentInfo> partitionedTables = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    partitionedTables.add(arg);
+                }
+            }
+
+            if (partitionedTables.size() <= 1) {
+                return;
+            }
+
+            ArgumentInfo first = partitionedTables.get(0);
+            int expectedPartitionColumnCount = first.partitionColumnNames.length;
+
+            for (int i = 1; i < partitionedTables.size(); i++) {
+                ArgumentInfo current = partitionedTables.get(i);
+
+                if (current.partitionColumnNames.length != expectedPartitionColumnCount) {
+                    throw new IllegalArgumentException(
+                            String.format(
+                                    "Inconsistent partitioning: Table argument '%s' has %d partition column(s), "
+                                            + "but table argument '%s' has %d partition column(s). "
+                                            + "All SET_SEMANTIC_TABLE arguments must use consistent partitioning "
+                                            + "(same number of columns and matching data types).",
+                                    first.name,
+                                    expectedPartitionColumnCount,
+                                    current.name,
+                                    current.partitionColumnNames.length));
+                }
+
+                // Check that partition column types match
+                for (int colIdx = 0; colIdx < expectedPartitionColumnCount; colIdx++) {
+                    String firstColName = first.partitionColumnNames[colIdx];
+                    String currentColName = current.partitionColumnNames[colIdx];
+                    DataType firstColType = extractPartitionColumnType(first, firstColName);
+                    DataType currentColType = extractPartitionColumnType(current, currentColName);
+
+                    if (!firstColType.getLogicalType().equals(currentColType.getLogicalType())) {
+                        throw new IllegalArgumentException(
+                                String.format(
+                                        "Inconsistent partitioning: Partition column '%s' of table argument '%s' "
+                                                + "has type %s, but partition column '%s' of table argument '%s' "
+                                                + "has type %s. All SET_SEMANTIC_TABLE arguments must use "
+                                                + "consistent partitioning (same number of columns and matching data types).",
+                                        firstColName,
+                                        first.name,
+                                        firstColType,
+                                        currentColName,
+                                        current.name,
+                                        currentColType));
+                    }
+                }
+            }
+        }
+
+        private DataType extractPartitionColumnType(ArgumentInfo arg, String columnName) {
+            if (arg.dataType instanceof FieldsDataType) {
+                FieldsDataType fieldsDataType = (FieldsDataType) arg.dataType;
+                LogicalType logicalType = fieldsDataType.getLogicalType();
+                List<DataType> fieldDataTypes = fieldsDataType.getChildren();
+
+                if (logicalType instanceof RowType) {
+                    RowType rowType = (RowType) logicalType;
+                    int fieldIndex = 0;
+                    for (RowType.RowField field : rowType.getFields()) {
+                        if (field.getName().equals(columnName)) {
+                            return fieldDataTypes.get(fieldIndex);
+                        }
+                        fieldIndex++;
+                    }
+                } else if (logicalType instanceof StructuredType) {
+                    StructuredType structuredType = (StructuredType) logicalType;
+                    int attrIndex = 0;
+                    for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                        if (attr.getName().equals(columnName)) {
+                            return fieldDataTypes.get(attrIndex);
+                        }
+                        attrIndex++;
+                    }
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format(
+                            "Cannot extract data type for partition column '%s' of argument '%s'",
+                            columnName, arg.name));
+        }
+
+        // ---------------------------------------------------------------------
+        // Type Inference
+        // ---------------------------------------------------------------------
+
+        /**
+         * Extracts type inference from the PTF and validates builder configuration.
+         *
+         * <p>Uses SystemTypeInference to validate things like reserved argument names, multiple
+         * table argument rules, static argument trait validation, etc.
+         */
+        private List<ArgumentInfo> extractAndValidateTypeInference(
+                ProcessTableFunction<OUT> function) {
+
+            DataTypeFactory dataTypeFactory = createDataTypeFactory();
+            TypeInference baseTypeInference = function.getTypeInference(dataTypeFactory);
+            TypeInference systemTypeInference =
+                    SystemTypeInference.of(FunctionKind.PROCESS_TABLE, baseTypeInference);
+
+            Optional<List<StaticArgument>> staticArgsOpt = systemTypeInference.getStaticArguments();
+            if (staticArgsOpt.isEmpty()) {
+                throw new IllegalStateException(
+                        "PTF does not provide static argument information. "
+                                + "Ensure @ArgumentHint annotations are present on all eval() parameters.");
+            }
+
+            List<StaticArgument> allArgs = staticArgsOpt.get();
+            List<StaticArgument> userArgs = new ArrayList<>();
+            for (StaticArgument arg : allArgs) {
+                if (!isSystemArgument(arg.getName())) {
+                    userArgs.add(arg);
+                }
+            }
+
+            List<ArgumentInfo> arguments = new ArrayList<>();
+
+            for (StaticArgument staticArg : userArgs) {
+                boolean isScalar = staticArg.getTraits().contains(StaticArgumentTrait.SCALAR);
+                boolean isTableArg =
+                        staticArg.getTraits().contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)
+                                || staticArg
+                                        .getTraits()
+                                        .contains(StaticArgumentTrait.SET_SEMANTIC_TABLE);
+
+                if (isScalar || isTableArg) {
+                    ArgumentInfo argInfo = buildArgumentInfo(staticArg);
+                    arguments.add(argInfo);
+                } else {
+                    throw new IllegalStateException(
+                            "Unknown argument type for StaticArgument. "
+                                    + "Expected SCALAR, ROW_SEMANTIC_TABLE, or SET_SEMANTIC_TABLE trait.");
+                }
+            }
+
+            validateArgumentConfiguration(arguments);
+
+            return arguments;
+        }
+
+        /** Checks if an argument name is a system-reserved argument. */
+        private boolean isSystemArgument(String argName) {
+            return SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_ON_TIME.equals(argName)
+                    || SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_UID.equals(argName);
+        }
+
+        private DataTypeFactory createDataTypeFactory() {
+            return new TestHarnessDataTypeFactory();
+        }
+
+        private ArgumentInfo buildArgumentInfo(StaticArgument staticArg) {
+
+            String name = staticArg.getName();
+            ArgumentTrait primaryTrait = extractPrimaryTrait(staticArg.getTraits());
+
+            DataType dataType;
+            if (primaryTrait == ArgumentTrait.SCALAR) {
+                Optional<DataType> dataTypeOpt = staticArg.getDataType();
+                if (dataTypeOpt.isPresent()) {
+                    dataType = dataTypeOpt.get();
+                } else {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "Cannot determine data type for scalar argument '%s'", name));
+                }
+            } else {
+                // For table arguments, check both annotation and builder config
+                Optional<DataType> annotationTypeOpt = staticArg.getDataType();
+                TableArgumentConfiguration config = tableArgs.get(name);
+
+                if (annotationTypeOpt.isPresent()
+                        && config != null
+                        && config.explicitType != null) {
+                    // Both specified - validate they match
+                    DataTypeFactory factory = createDataTypeFactory();
+                    DataType builderType = factory.createDataType(config.explicitType);
+                    DataType annotationType = annotationTypeOpt.get();
+
+                    if (!annotationType.equals(builderType)) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Type mismatch for table argument '%s': "
+                                                + "annotation declares type %s but builder declares type %s. "
+                                                + "Use either @ArgumentHint(type = ...) OR .withTableArgument(...), not both.",
+                                        name, annotationType, builderType));
+                    }
+                    dataType = annotationType;
+                } else if (annotationTypeOpt.isPresent()) {
+                    dataType = annotationTypeOpt.get();
+                } else if (config != null && config.explicitType != null) {
+                    DataTypeFactory factory = createDataTypeFactory();
+                    dataType = factory.createDataType(config.explicitType);
+                } else {
+                    // Try to infer from Java parameter class (for structured types)
+                    Optional<Class<?>> conversionClassOpt = staticArg.getConversionClass();
+                    if (conversionClassOpt.isPresent()) {
+                        DataTypeFactory factory = createDataTypeFactory();
+                        dataType = factory.createDataType(conversionClassOpt.get());
+                    } else {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Table argument '%s' requires explicit type configuration. "
+                                                + "Use @ArgumentHint(type = @DataTypeHint(\"ROW<...>\")) or "
+                                                + ".withTableArgument(\"%s\", DataTypes.of(\"ROW<...>\"))",
+                                        name, name));
+                    }
+                }
+            }
+
+            String[] partitionColumnNames = null;
+            if (primaryTrait == ArgumentTrait.SET_SEMANTIC_TABLE) {
+                boolean hasOptionalPartitionBy =
+                        staticArg.getTraits().contains(StaticArgumentTrait.OPTIONAL_PARTITION_BY);
+                partitionColumnNames =
+                        extractAndValidatePartitionColumns(name, dataType, hasOptionalPartitionBy);
+            }
+
+            boolean hasPassColumnsThrough =
+                    staticArg.getTraits().contains(StaticArgumentTrait.PASS_COLUMNS_THROUGH);

Review Comment:
   partitioning and pass-through columns seem to be independently handled here, but the output collector of the harness only applies either of them (preferring pass-through cols over partitioning cols).
   Is that on purpose?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            LogicalType logicalType = dataType.getLogicalType();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                int index = 0;
+                for (RowType.RowField field : rowType.getFields()) {
+                    if (field.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                int index = 0;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    if (attr.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a table argument without an explicit schema.
+         *
+         * <p>Use this for structured type arguments where the type can be inferred from the PTF's
+         * eval() signature. For Row arguments, use {@link #withTableArgument(String,
+         * AbstractDataType)} with an explicit schema.
+         *
+         * @param argumentName The table argument name
+         */
+        public Builder<OUT> withTableArgument(String argumentName) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName) || tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException("Argument already configured: " + argumentName);
+            }
+
+            ScalarArgumentConfiguration config = new ScalarArgumentConfiguration(value);
+            scalarArgs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Partitioning
+        // ---------------------------------------------------------------------
+
+        /**
+         * Specifies partition columns for a set semantic table.
+         *
+         * @param argumentName The table argument name
+         * @param columnNames The partition column names
+         * @return This builder
+         */
+        public Builder<OUT> withPartitionBy(String argumentName, String... columnNames) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(columnNames, "columnNames must not be null");
+            checkArgument(columnNames.length > 0, "Must specify at least one column");
+
+            if (partitionConfigs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Partition config already exists for: " + argumentName);
+            }
+
+            PartitionConfiguration config = new PartitionConfiguration(columnNames);
+            partitionConfigs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Build
+        // ---------------------------------------------------------------------
+
+        /**
+         * Builds the test harness.
+         *
+         * <p>This instantiates the PTF, validates configuration via type inference, creates the
+         * FunctionContext, and opens the function.
+         *
+         * @return The configured test harness
+         * @throws Exception If instantiation or opening fails
+         */
+        public ProcessTableFunctionTestHarness<OUT> build() throws Exception {
+            ProcessTableFunction<OUT> function = instantiateFunction();
+
+            List<ArgumentInfo> arguments = extractAndValidateTypeInference(function);
+
+            FunctionContext functionContext =
+                    new FunctionContext(null, Thread.currentThread().getContextClassLoader(), null);
+
+            Method evalMethod = findEvalMethod();
+
+            validateEvalMethodSupported(evalMethod, arguments);
+            validatePartitionConsistency(arguments);
+
+            // In cases where PTFs have only a single table argument, set it as a default
+            // and mark as a single table function so that processElement without specifying
+            // a table argument can be used.
+            String defaultTableArg = null;
+            boolean isSingleTableFunction = false;
+
+            List<ArgumentInfo> tableArguments = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    tableArguments.add(arg);
+                }
+            }
+
+            if (tableArguments.size() == 1) {
+                defaultTableArg = tableArguments.get(0).name;
+                isSingleTableFunction = true;
+            }
+
+            Map<String, DataStructureConverter<Object, Object>> inputConverters = new HashMap<>();
+            Map<String, DataStructureConverter<Object, Object>> outputConverters = new HashMap<>();
+            createConverters(arguments, inputConverters, outputConverters);
+
+            Map<String, ArgumentInfo> argumentsByName = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    argumentsByName.put(arg.name, arg);
+                }
+            }
+
+            return new ProcessTableFunctionTestHarness<>(
+                    function,
+                    functionContext,
+                    defaultTableArg,
+                    evalMethod,
+                    arguments,
+                    argumentsByName,
+                    isSingleTableFunction,
+                    extractScalarValues(arguments),
+                    inputConverters,
+                    outputConverters);
+        }
+
+        /** Extracts scalar values from configs, creating a map keyed by argument name. */
+        private Map<String, Object> extractScalarValues(List<ArgumentInfo> arguments) {
+            Map<String, Object> values = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    ScalarArgumentConfiguration config = scalarArgs.get(arg.name);
+                    if (config != null) {
+                        values.put(arg.name, config.value);
+                    }
+                }
+            }
+            return values;
+        }
+
+        /**
+         * Creates and initializes data structure converters for all table arguments.
+         *
+         * <p>For Row types, both input and output converters are the same (between Row and
+         * RowData).
+         *
+         * <p>For structured types, input converter uses Row types (Row to RowData), and the output
+         * converter uses the structured type.
+         */
+        private void createConverters(
+                List<ArgumentInfo> arguments,
+                Map<String, DataStructureConverter<Object, Object>> inputConverters,
+                Map<String, DataStructureConverter<Object, Object>> outputConverters) {
+            ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    String converterKey = arg.name;
+
+                    LogicalType logicalType = arg.dataType.getLogicalType();
+                    boolean isStructuredType =
+                            logicalType instanceof StructuredType
+                                    && ((StructuredType) logicalType)
+                                            .getImplementationClass()
+                                            .isPresent();
+
+                    if (isStructuredType) {
+                        StructuredType structuredType = (StructuredType) logicalType;
+                        List<RowType.RowField> rowFields = new ArrayList<>();
+                        for (StructuredType.StructuredAttribute attr :
+                                structuredType.getAttributes()) {
+                            rowFields.add(new RowType.RowField(attr.getName(), attr.getType()));
+                        }
+                        RowType rowType = new RowType(logicalType.isNullable(), rowFields);
+                        DataType rowDataType = TypeConversions.fromLogicalToDataType(rowType);
+
+                        DataStructureConverter<Object, Object> inputConverter =
+                                DataStructureConverters.getConverter(rowDataType);
+                        inputConverter.open(classLoader);
+
+                        DataStructureConverter<Object, Object> outputConverter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        outputConverter.open(classLoader);
+
+                        inputConverters.put(converterKey, inputConverter);
+                        outputConverters.put(converterKey, outputConverter);
+                    } else {
+                        DataStructureConverter<Object, Object> converter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        converter.open(classLoader);
+
+                        inputConverters.put(converterKey, converter);
+                        outputConverters.put(converterKey, converter);
+                    }
+                }
+            }
+        }
+
+        private Method findEvalMethod() throws NoSuchMethodException {
+            Method[] methods = functionClass.getMethods();
+            Method evalMethod = null;
+            int evalMethodCount = 0;
+
+            for (Method method : methods) {
+                if (method.getName().equals("eval")) {
+                    evalMethod = method;
+                    evalMethodCount++;
+                }
+            }
+
+            if (evalMethodCount == 0) {
+                throw new NoSuchMethodException(
+                        "No eval() method found in " + functionClass.getSimpleName());
+            } else if (evalMethodCount > 1) {
+                throw new IllegalStateException(
+                        "Multiple eval() methods found in "
+                                + functionClass.getSimpleName()
+                                + ". ProcessTableFunction must have exactly one eval() method.");
+            } else {
+                return evalMethod;
+            }
+        }
+
+        /**
+         * Validates that the eval() method doesn't use unsupported features. Temporary, until state
+         * and context is supported.
+         */
+        private void validateEvalMethodSupported(Method evalMethod, List<ArgumentInfo> arguments) {
+            Parameter[] parameters = evalMethod.getParameters();
+
+            for (int i = 0; i < parameters.length; i++) {
+                Parameter param = parameters[i];
+                Class<?> paramType = param.getType();
+
+                if (ProcessTableFunction.Context.class.isAssignableFrom(paramType)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support Context parameters. "
+                                            + "Found Context parameter at position %d in eval() method. ",
+                                    i));
+                }
+
+                if (param.isAnnotationPresent(StateHint.class)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support state parameters. "
+                                            + "Found @StateHint parameter at position %d in eval() method. ",
+                                    i));
+                }
+            }
+
+            // Parameter count should also match our arguments list
+            if (parameters.length != arguments.size()) {
+                throw new IllegalStateException(
+                        String.format(
+                                "Parameter count mismatch: eval() has %d parameters but only %d arguments were extracted. "
+                                        + "This may indicate missing @ArgumentHint annotations.",
+                                parameters.length, arguments.size()));
+            }
+        }
+
+        /**
+         * Validates that all SET_SEMANTIC_TABLE arguments with partitioning use consistent
+         * partitioning. All such arguments must have the same number of partition columns with
+         * matching data types.
+         */
+        private void validatePartitionConsistency(List<ArgumentInfo> arguments) {
+            List<ArgumentInfo> partitionedTables = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    partitionedTables.add(arg);
+                }
+            }
+
+            if (partitionedTables.size() <= 1) {
+                return;
+            }
+
+            ArgumentInfo first = partitionedTables.get(0);
+            int expectedPartitionColumnCount = first.partitionColumnNames.length;
+
+            for (int i = 1; i < partitionedTables.size(); i++) {
+                ArgumentInfo current = partitionedTables.get(i);
+
+                if (current.partitionColumnNames.length != expectedPartitionColumnCount) {
+                    throw new IllegalArgumentException(
+                            String.format(
+                                    "Inconsistent partitioning: Table argument '%s' has %d partition column(s), "
+                                            + "but table argument '%s' has %d partition column(s). "
+                                            + "All SET_SEMANTIC_TABLE arguments must use consistent partitioning "
+                                            + "(same number of columns and matching data types).",
+                                    first.name,
+                                    expectedPartitionColumnCount,
+                                    current.name,
+                                    current.partitionColumnNames.length));
+                }
+
+                // Check that partition column types match
+                for (int colIdx = 0; colIdx < expectedPartitionColumnCount; colIdx++) {
+                    String firstColName = first.partitionColumnNames[colIdx];
+                    String currentColName = current.partitionColumnNames[colIdx];
+                    DataType firstColType = extractPartitionColumnType(first, firstColName);
+                    DataType currentColType = extractPartitionColumnType(current, currentColName);
+
+                    if (!firstColType.getLogicalType().equals(currentColType.getLogicalType())) {
+                        throw new IllegalArgumentException(
+                                String.format(
+                                        "Inconsistent partitioning: Partition column '%s' of table argument '%s' "
+                                                + "has type %s, but partition column '%s' of table argument '%s' "
+                                                + "has type %s. All SET_SEMANTIC_TABLE arguments must use "
+                                                + "consistent partitioning (same number of columns and matching data types).",
+                                        firstColName,
+                                        first.name,
+                                        firstColType,
+                                        currentColName,
+                                        current.name,
+                                        currentColType));
+                    }
+                }
+            }
+        }
+
+        private DataType extractPartitionColumnType(ArgumentInfo arg, String columnName) {
+            if (arg.dataType instanceof FieldsDataType) {
+                FieldsDataType fieldsDataType = (FieldsDataType) arg.dataType;
+                LogicalType logicalType = fieldsDataType.getLogicalType();
+                List<DataType> fieldDataTypes = fieldsDataType.getChildren();
+
+                if (logicalType instanceof RowType) {
+                    RowType rowType = (RowType) logicalType;
+                    int fieldIndex = 0;
+                    for (RowType.RowField field : rowType.getFields()) {
+                        if (field.getName().equals(columnName)) {
+                            return fieldDataTypes.get(fieldIndex);
+                        }
+                        fieldIndex++;
+                    }
+                } else if (logicalType instanceof StructuredType) {
+                    StructuredType structuredType = (StructuredType) logicalType;
+                    int attrIndex = 0;
+                    for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                        if (attr.getName().equals(columnName)) {
+                            return fieldDataTypes.get(attrIndex);
+                        }
+                        attrIndex++;
+                    }
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format(
+                            "Cannot extract data type for partition column '%s' of argument '%s'",
+                            columnName, arg.name));

Review Comment:
   Use separate error messages for the case no FieldsDataType and the case of not having found the column?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            LogicalType logicalType = dataType.getLogicalType();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                int index = 0;
+                for (RowType.RowField field : rowType.getFields()) {
+                    if (field.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                int index = 0;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    if (attr.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a table argument without an explicit schema.
+         *
+         * <p>Use this for structured type arguments where the type can be inferred from the PTF's
+         * eval() signature. For Row arguments, use {@link #withTableArgument(String,
+         * AbstractDataType)} with an explicit schema.
+         *
+         * @param argumentName The table argument name
+         */
+        public Builder<OUT> withTableArgument(String argumentName) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName) || tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException("Argument already configured: " + argumentName);
+            }
+
+            ScalarArgumentConfiguration config = new ScalarArgumentConfiguration(value);
+            scalarArgs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Partitioning
+        // ---------------------------------------------------------------------
+
+        /**
+         * Specifies partition columns for a set semantic table.
+         *
+         * @param argumentName The table argument name
+         * @param columnNames The partition column names
+         * @return This builder
+         */
+        public Builder<OUT> withPartitionBy(String argumentName, String... columnNames) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(columnNames, "columnNames must not be null");
+            checkArgument(columnNames.length > 0, "Must specify at least one column");
+
+            if (partitionConfigs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Partition config already exists for: " + argumentName);
+            }
+
+            PartitionConfiguration config = new PartitionConfiguration(columnNames);
+            partitionConfigs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Build
+        // ---------------------------------------------------------------------
+
+        /**
+         * Builds the test harness.
+         *
+         * <p>This instantiates the PTF, validates configuration via type inference, creates the
+         * FunctionContext, and opens the function.
+         *
+         * @return The configured test harness
+         * @throws Exception If instantiation or opening fails
+         */
+        public ProcessTableFunctionTestHarness<OUT> build() throws Exception {
+            ProcessTableFunction<OUT> function = instantiateFunction();
+
+            List<ArgumentInfo> arguments = extractAndValidateTypeInference(function);
+
+            FunctionContext functionContext =
+                    new FunctionContext(null, Thread.currentThread().getContextClassLoader(), null);
+
+            Method evalMethod = findEvalMethod();
+
+            validateEvalMethodSupported(evalMethod, arguments);
+            validatePartitionConsistency(arguments);
+
+            // In cases where PTFs have only a single table argument, set it as a default
+            // and mark as a single table function so that processElement without specifying
+            // a table argument can be used.
+            String defaultTableArg = null;
+            boolean isSingleTableFunction = false;
+
+            List<ArgumentInfo> tableArguments = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    tableArguments.add(arg);
+                }
+            }
+
+            if (tableArguments.size() == 1) {
+                defaultTableArg = tableArguments.get(0).name;
+                isSingleTableFunction = true;
+            }
+
+            Map<String, DataStructureConverter<Object, Object>> inputConverters = new HashMap<>();
+            Map<String, DataStructureConverter<Object, Object>> outputConverters = new HashMap<>();
+            createConverters(arguments, inputConverters, outputConverters);
+
+            Map<String, ArgumentInfo> argumentsByName = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    argumentsByName.put(arg.name, arg);
+                }
+            }
+
+            return new ProcessTableFunctionTestHarness<>(
+                    function,
+                    functionContext,
+                    defaultTableArg,
+                    evalMethod,
+                    arguments,
+                    argumentsByName,
+                    isSingleTableFunction,
+                    extractScalarValues(arguments),
+                    inputConverters,
+                    outputConverters);
+        }
+
+        /** Extracts scalar values from configs, creating a map keyed by argument name. */
+        private Map<String, Object> extractScalarValues(List<ArgumentInfo> arguments) {
+            Map<String, Object> values = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    ScalarArgumentConfiguration config = scalarArgs.get(arg.name);
+                    if (config != null) {
+                        values.put(arg.name, config.value);
+                    }
+                }
+            }
+            return values;
+        }
+
+        /**
+         * Creates and initializes data structure converters for all table arguments.
+         *
+         * <p>For Row types, both input and output converters are the same (between Row and
+         * RowData).
+         *
+         * <p>For structured types, input converter uses Row types (Row to RowData), and the output
+         * converter uses the structured type.
+         */
+        private void createConverters(
+                List<ArgumentInfo> arguments,
+                Map<String, DataStructureConverter<Object, Object>> inputConverters,
+                Map<String, DataStructureConverter<Object, Object>> outputConverters) {
+            ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    String converterKey = arg.name;
+
+                    LogicalType logicalType = arg.dataType.getLogicalType();
+                    boolean isStructuredType =
+                            logicalType instanceof StructuredType
+                                    && ((StructuredType) logicalType)
+                                            .getImplementationClass()
+                                            .isPresent();
+
+                    if (isStructuredType) {
+                        StructuredType structuredType = (StructuredType) logicalType;
+                        List<RowType.RowField> rowFields = new ArrayList<>();
+                        for (StructuredType.StructuredAttribute attr :
+                                structuredType.getAttributes()) {
+                            rowFields.add(new RowType.RowField(attr.getName(), attr.getType()));
+                        }
+                        RowType rowType = new RowType(logicalType.isNullable(), rowFields);
+                        DataType rowDataType = TypeConversions.fromLogicalToDataType(rowType);
+
+                        DataStructureConverter<Object, Object> inputConverter =
+                                DataStructureConverters.getConverter(rowDataType);
+                        inputConverter.open(classLoader);
+
+                        DataStructureConverter<Object, Object> outputConverter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        outputConverter.open(classLoader);
+
+                        inputConverters.put(converterKey, inputConverter);
+                        outputConverters.put(converterKey, outputConverter);
+                    } else {
+                        DataStructureConverter<Object, Object> converter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        converter.open(classLoader);
+
+                        inputConverters.put(converterKey, converter);
+                        outputConverters.put(converterKey, converter);
+                    }
+                }
+            }
+        }
+
+        private Method findEvalMethod() throws NoSuchMethodException {
+            Method[] methods = functionClass.getMethods();
+            Method evalMethod = null;
+            int evalMethodCount = 0;
+
+            for (Method method : methods) {
+                if (method.getName().equals("eval")) {
+                    evalMethod = method;
+                    evalMethodCount++;
+                }
+            }
+
+            if (evalMethodCount == 0) {
+                throw new NoSuchMethodException(
+                        "No eval() method found in " + functionClass.getSimpleName());
+            } else if (evalMethodCount > 1) {
+                throw new IllegalStateException(
+                        "Multiple eval() methods found in "
+                                + functionClass.getSimpleName()
+                                + ". ProcessTableFunction must have exactly one eval() method.");
+            } else {
+                return evalMethod;
+            }
+        }
+
+        /**
+         * Validates that the eval() method doesn't use unsupported features. Temporary, until state
+         * and context is supported.
+         */
+        private void validateEvalMethodSupported(Method evalMethod, List<ArgumentInfo> arguments) {
+            Parameter[] parameters = evalMethod.getParameters();
+
+            for (int i = 0; i < parameters.length; i++) {
+                Parameter param = parameters[i];
+                Class<?> paramType = param.getType();
+
+                if (ProcessTableFunction.Context.class.isAssignableFrom(paramType)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support Context parameters. "
+                                            + "Found Context parameter at position %d in eval() method. ",
+                                    i));
+                }
+
+                if (param.isAnnotationPresent(StateHint.class)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support state parameters. "
+                                            + "Found @StateHint parameter at position %d in eval() method. ",
+                                    i));
+                }
+            }
+
+            // Parameter count should also match our arguments list
+            if (parameters.length != arguments.size()) {
+                throw new IllegalStateException(
+                        String.format(
+                                "Parameter count mismatch: eval() has %d parameters but only %d arguments were extracted. "
+                                        + "This may indicate missing @ArgumentHint annotations.",
+                                parameters.length, arguments.size()));
+            }
+        }
+
+        /**
+         * Validates that all SET_SEMANTIC_TABLE arguments with partitioning use consistent
+         * partitioning. All such arguments must have the same number of partition columns with
+         * matching data types.
+         */
+        private void validatePartitionConsistency(List<ArgumentInfo> arguments) {
+            List<ArgumentInfo> partitionedTables = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    partitionedTables.add(arg);
+                }
+            }
+
+            if (partitionedTables.size() <= 1) {
+                return;
+            }
+
+            ArgumentInfo first = partitionedTables.get(0);
+            int expectedPartitionColumnCount = first.partitionColumnNames.length;
+
+            for (int i = 1; i < partitionedTables.size(); i++) {
+                ArgumentInfo current = partitionedTables.get(i);
+
+                if (current.partitionColumnNames.length != expectedPartitionColumnCount) {
+                    throw new IllegalArgumentException(
+                            String.format(
+                                    "Inconsistent partitioning: Table argument '%s' has %d partition column(s), "
+                                            + "but table argument '%s' has %d partition column(s). "
+                                            + "All SET_SEMANTIC_TABLE arguments must use consistent partitioning "
+                                            + "(same number of columns and matching data types).",
+                                    first.name,
+                                    expectedPartitionColumnCount,
+                                    current.name,
+                                    current.partitionColumnNames.length));
+                }
+
+                // Check that partition column types match
+                for (int colIdx = 0; colIdx < expectedPartitionColumnCount; colIdx++) {
+                    String firstColName = first.partitionColumnNames[colIdx];
+                    String currentColName = current.partitionColumnNames[colIdx];
+                    DataType firstColType = extractPartitionColumnType(first, firstColName);
+                    DataType currentColType = extractPartitionColumnType(current, currentColName);
+
+                    if (!firstColType.getLogicalType().equals(currentColType.getLogicalType())) {
+                        throw new IllegalArgumentException(
+                                String.format(
+                                        "Inconsistent partitioning: Partition column '%s' of table argument '%s' "
+                                                + "has type %s, but partition column '%s' of table argument '%s' "
+                                                + "has type %s. All SET_SEMANTIC_TABLE arguments must use "
+                                                + "consistent partitioning (same number of columns and matching data types).",
+                                        firstColName,
+                                        first.name,
+                                        firstColType,
+                                        currentColName,
+                                        current.name,
+                                        currentColType));
+                    }
+                }
+            }
+        }
+
+        private DataType extractPartitionColumnType(ArgumentInfo arg, String columnName) {
+            if (arg.dataType instanceof FieldsDataType) {
+                FieldsDataType fieldsDataType = (FieldsDataType) arg.dataType;
+                LogicalType logicalType = fieldsDataType.getLogicalType();
+                List<DataType> fieldDataTypes = fieldsDataType.getChildren();
+
+                if (logicalType instanceof RowType) {
+                    RowType rowType = (RowType) logicalType;
+                    int fieldIndex = 0;
+                    for (RowType.RowField field : rowType.getFields()) {
+                        if (field.getName().equals(columnName)) {
+                            return fieldDataTypes.get(fieldIndex);
+                        }
+                        fieldIndex++;
+                    }
+                } else if (logicalType instanceof StructuredType) {
+                    StructuredType structuredType = (StructuredType) logicalType;
+                    int attrIndex = 0;
+                    for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                        if (attr.getName().equals(columnName)) {
+                            return fieldDataTypes.get(attrIndex);
+                        }
+                        attrIndex++;
+                    }
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format(
+                            "Cannot extract data type for partition column '%s' of argument '%s'",
+                            columnName, arg.name));
+        }
+
+        // ---------------------------------------------------------------------
+        // Type Inference
+        // ---------------------------------------------------------------------
+
+        /**
+         * Extracts type inference from the PTF and validates builder configuration.
+         *
+         * <p>Uses SystemTypeInference to validate things like reserved argument names, multiple
+         * table argument rules, static argument trait validation, etc.
+         */
+        private List<ArgumentInfo> extractAndValidateTypeInference(
+                ProcessTableFunction<OUT> function) {
+
+            DataTypeFactory dataTypeFactory = createDataTypeFactory();
+            TypeInference baseTypeInference = function.getTypeInference(dataTypeFactory);
+            TypeInference systemTypeInference =
+                    SystemTypeInference.of(FunctionKind.PROCESS_TABLE, baseTypeInference);
+
+            Optional<List<StaticArgument>> staticArgsOpt = systemTypeInference.getStaticArguments();
+            if (staticArgsOpt.isEmpty()) {
+                throw new IllegalStateException(
+                        "PTF does not provide static argument information. "
+                                + "Ensure @ArgumentHint annotations are present on all eval() parameters.");
+            }
+
+            List<StaticArgument> allArgs = staticArgsOpt.get();
+            List<StaticArgument> userArgs = new ArrayList<>();
+            for (StaticArgument arg : allArgs) {
+                if (!isSystemArgument(arg.getName())) {
+                    userArgs.add(arg);
+                }
+            }
+
+            List<ArgumentInfo> arguments = new ArrayList<>();
+
+            for (StaticArgument staticArg : userArgs) {
+                boolean isScalar = staticArg.getTraits().contains(StaticArgumentTrait.SCALAR);
+                boolean isTableArg =
+                        staticArg.getTraits().contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)
+                                || staticArg
+                                        .getTraits()
+                                        .contains(StaticArgumentTrait.SET_SEMANTIC_TABLE);
+
+                if (isScalar || isTableArg) {
+                    ArgumentInfo argInfo = buildArgumentInfo(staticArg);
+                    arguments.add(argInfo);
+                } else {
+                    throw new IllegalStateException(
+                            "Unknown argument type for StaticArgument. "
+                                    + "Expected SCALAR, ROW_SEMANTIC_TABLE, or SET_SEMANTIC_TABLE trait.");
+                }
+            }
+
+            validateArgumentConfiguration(arguments);
+
+            return arguments;
+        }
+
+        /** Checks if an argument name is a system-reserved argument. */
+        private boolean isSystemArgument(String argName) {
+            return SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_ON_TIME.equals(argName)
+                    || SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_UID.equals(argName);
+        }
+
+        private DataTypeFactory createDataTypeFactory() {
+            return new TestHarnessDataTypeFactory();
+        }
+
+        private ArgumentInfo buildArgumentInfo(StaticArgument staticArg) {
+
+            String name = staticArg.getName();
+            ArgumentTrait primaryTrait = extractPrimaryTrait(staticArg.getTraits());
+
+            DataType dataType;
+            if (primaryTrait == ArgumentTrait.SCALAR) {
+                Optional<DataType> dataTypeOpt = staticArg.getDataType();
+                if (dataTypeOpt.isPresent()) {
+                    dataType = dataTypeOpt.get();
+                } else {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "Cannot determine data type for scalar argument '%s'", name));
+                }
+            } else {
+                // For table arguments, check both annotation and builder config
+                Optional<DataType> annotationTypeOpt = staticArg.getDataType();
+                TableArgumentConfiguration config = tableArgs.get(name);
+
+                if (annotationTypeOpt.isPresent()
+                        && config != null
+                        && config.explicitType != null) {
+                    // Both specified - validate they match
+                    DataTypeFactory factory = createDataTypeFactory();
+                    DataType builderType = factory.createDataType(config.explicitType);
+                    DataType annotationType = annotationTypeOpt.get();
+
+                    if (!annotationType.equals(builderType)) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Type mismatch for table argument '%s': "
+                                                + "annotation declares type %s but builder declares type %s. "
+                                                + "Use either @ArgumentHint(type = ...) OR .withTableArgument(...), not both.",
+                                        name, annotationType, builderType));
+                    }
+                    dataType = annotationType;
+                } else if (annotationTypeOpt.isPresent()) {
+                    dataType = annotationTypeOpt.get();
+                } else if (config != null && config.explicitType != null) {
+                    DataTypeFactory factory = createDataTypeFactory();
+                    dataType = factory.createDataType(config.explicitType);
+                } else {
+                    // Try to infer from Java parameter class (for structured types)
+                    Optional<Class<?>> conversionClassOpt = staticArg.getConversionClass();
+                    if (conversionClassOpt.isPresent()) {
+                        DataTypeFactory factory = createDataTypeFactory();
+                        dataType = factory.createDataType(conversionClassOpt.get());
+                    } else {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Table argument '%s' requires explicit type configuration. "
+                                                + "Use @ArgumentHint(type = @DataTypeHint(\"ROW<...>\")) or "
+                                                + ".withTableArgument(\"%s\", DataTypes.of(\"ROW<...>\"))",
+                                        name, name));
+                    }
+                }
+            }
+
+            String[] partitionColumnNames = null;
+            if (primaryTrait == ArgumentTrait.SET_SEMANTIC_TABLE) {
+                boolean hasOptionalPartitionBy =
+                        staticArg.getTraits().contains(StaticArgumentTrait.OPTIONAL_PARTITION_BY);
+                partitionColumnNames =
+                        extractAndValidatePartitionColumns(name, dataType, hasOptionalPartitionBy);
+            }
+
+            boolean hasPassColumnsThrough =
+                    staticArg.getTraits().contains(StaticArgumentTrait.PASS_COLUMNS_THROUGH);
+
+            return new ArgumentInfo(
+                    name, dataType, primaryTrait, partitionColumnNames, hasPassColumnsThrough);
+        }
+
+        private ArgumentTrait extractPrimaryTrait(EnumSet<StaticArgumentTrait> staticTraits) {
+            if (staticTraits.contains(StaticArgumentTrait.SCALAR)) {
+                return ArgumentTrait.SCALAR;
+            }
+            if (staticTraits.contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)) {
+                return ArgumentTrait.ROW_SEMANTIC_TABLE;
+            }
+            if (staticTraits.contains(StaticArgumentTrait.SET_SEMANTIC_TABLE)) {
+                return ArgumentTrait.SET_SEMANTIC_TABLE;
+            }
+            return ArgumentTrait.SCALAR;
+        }
+
+        private String[] extractAndValidatePartitionColumns(
+                String name, DataType dataType, boolean isOptionalPartitionBy) {
+            PartitionConfiguration config = partitionConfigs.get(name);
+            if (config == null) {
+                if (isOptionalPartitionBy) {
+                    return null;
+                }
+                throw new IllegalStateException(
+                        String.format(
+                                "No partition configuration found for table argument '%s'. "
+                                        + "Use withPartitionBy(\"%s\", ...) to configure partitioning.",
+                                name, name));
+            }
+
+            LogicalType logicalType = dataType.getLogicalType();
+            List<String> fieldNames = new ArrayList<>();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                for (RowType.RowField field : rowType.getFields()) {
+                    fieldNames.add(field.getName());
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    fieldNames.add(attr.getName());
+                }
+            } else {
+                throw new IllegalStateException(
+                        String.format(
+                                "Unsupported data type for partitioning: %s. "
+                                        + "Only Row and structured types (POJOs) support partitioning.",
+                                dataType));
+            }
+
+            for (String columnName : config.columnNames) {
+                if (!fieldNames.contains(columnName)) {
+                    throw new IllegalArgumentException(
+                            "Partition column '"
+                                    + columnName
+                                    + "' not found. "
+                                    + "Available columns: "
+                                    + fieldNames);
+                }
+            }
+            return config.columnNames;
+        }
+
+        private void validateArgumentConfiguration(List<ArgumentInfo> arguments) {
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    if (!scalarArgs.containsKey(arg.name)) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Missing required scalar argument '%s'. "
+                                                + "Use .withScalarArgument(\"%s\", ...)",
+                                        arg.name, arg.name));
+                    }
+                } else {
+                    // For table arguments: builder config is optional if type comes from annotation
+                    boolean hasBuilderConfig = tableArgs.containsKey(arg.name);
+                    boolean hasInlineType = arg.dataType != null;
+
+                    if (!hasBuilderConfig && !hasInlineType) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Missing required table argument '%s'. "
+                                                + "Either specify @ArgumentHint(type = @DataTypeHint(...)) "
+                                                + "or use .withTableArgument(\"%s\", ...)",
+                                        arg.name, arg.name));

Review Comment:
   Wasn't this already checked in `buildArgumentInfo()`?



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            LogicalType logicalType = dataType.getLogicalType();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                int index = 0;
+                for (RowType.RowField field : rowType.getFields()) {
+                    if (field.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                int index = 0;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    if (attr.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a table argument without an explicit schema.
+         *
+         * <p>Use this for structured type arguments where the type can be inferred from the PTF's
+         * eval() signature. For Row arguments, use {@link #withTableArgument(String,
+         * AbstractDataType)} with an explicit schema.
+         *
+         * @param argumentName The table argument name
+         */
+        public Builder<OUT> withTableArgument(String argumentName) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName) || tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException("Argument already configured: " + argumentName);
+            }
+
+            ScalarArgumentConfiguration config = new ScalarArgumentConfiguration(value);
+            scalarArgs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Partitioning
+        // ---------------------------------------------------------------------
+
+        /**
+         * Specifies partition columns for a set semantic table.
+         *
+         * @param argumentName The table argument name
+         * @param columnNames The partition column names
+         * @return This builder
+         */
+        public Builder<OUT> withPartitionBy(String argumentName, String... columnNames) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(columnNames, "columnNames must not be null");
+            checkArgument(columnNames.length > 0, "Must specify at least one column");
+
+            if (partitionConfigs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Partition config already exists for: " + argumentName);
+            }
+
+            PartitionConfiguration config = new PartitionConfiguration(columnNames);
+            partitionConfigs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Build
+        // ---------------------------------------------------------------------
+
+        /**
+         * Builds the test harness.
+         *
+         * <p>This instantiates the PTF, validates configuration via type inference, creates the
+         * FunctionContext, and opens the function.
+         *
+         * @return The configured test harness
+         * @throws Exception If instantiation or opening fails
+         */
+        public ProcessTableFunctionTestHarness<OUT> build() throws Exception {
+            ProcessTableFunction<OUT> function = instantiateFunction();
+
+            List<ArgumentInfo> arguments = extractAndValidateTypeInference(function);
+
+            FunctionContext functionContext =
+                    new FunctionContext(null, Thread.currentThread().getContextClassLoader(), null);
+
+            Method evalMethod = findEvalMethod();
+
+            validateEvalMethodSupported(evalMethod, arguments);
+            validatePartitionConsistency(arguments);
+
+            // In cases where PTFs have only a single table argument, set it as a default
+            // and mark as a single table function so that processElement without specifying
+            // a table argument can be used.
+            String defaultTableArg = null;
+            boolean isSingleTableFunction = false;
+
+            List<ArgumentInfo> tableArguments = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    tableArguments.add(arg);
+                }
+            }
+
+            if (tableArguments.size() == 1) {
+                defaultTableArg = tableArguments.get(0).name;
+                isSingleTableFunction = true;
+            }
+
+            Map<String, DataStructureConverter<Object, Object>> inputConverters = new HashMap<>();
+            Map<String, DataStructureConverter<Object, Object>> outputConverters = new HashMap<>();
+            createConverters(arguments, inputConverters, outputConverters);
+
+            Map<String, ArgumentInfo> argumentsByName = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    argumentsByName.put(arg.name, arg);
+                }
+            }
+
+            return new ProcessTableFunctionTestHarness<>(
+                    function,
+                    functionContext,
+                    defaultTableArg,
+                    evalMethod,
+                    arguments,
+                    argumentsByName,
+                    isSingleTableFunction,
+                    extractScalarValues(arguments),
+                    inputConverters,
+                    outputConverters);
+        }
+
+        /** Extracts scalar values from configs, creating a map keyed by argument name. */
+        private Map<String, Object> extractScalarValues(List<ArgumentInfo> arguments) {
+            Map<String, Object> values = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    ScalarArgumentConfiguration config = scalarArgs.get(arg.name);
+                    if (config != null) {
+                        values.put(arg.name, config.value);
+                    }
+                }
+            }
+            return values;
+        }
+
+        /**
+         * Creates and initializes data structure converters for all table arguments.
+         *
+         * <p>For Row types, both input and output converters are the same (between Row and
+         * RowData).
+         *
+         * <p>For structured types, input converter uses Row types (Row to RowData), and the output
+         * converter uses the structured type.
+         */
+        private void createConverters(
+                List<ArgumentInfo> arguments,
+                Map<String, DataStructureConverter<Object, Object>> inputConverters,
+                Map<String, DataStructureConverter<Object, Object>> outputConverters) {
+            ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    String converterKey = arg.name;
+
+                    LogicalType logicalType = arg.dataType.getLogicalType();
+                    boolean isStructuredType =
+                            logicalType instanceof StructuredType
+                                    && ((StructuredType) logicalType)
+                                            .getImplementationClass()
+                                            .isPresent();
+
+                    if (isStructuredType) {
+                        StructuredType structuredType = (StructuredType) logicalType;
+                        List<RowType.RowField> rowFields = new ArrayList<>();
+                        for (StructuredType.StructuredAttribute attr :
+                                structuredType.getAttributes()) {
+                            rowFields.add(new RowType.RowField(attr.getName(), attr.getType()));
+                        }
+                        RowType rowType = new RowType(logicalType.isNullable(), rowFields);
+                        DataType rowDataType = TypeConversions.fromLogicalToDataType(rowType);
+
+                        DataStructureConverter<Object, Object> inputConverter =
+                                DataStructureConverters.getConverter(rowDataType);
+                        inputConverter.open(classLoader);
+
+                        DataStructureConverter<Object, Object> outputConverter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        outputConverter.open(classLoader);
+
+                        inputConverters.put(converterKey, inputConverter);
+                        outputConverters.put(converterKey, outputConverter);
+                    } else {
+                        DataStructureConverter<Object, Object> converter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        converter.open(classLoader);
+
+                        inputConverters.put(converterKey, converter);
+                        outputConverters.put(converterKey, converter);
+                    }
+                }
+            }
+        }
+
+        private Method findEvalMethod() throws NoSuchMethodException {
+            Method[] methods = functionClass.getMethods();
+            Method evalMethod = null;
+            int evalMethodCount = 0;
+
+            for (Method method : methods) {
+                if (method.getName().equals("eval")) {
+                    evalMethod = method;
+                    evalMethodCount++;
+                }
+            }
+
+            if (evalMethodCount == 0) {
+                throw new NoSuchMethodException(
+                        "No eval() method found in " + functionClass.getSimpleName());
+            } else if (evalMethodCount > 1) {
+                throw new IllegalStateException(
+                        "Multiple eval() methods found in "
+                                + functionClass.getSimpleName()
+                                + ". ProcessTableFunction must have exactly one eval() method.");
+            } else {
+                return evalMethod;
+            }
+        }
+
+        /**
+         * Validates that the eval() method doesn't use unsupported features. Temporary, until state
+         * and context is supported.
+         */
+        private void validateEvalMethodSupported(Method evalMethod, List<ArgumentInfo> arguments) {
+            Parameter[] parameters = evalMethod.getParameters();
+
+            for (int i = 0; i < parameters.length; i++) {
+                Parameter param = parameters[i];
+                Class<?> paramType = param.getType();
+
+                if (ProcessTableFunction.Context.class.isAssignableFrom(paramType)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support Context parameters. "
+                                            + "Found Context parameter at position %d in eval() method. ",
+                                    i));
+                }
+
+                if (param.isAnnotationPresent(StateHint.class)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support state parameters. "
+                                            + "Found @StateHint parameter at position %d in eval() method. ",
+                                    i));
+                }
+            }
+
+            // Parameter count should also match our arguments list
+            if (parameters.length != arguments.size()) {
+                throw new IllegalStateException(
+                        String.format(
+                                "Parameter count mismatch: eval() has %d parameters but only %d arguments were extracted. "
+                                        + "This may indicate missing @ArgumentHint annotations.",
+                                parameters.length, arguments.size()));
+            }

Review Comment:
   Could also check if the provided values for scalar attributes are valid for the `eval()` signature.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "Au-Miner (via GitHub)" <gi...@apache.org>.
Au-Miner commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3115714118


##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1199 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        // Try named arguments first
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        } else {
+            invokeEval(tableArg, row);
+        }
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Invokes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void invoke() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        // Validate this is a scalar-only PTF
+        boolean hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "invoke() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        // Build arguments array with only scalar values
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+
+        // Invoke eval() method
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                // If the argument is a scalar argument, pull it from the predefined scalar
+                // argument fixtures.
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // If the argument is a table argument but is not the current, active table argument
+                // then just pass in null.
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                // No active table argument or it's scalar - just collect as-is
+                output.add(record);
+                return;
+            }
+
+            // Determine which columns to prepend
+            if (activeTableArg.hasPassColumnsThrough) {
+                // PASS_COLUMNS_THROUGH: Prepend ALL input columns
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                // SET_SEMANTIC_TABLE: Prepend partition key columns only
+                output.add(prependPartitionKeys(record));
+            } else {
+                // ROW_SEMANTIC_TABLE or no partitioning: no prepending
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    // Check if this is the active table
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            // Active table: extract partition key value from input row
+                            // Convert column name to position index
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            // Inactive table: use null
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            // Append PTF output
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            RowType rowType = (RowType) dataType.getLogicalType();
+            int index = 0;
+            for (RowType.RowField field : rowType.getFields()) {
+                if (field.getName().equals(fieldName)) {
+                    return index;
+                }
+                index++;
+            }
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend ALL input columns
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            // Append PTF output
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        // Position counter for positional-only arguments (those without @ArgumentHint names)
+        // Tracks eval() signature position for consistent dual-lookup
+        private int nextPosition = 0;
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration(argumentName);
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(value, "value must not be null");
+
+            if (scalarArgs.containsKey(argumentName) || tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException("Argument already configured: " + argumentName);
+            }
+
+            ScalarArgumentConfiguration config =
+                    new ScalarArgumentConfiguration(argumentName, value);
+            scalarArgs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Partitioning
+        // ---------------------------------------------------------------------
+
+        /**
+         * Specifies partition columns for a set semantic table.
+         *
+         * @param argumentName The table argument name
+         * @param columnNames The partition column names
+         * @return This builder
+         */
+        public Builder<OUT> withPartitionBy(String argumentName, String... columnNames) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(columnNames, "columnNames must not be null");
+            checkArgument(columnNames.length > 0, "Must specify at least one column");
+
+            if (partitionConfigs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Partition config already exists for: " + argumentName);
+            }
+
+            PartitionConfiguration config = new PartitionConfiguration(argumentName, columnNames);
+            partitionConfigs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Build
+        // ---------------------------------------------------------------------
+
+        /**
+         * Builds the test harness.
+         *
+         * <p>This instantiates the PTF, validates configuration via type inference, creates the
+         * FunctionContext, and opens the function.
+         *
+         * @return The configured test harness
+         * @throws Exception If instantiation or opening fails
+         */
+        public ProcessTableFunctionTestHarness<OUT> build() throws Exception {
+            ProcessTableFunction<OUT> function = instantiateFunction();
+
+            List<ArgumentInfo> arguments = extractAndValidateTypeInference(function);
+
+            FunctionContext functionContext =
+                    new FunctionContext(null, Thread.currentThread().getContextClassLoader(), null);
+
+            Method evalMethod = findEvalMethod();
+
+            // Validate that the eval method does not have currently unsupported arguments, like
+            // state or context.
+            validateEvalMethodSupported(evalMethod, arguments);
+
+            // Validate partition consistency for multi-table PTFs
+            validatePartitionConsistency(arguments);
+
+            // In cases where PTFs have only a single table argument, set it as a default
+            // and mark as a single table function so that processElement without specifying
+            // a table argument can be used.
+            String defaultTableArg = null;
+            boolean isSingleTableFunction = false;
+
+            // Count table arguments from actual signature (not just builder config)
+            List<ArgumentInfo> tableArguments = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    tableArguments.add(arg);
+                }
+            }
+
+            if (tableArguments.size() == 1) {
+                defaultTableArg = tableArguments.get(0).name;
+                isSingleTableFunction = true;
+            }
+
+            // Create input and output converters for table arguments.
+            Map<String, DataStructureConverter<Object, Object>> inputConverters = new HashMap<>();
+            Map<String, DataStructureConverter<Object, Object>> outputConverters = new HashMap<>();
+            createConverters(arguments, inputConverters, outputConverters);
+
+            // Build the map of named arguments for quick lookup.
+            Map<String, ArgumentInfo> argumentsByName = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    argumentsByName.put(arg.name, arg);
+                }
+            }
+
+            return new ProcessTableFunctionTestHarness<>(
+                    function,
+                    functionContext,
+                    defaultTableArg,
+                    evalMethod,
+                    arguments,
+                    argumentsByName,
+                    isSingleTableFunction,
+                    extractScalarValues(arguments),
+                    inputConverters,
+                    outputConverters);
+        }
+
+        /** Extracts scalar values from configs, creating a map keyed by argument name. */
+        private Map<String, Object> extractScalarValues(List<ArgumentInfo> arguments) {
+            Map<String, Object> values = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    ScalarArgumentConfiguration config = scalarArgs.get(arg.name);
+                    if (config != null) {
+                        values.put(arg.name, config.value);
+                    }
+                }
+            }
+            return values;
+        }
+
+        /**
+         * Creates and initializes data structure converters for all table arguments.
+         *
+         * <p>For Row types, both input and output converters are the same (between Row and
+         * RowData).
+         *
+         * <p>For structured types, input converter uses Row types (Row to RowData), and the output
+         * converter uses the structured type.
+         */
+        private void createConverters(
+                List<ArgumentInfo> arguments,
+                Map<String, DataStructureConverter<Object, Object>> inputConverters,
+                Map<String, DataStructureConverter<Object, Object>> outputConverters) {
+            ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    String converterKey = arg.name;
+
+                    LogicalType logicalType = arg.dataType.getLogicalType();
+                    boolean isStructuredType =
+                            logicalType instanceof StructuredType
+                                    && ((StructuredType) logicalType)
+                                            .getImplementationClass()
+                                            .isPresent();
+
+                    if (isStructuredType) {
+                        StructuredType structuredType = (StructuredType) logicalType;
+                        List<RowType.RowField> rowFields = new ArrayList<>();
+                        for (StructuredType.StructuredAttribute attr :
+                                structuredType.getAttributes()) {
+                            rowFields.add(new RowType.RowField(attr.getName(), attr.getType()));
+                        }
+                        RowType rowType = new RowType(logicalType.isNullable(), rowFields);
+                        DataType rowDataType = TypeConversions.fromLogicalToDataType(rowType);
+
+                        DataStructureConverter<Object, Object> inputConverter =
+                                DataStructureConverters.getConverter(rowDataType);
+                        inputConverter.open(classLoader);
+
+                        DataStructureConverter<Object, Object> outputConverter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        outputConverter.open(classLoader);
+
+                        inputConverters.put(converterKey, inputConverter);
+                        outputConverters.put(converterKey, outputConverter);
+                    } else {
+                        DataStructureConverter<Object, Object> converter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        converter.open(classLoader);
+
+                        inputConverters.put(converterKey, converter);
+                        outputConverters.put(converterKey, converter);
+                    }
+                }
+            }
+        }
+
+        private Method findEvalMethod() throws NoSuchMethodException {
+            Method[] methods = functionClass.getMethods();
+            Method evalMethod = null;
+            int evalMethodCount = 0;
+
+            for (Method method : methods) {
+                if (method.getName().equals("eval")) {
+                    evalMethod = method;
+                    evalMethodCount++;
+                }
+            }
+
+            if (evalMethodCount == 0) {
+                throw new NoSuchMethodException(
+                        "No eval() method found in " + functionClass.getSimpleName());
+            } else if (evalMethodCount > 1) {
+                throw new IllegalStateException(
+                        "Multiple eval() methods found in "
+                                + functionClass.getSimpleName()
+                                + ". ProcessTableFunction must have exactly one eval() method.");
+            } else {
+                return evalMethod;
+            }
+        }
+
+        /**
+         * Validates that the eval() method doesn't use unsupported features. Temporary, until state
+         * and context is supported.
+         */
+        private void validateEvalMethodSupported(Method evalMethod, List<ArgumentInfo> arguments) {
+            Parameter[] parameters = evalMethod.getParameters();
+
+            for (int i = 0; i < parameters.length; i++) {
+                Parameter param = parameters[i];
+                Class<?> paramType = param.getType();
+
+                if (ProcessTableFunction.Context.class.isAssignableFrom(paramType)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support Context parameters. "
+                                            + "Found Context parameter at position %d in eval() method. ",
+                                    i));
+                }
+
+                if (param.isAnnotationPresent(StateHint.class)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support state parameters. "
+                                            + "Found @StateHint parameter at position %d in eval() method. ",
+                                    i));
+                }
+            }
+
+            // Parameter count should also match our arguments list
+            if (parameters.length != arguments.size()) {
+                throw new IllegalStateException(
+                        String.format(
+                                "Parameter count mismatch: eval() has %d parameters but only %d arguments were extracted. "
+                                        + "This may indicate missing @ArgumentHint annotations.",
+                                parameters.length, arguments.size()));
+            }
+        }
+
+        /**
+         * Validates that all SET_SEMANTIC_TABLE arguments with partitioning use consistent
+         * partitioning. All such arguments must have the same number of partition columns with
+         * matching data types.
+         */
+        private void validatePartitionConsistency(List<ArgumentInfo> arguments) {
+            List<ArgumentInfo> partitionedTables = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    partitionedTables.add(arg);
+                }
+            }
+
+            if (partitionedTables.size() <= 1) {
+                return;
+            }
+
+            ArgumentInfo first = partitionedTables.get(0);
+            int expectedPartitionColumnCount = first.partitionColumnNames.length;
+
+            for (int i = 1; i < partitionedTables.size(); i++) {
+                ArgumentInfo current = partitionedTables.get(i);
+
+                if (current.partitionColumnNames.length != expectedPartitionColumnCount) {
+                    throw new IllegalArgumentException(
+                            String.format(
+                                    "Inconsistent partitioning: Table argument '%s' has %d partition column(s), "
+                                            + "but table argument '%s' has %d partition column(s). "
+                                            + "All SET_SEMANTIC_TABLE arguments must use consistent partitioning "
+                                            + "(same number of columns and matching data types).",
+                                    first.name,
+                                    expectedPartitionColumnCount,
+                                    current.name,
+                                    current.partitionColumnNames.length));
+                }
+
+                // Check that partition column types match
+                for (int colIdx = 0; colIdx < expectedPartitionColumnCount; colIdx++) {
+                    String firstColName = first.partitionColumnNames[colIdx];
+                    String currentColName = current.partitionColumnNames[colIdx];
+                    DataType firstColType = extractPartitionColumnType(first, firstColName);

Review Comment:
   The situation of StructuredType needs to be considered



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1199 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        // Try named arguments first
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        } else {
+            invokeEval(tableArg, row);
+        }
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Invokes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void invoke() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        // Validate this is a scalar-only PTF
+        boolean hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "invoke() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        // Build arguments array with only scalar values
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+
+        // Invoke eval() method
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                // If the argument is a scalar argument, pull it from the predefined scalar
+                // argument fixtures.
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // If the argument is a table argument but is not the current, active table argument
+                // then just pass in null.
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                // No active table argument or it's scalar - just collect as-is
+                output.add(record);
+                return;
+            }
+
+            // Determine which columns to prepend
+            if (activeTableArg.hasPassColumnsThrough) {
+                // PASS_COLUMNS_THROUGH: Prepend ALL input columns
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                // SET_SEMANTIC_TABLE: Prepend partition key columns only
+                output.add(prependPartitionKeys(record));
+            } else {
+                // ROW_SEMANTIC_TABLE or no partitioning: no prepending
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    // Check if this is the active table
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            // Active table: extract partition key value from input row
+                            // Convert column name to position index
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            // Inactive table: use null
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            // Append PTF output
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            RowType rowType = (RowType) dataType.getLogicalType();
+            int index = 0;
+            for (RowType.RowField field : rowType.getFields()) {
+                if (field.getName().equals(fieldName)) {
+                    return index;
+                }
+                index++;
+            }
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend ALL input columns
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            // Append PTF output
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        // Position counter for positional-only arguments (those without @ArgumentHint names)
+        // Tracks eval() signature position for consistent dual-lookup
+        private int nextPosition = 0;
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration(argumentName);
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(value, "value must not be null");

Review Comment:
   Why is it restricted here that argumentName and value cannot be null, while allowing eval input to be nullable.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "spuru9 (via GitHub)" <gi...@apache.org>.
spuru9 commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3084959280


##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1210 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.util.ArrayList;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgumentType("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final java.lang.reflect.Method evalMethod;

Review Comment:
   java.lang.reflect.Method can be imported in the top section.
   Same can be done for all others from reflect.*.



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1210 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.util.ArrayList;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgumentType("input", DataTypes.of("ROW<id INT, name STRING>"))

Review Comment:
   ```suggestion
    *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
   ```



##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1210 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.util.ArrayList;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgumentType("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final java.lang.reflect.Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            java.lang.reflect.Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        // Try named arguments first
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        } else {
+            invokeEval(tableArg, row);
+        }
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Invokes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void invoke() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        // Validate this is a scalar-only PTF
+        boolean hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "invoke() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        // Build arguments array with only scalar values
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+
+        // Invoke eval() method
+        try {
+            evalMethod.invoke(function, args);
+        } catch (java.lang.reflect.InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                // If the argument is a scalar argument, pull it from the predefined scalar
+                // argument fixtures.
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // If the argument is a table argument but is not the current, active table argument
+                // then just pass in null.
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (java.lang.reflect.InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        java.util.Arrays.toString(

Review Comment:
   nit: `import java.util.Arrays`



##########
docs/content/docs/dev/table/testing/ptf_test_harness.md:
##########
@@ -0,0 +1,361 @@
+---

Review Comment:
   The testing/ directory is missing an _index.md (needed for Hugo to show the section in the sidebar). Could you add one following the pattern of the sibling directories like functions/?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "autophagy (via GitHub)" <gi...@apache.org>.
autophagy commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3181239588


##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1199 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        // Try named arguments first
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        } else {
+            invokeEval(tableArg, row);
+        }
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Invokes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void invoke() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        // Validate this is a scalar-only PTF
+        boolean hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "invoke() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        // Build arguments array with only scalar values
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+
+        // Invoke eval() method
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                // If the argument is a scalar argument, pull it from the predefined scalar
+                // argument fixtures.
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // If the argument is a table argument but is not the current, active table argument
+                // then just pass in null.
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                // No active table argument or it's scalar - just collect as-is
+                output.add(record);
+                return;
+            }
+
+            // Determine which columns to prepend
+            if (activeTableArg.hasPassColumnsThrough) {
+                // PASS_COLUMNS_THROUGH: Prepend ALL input columns
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                // SET_SEMANTIC_TABLE: Prepend partition key columns only
+                output.add(prependPartitionKeys(record));
+            } else {
+                // ROW_SEMANTIC_TABLE or no partitioning: no prepending
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    // Check if this is the active table
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            // Active table: extract partition key value from input row
+                            // Convert column name to position index
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            // Inactive table: use null
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            // Append PTF output
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            RowType rowType = (RowType) dataType.getLogicalType();
+            int index = 0;
+            for (RowType.RowField field : rowType.getFields()) {
+                if (field.getName().equals(fieldName)) {
+                    return index;
+                }
+                index++;
+            }
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend ALL input columns
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            // Append PTF output
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        // Position counter for positional-only arguments (those without @ArgumentHint names)
+        // Tracks eval() signature position for consistent dual-lookup
+        private int nextPosition = 0;
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration(argumentName);
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(value, "value must not be null");

Review Comment:
   Good point! I've been a little overzealous with null checks here, I'll clean them up where it makes sense to



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "autophagy (via GitHub)" <gi...@apache.org>.
autophagy commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3257322962


##########
flink-table/flink-table-test-utils/src/test/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarnessTest.java:
##########
@@ -0,0 +1,1021 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.api.ValidationException;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class ProcessTableFunctionTestHarnessTest {
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PassthroughPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** Filter PTF for testing scalar argument handling. */
+    @DataTypeHint("ROW<value INT>")
+    public static class FilterPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer threshold) {
+            // Use named field access - converter enriches Row with field names
+            int value = input.getFieldAs("value");
+            if (value >= threshold) {
+                collect(input);
+            }
+        }
+    }
+
+    /** PTF for testing transformation of output types. */
+    @DataTypeHint("ROW<doubled INT, original INT>")
+    public static class DoublePTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2, value));
+        }
+    }
+
+    /** PTF with for testing table argument names set via argument hints. */
+    @DataTypeHint("ROW<value INT>")
+    public static class ExplicitNamePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "customName")
+                        Row actualParamName) {
+            collect(actualParamName);
+        }
+    }
+
+    /** PTF with inline type annotation - no builder config needed. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class InlineTypePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(
+                                value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+                                type = @DataTypeHint("ROW<value INT>"))
+                        Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PartitionedPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+            collect(Row.of((Integer) input.getFieldAs("value")));
+        }
+    }
+
+    /**
+     * PTF with PASS_COLUMNS_THROUGH for validating that all input columns are prepended to output.
+     */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class PassColumnsThroughPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** PTF with OPTIONAL_PARTITION_BY for validating that partition setup can be omitted. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class OptionalPartitionPTF extends ProcessTableFunction<Row> {
+
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.OPTIONAL_PARTITION_BY
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** Simple POJO for testing structured type input/output. */
+    public static class User {
+        public String name;
+        public int age;
+
+        public User() {}
+
+        public User(String name, int age) {
+            this.name = name;
+            this.age = age;
+        }
+
+        @Override
+        public String toString() {
+            return "User{name='" + name + "', age=" + age + '}';
+        }
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o) {
+                return true;
+            }
+            if (o == null || getClass() != o.getClass()) {
+                return false;
+            }
+            User user = (User) o;
+            return age == user.age && java.util.Objects.equals(name, user.name);
+        }
+
+        @Override
+        public int hashCode() {
+            return java.util.Objects.hash(name, age);
+        }
+    }
+
+    /** PTF for testing structured type inputs. */
+    @DataTypeHint("ROW<name STRING, age INT>")
+    public static class UserPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            if (user.age >= 18) {
+                collect(Row.of(user.name, user.age));
+            }
+        }
+    }
+
+    /** PTF that transforms structured type inputs and outputs. */
+    public static class UserTransformPTF extends ProcessTableFunction<User> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            User transformed = new User(user.name, user.age + 1);
+            collect(transformed);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "on_time". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgOnTimePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "on_time")
+                        Row input) {
+            collect(input);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "uid". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgUidPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) String uid) {
+            collect(input);
+        }
+    }
+
+    /** Multi-table PTF for validating multi-input processing. */
+    @DataTypeHint("ROW<output STRING>")
+    public static class MultiTableUnionPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /**
+     * Multi-table PTF with one POJO and one Row argument, for testing partitioning with structured
+     * types.
+     */
+    @DataTypeHint("ROW<source STRING, age INT>")
+    public static class MixedTypeMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) User userTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rowTable) {
+            if (userTable != null) {
+                collect(Row.of("USER", userTable.age));
+            }
+            if (rowTable != null) {
+                collect(Row.of("ROW", rowTable.getFieldAs("age")));
+            }
+        }
+    }
+
+    /**
+     * Invalid PTF - uses PASS_COLUMNS_THROUGH with multiple table arguments (not allowed per Flink
+     * docs).
+     */
+    @DataTypeHint("ROW<output STRING>")
+    public static class InvalidPassColumnsThroughMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /** PTF with only scalar arguments, no tables. */
+    @DataTypeHint("ROW<sum INT>")
+    public static class ScalarOnlyPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer a,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer b) {
+            collect(Row.of(a + b));
+        }
+    }
+
+    /** PTF with Context parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithContext extends ProcessTableFunction<Row> {
+        public void eval(Context ctx, @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** PTF with State parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithState extends ProcessTableFunction<Row> {
+        public static class CountState {
+            public long counter = 0L;
+        }
+
+        public void eval(
+                @StateHint CountState state,
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Builder Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testBuilderRejectsDuplicateScalarArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("threshold", 50)
+                                    .withScalarArgument("threshold", 100);
+                        });
+
+        assertThat(exception.getMessage()).contains("threshold");
+    }
+
+    @Test
+    void testBuilderRejectsDuplicateTableArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableUnionPTF.class)
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, value INT>"));
+                        });
+
+        assertThat(exception.getMessage()).contains("leftTable");
+    }
+
+    @Test
+    void testBuilderRejectsMixedDuplicateArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("input", 42);
+                        });
+
+        assertThat(exception.getMessage()).contains("input");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentOnTime() {
+        // We should reject PTFs that use reserved argument name "on_time"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgOnTimePTF.class)
+                        .withTableArgument("on_time", DataTypes.of("ROW<id INT>"));
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("on_time");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentUid() {
+        // We should reject PTFs that use reserved argument name "uid"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgUidPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<id INT>"))
+                        .withScalarArgument("uid", "my-id");
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("uid");
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testExplicitNameTakesPrecedence() throws Exception {
+        // Verify that @ArgumentHint(name="customName") takes precedence over actual parameter
+        // name when processing elements and calling eval.
+
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ExplicitNamePTF.class)
+                        .withTableArgument("customName", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(42));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0).getField(0)).isEqualTo(42);
+            assertThat(output.get(1).getField(0)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testScalarOnlyPTF() throws Exception {
+        // Test scalar-only PTF with no table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ScalarOnlyPTF.class)
+                        .withScalarArgument("a", 10)
+                        .withScalarArgument("b", 20)
+                        .build()) {
+
+            harness.process();
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0).getField(0)).isEqualTo(30);
+        }
+    }
+
+    @Test
+    void testInvokeRejectsTableArguments() throws Exception {
+        // Verify that invoke() rejects PTFs with table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50)
+                        .build()) {
+
+            Exception exception =
+                    assertThrows(
+                            IllegalStateException.class,
+                            () -> {
+                                harness.process();
+                            });
+
+            assertThat(exception.getMessage()).contains("process() is only for scalar-only PTFs");
+        }
+    }
+
+    @Test
+    void testTableProcessingWithScalarArgument() throws Exception {
+        // Test a PTF that uses a scalar parameter
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50) // Scalar argument: threshold = 50
+                        .build()) {
+
+            harness.processElement(Row.of(25));
+            harness.processElement(Row.of(75));
+            harness.processElement(Row.of(50));
+            harness.processElement(Row.of(10));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0).getField(0)).isEqualTo(75);
+            assertThat(output.get(1).getField(0)).isEqualTo(50);
+            assertThat(output.get(2).getField(0)).isEqualTo(100);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Trait Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testProcessElementWithRowKind() throws Exception {
+        // Verify RowKind is preserved through processing (ROW_SEMANTIC_TABLE)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(RowKind.INSERT, 10);
+            harness.processElement(RowKind.UPDATE_BEFORE, 15);
+            harness.processElement(RowKind.UPDATE_AFTER, 20);
+            harness.processElement(RowKind.DELETE, 30);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+            assertThat(output.get(0).getKind()).isEqualTo(RowKind.INSERT);
+            assertThat(output.get(0).getField(0)).isEqualTo(10);
+            assertThat(output.get(1).getKind()).isEqualTo(RowKind.UPDATE_BEFORE);
+            assertThat(output.get(1).getField(0)).isEqualTo(15);
+            assertThat(output.get(2).getKind()).isEqualTo(RowKind.UPDATE_AFTER);
+            assertThat(output.get(2).getField(0)).isEqualTo(20);
+            assertThat(output.get(3).getKind()).isEqualTo(RowKind.DELETE);
+            assertThat(output.get(3).getField(0)).isEqualTo(30);
+        }
+    }
+
+    @Test
+    void testPassColumnsThroughTrait() throws Exception {
+        // Verify PASS_COLUMNS_THROUGH prepends ALL input columns (not just partition keys)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassColumnsThroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 10, 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("B", 20, 40));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithoutPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY allows omitting partition configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+            harness.processElement(Row.of("C", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of(20));
+            assertThat(output.get(1)).isEqualTo(Row.of(40));
+            assertThat(output.get(2)).isEqualTo(Row.of(60));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY still works when partition is configured
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("A", 5));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("A", 10));
+            assertThat(output.get(2)).isEqualTo(Row.of("B", 40));
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Data Type Conversion Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testNamedRowFieldOrdering() throws Exception {
+        // Test what happens when Row field order differs from DataType schema order
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row rowA = Row.withNames();
+            rowA.setField("value", 100);
+            rowA.setField("user", "Alice");
+
+            harness.processElement(rowA);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+
+            // Positional access follows schema order
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testPositionalRowWithWrongTypeOrder() throws Exception {
+        // Verify that type mismatches are caught when Row values don't match schema types
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row wrongOrderRow = Row.of(10, "Alice");
+
+            Exception exception =
+                    assertThrows(
+                            ClassCastException.class, () -> harness.processElement(wrongOrderRow));
+
+            assertThat(exception.getMessage()).contains("Integer");
+            assertThat(exception.getMessage()).contains("String");
+            assertThat(exception.getMessage()).contains("cannot be cast");
+        }
+    }
+
+    @Test
+    void testStructuredTypeInput() throws Exception {
+        // Test that a PTF can declare an input type as a structured type,
+        // and that the harness can handle the conversion from Row into
+        // that type.
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+            harness.processElement(Row.of("Bob", 17));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(25);
+        }
+    }
+
+    @Test
+    void testStructuredTypeInputAndOutput() throws Exception {
+        // Test PTF with structured type inputs and outputs
+        try (ProcessTableFunctionTestHarness<User> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserTransformPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+
+            List<User> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            User result = output.get(0);
+            assertThat(result.getClass()).isEqualTo(User.class);
+            assertThat(result.name).isEqualTo("Alice");
+            assertThat(result.age).isEqualTo(26);
+        }
+    }
+
+    @Test
+    void testInlineTypeAnnotation() throws Exception {
+        // Verify that PTFs can declare table argument types via @ArgumentHint(type = ...)
+        // without needing .withTableArgument() configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class).build()) {
+
+            harness.processElement(Row.of(5));
+            harness.processElement(Row.of(10));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0)).isEqualTo(Row.of(10));
+            assertThat(output.get(1)).isEqualTo(Row.of(20));
+        }
+    }
+
+    @Test
+    void testInlineTypeMatchesBuilderConfig() throws Exception {
+        // Verify that when both inline annotation and builder config are provided with matching
+        // types, the harness builds successfully
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(7));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0)).isEqualTo(Row.of(14));
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Partitioning Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testSetSemanticWithPartitionByName() throws Exception {
+        // Verify set-semantic table with partition configuration by column name
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key") // Partition by "key" column name
+                        .build()) {
+
+            harness.processElement(Row.of("X", 10));
+            harness.processElement(Row.of("Y", 20));
+            harness.processElement(Row.of("X", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0)).isEqualTo(Row.of("X", 10));
+            assertThat(output.get(1)).isEqualTo(Row.of("Y", 20));
+            assertThat(output.get(2)).isEqualTo(Row.of("X", 30));
+        }
+    }
+
+    @Test
+    void testSetSemanticWithMultiplePartitionColumns() throws Exception {
+        // Verify composite partition key (multiple columns)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument(
+                                "input",
+                                DataTypes.of("ROW<region STRING, country STRING, value INT>"))
+                        .withPartitionBy("input", "region", "country")
+                        .build()) {
+
+            harness.processElement(Row.of("EU", "DE", 100));
+            harness.processElement(Row.of("EU", "DE", 200));
+            harness.processElement(Row.of("EU", "FR", 300));
+            harness.processElement(Row.of("US", "NY", 400));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+            assertThat(output.get(0)).isEqualTo(Row.of("EU", "DE", 100));
+            assertThat(output.get(1)).isEqualTo(Row.of("EU", "DE", 200));
+            assertThat(output.get(2)).isEqualTo(Row.of("EU", "FR", 300));
+            assertThat(output.get(3)).isEqualTo(Row.of("US", "NY", 400));
+        }
+    }
+
+    @Test
+    void testSetSemanticWithSelectivePartitioning() throws Exception {
+        // Verify that only partition columns are automatically included in output
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument(
+                                "input",
+                                DataTypes.of(
+                                        "ROW<id INT, region STRING, country STRING, city STRING, value INT>"))
+                        .withPartitionBy("input", "region")
+                        .build()) {
+
+            harness.processElement(Row.of(1, "EU", "DE", "Berlin", 100));
+            harness.processElement(Row.of(4, "US", "CA", "LA", 200));
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output.get(0)).isEqualTo(Row.of("EU", 100));
+            assertThat(output.get(1)).isEqualTo(Row.of("US", 200));
+        }
+    }
+
+    @Test
+    void testMultipleSetSemanticTablesWithMatchingPartitionKeys() throws Exception {
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(MultiTableUnionPTF.class)
+                        .withTableArgument("leftTable", DataTypes.of("ROW<name STRING, score INT>"))
+                        .withPartitionBy("leftTable", "name")
+                        .withTableArgument(
+                                "rightTable", DataTypes.of("ROW<name STRING, city STRING>"))
+                        .withPartitionBy("rightTable", "name")

Review Comment:
   Actually digging into this further, I think I misunderstood the test (that the column names were just for the sink schema). In the collector used for PTFs in the actual runtime, it just collects `RowData` which is purely positional I think. So I believe our behaviour here is correct



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "fhueske (via GitHub)" <gi...@apache.org>.
fhueske commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3259201512


##########
flink-table/flink-table-test-utils/src/test/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarnessTest.java:
##########
@@ -0,0 +1,1021 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.api.ValidationException;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class ProcessTableFunctionTestHarnessTest {
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PassthroughPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** Filter PTF for testing scalar argument handling. */
+    @DataTypeHint("ROW<value INT>")
+    public static class FilterPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer threshold) {
+            // Use named field access - converter enriches Row with field names
+            int value = input.getFieldAs("value");
+            if (value >= threshold) {
+                collect(input);
+            }
+        }
+    }
+
+    /** PTF for testing transformation of output types. */
+    @DataTypeHint("ROW<doubled INT, original INT>")
+    public static class DoublePTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2, value));
+        }
+    }
+
+    /** PTF with for testing table argument names set via argument hints. */
+    @DataTypeHint("ROW<value INT>")
+    public static class ExplicitNamePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "customName")
+                        Row actualParamName) {
+            collect(actualParamName);
+        }
+    }
+
+    /** PTF with inline type annotation - no builder config needed. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class InlineTypePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(
+                                value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+                                type = @DataTypeHint("ROW<value INT>"))
+                        Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PartitionedPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+            collect(Row.of((Integer) input.getFieldAs("value")));
+        }
+    }
+
+    /**
+     * PTF with PASS_COLUMNS_THROUGH for validating that all input columns are prepended to output.
+     */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class PassColumnsThroughPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** PTF with OPTIONAL_PARTITION_BY for validating that partition setup can be omitted. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class OptionalPartitionPTF extends ProcessTableFunction<Row> {
+
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.OPTIONAL_PARTITION_BY
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** Simple POJO for testing structured type input/output. */
+    public static class User {
+        public String name;
+        public int age;
+
+        public User() {}
+
+        public User(String name, int age) {
+            this.name = name;
+            this.age = age;
+        }
+
+        @Override
+        public String toString() {
+            return "User{name='" + name + "', age=" + age + '}';
+        }
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o) {
+                return true;
+            }
+            if (o == null || getClass() != o.getClass()) {
+                return false;
+            }
+            User user = (User) o;
+            return age == user.age && java.util.Objects.equals(name, user.name);
+        }
+
+        @Override
+        public int hashCode() {
+            return java.util.Objects.hash(name, age);
+        }
+    }
+
+    /** PTF for testing structured type inputs. */
+    @DataTypeHint("ROW<name STRING, age INT>")
+    public static class UserPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            if (user.age >= 18) {
+                collect(Row.of(user.name, user.age));
+            }
+        }
+    }
+
+    /** PTF that transforms structured type inputs and outputs. */
+    public static class UserTransformPTF extends ProcessTableFunction<User> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            User transformed = new User(user.name, user.age + 1);
+            collect(transformed);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "on_time". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgOnTimePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "on_time")
+                        Row input) {
+            collect(input);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "uid". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgUidPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) String uid) {
+            collect(input);
+        }
+    }
+
+    /** Multi-table PTF for validating multi-input processing. */
+    @DataTypeHint("ROW<output STRING>")
+    public static class MultiTableUnionPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /**
+     * Multi-table PTF with one POJO and one Row argument, for testing partitioning with structured
+     * types.
+     */
+    @DataTypeHint("ROW<source STRING, age INT>")
+    public static class MixedTypeMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) User userTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rowTable) {
+            if (userTable != null) {
+                collect(Row.of("USER", userTable.age));
+            }
+            if (rowTable != null) {
+                collect(Row.of("ROW", rowTable.getFieldAs("age")));
+            }
+        }
+    }
+
+    /**
+     * Invalid PTF - uses PASS_COLUMNS_THROUGH with multiple table arguments (not allowed per Flink
+     * docs).
+     */
+    @DataTypeHint("ROW<output STRING>")
+    public static class InvalidPassColumnsThroughMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /** PTF with only scalar arguments, no tables. */
+    @DataTypeHint("ROW<sum INT>")
+    public static class ScalarOnlyPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer a,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer b) {
+            collect(Row.of(a + b));
+        }
+    }
+
+    /** PTF with Context parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithContext extends ProcessTableFunction<Row> {
+        public void eval(Context ctx, @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** PTF with State parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithState extends ProcessTableFunction<Row> {
+        public static class CountState {
+            public long counter = 0L;
+        }
+
+        public void eval(
+                @StateHint CountState state,
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Builder Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testBuilderRejectsDuplicateScalarArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("threshold", 50)
+                                    .withScalarArgument("threshold", 100);
+                        });
+
+        assertThat(exception.getMessage()).contains("threshold");
+    }
+
+    @Test
+    void testBuilderRejectsDuplicateTableArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableUnionPTF.class)
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, value INT>"));
+                        });
+
+        assertThat(exception.getMessage()).contains("leftTable");
+    }
+
+    @Test
+    void testBuilderRejectsMixedDuplicateArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("input", 42);
+                        });
+
+        assertThat(exception.getMessage()).contains("input");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentOnTime() {
+        // We should reject PTFs that use reserved argument name "on_time"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgOnTimePTF.class)
+                        .withTableArgument("on_time", DataTypes.of("ROW<id INT>"));
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("on_time");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentUid() {
+        // We should reject PTFs that use reserved argument name "uid"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgUidPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<id INT>"))
+                        .withScalarArgument("uid", "my-id");
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("uid");
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testExplicitNameTakesPrecedence() throws Exception {
+        // Verify that @ArgumentHint(name="customName") takes precedence over actual parameter
+        // name when processing elements and calling eval.
+
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ExplicitNamePTF.class)
+                        .withTableArgument("customName", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(42));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0).getField(0)).isEqualTo(42);
+            assertThat(output.get(1).getField(0)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testScalarOnlyPTF() throws Exception {
+        // Test scalar-only PTF with no table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ScalarOnlyPTF.class)
+                        .withScalarArgument("a", 10)
+                        .withScalarArgument("b", 20)
+                        .build()) {
+
+            harness.process();
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0).getField(0)).isEqualTo(30);
+        }
+    }
+
+    @Test
+    void testInvokeRejectsTableArguments() throws Exception {
+        // Verify that invoke() rejects PTFs with table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50)
+                        .build()) {
+
+            Exception exception =
+                    assertThrows(
+                            IllegalStateException.class,
+                            () -> {
+                                harness.process();
+                            });
+
+            assertThat(exception.getMessage()).contains("process() is only for scalar-only PTFs");
+        }
+    }
+
+    @Test
+    void testTableProcessingWithScalarArgument() throws Exception {
+        // Test a PTF that uses a scalar parameter
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50) // Scalar argument: threshold = 50
+                        .build()) {
+
+            harness.processElement(Row.of(25));
+            harness.processElement(Row.of(75));
+            harness.processElement(Row.of(50));
+            harness.processElement(Row.of(10));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0).getField(0)).isEqualTo(75);
+            assertThat(output.get(1).getField(0)).isEqualTo(50);
+            assertThat(output.get(2).getField(0)).isEqualTo(100);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Trait Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testProcessElementWithRowKind() throws Exception {
+        // Verify RowKind is preserved through processing (ROW_SEMANTIC_TABLE)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(RowKind.INSERT, 10);
+            harness.processElement(RowKind.UPDATE_BEFORE, 15);
+            harness.processElement(RowKind.UPDATE_AFTER, 20);
+            harness.processElement(RowKind.DELETE, 30);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+            assertThat(output.get(0).getKind()).isEqualTo(RowKind.INSERT);
+            assertThat(output.get(0).getField(0)).isEqualTo(10);
+            assertThat(output.get(1).getKind()).isEqualTo(RowKind.UPDATE_BEFORE);
+            assertThat(output.get(1).getField(0)).isEqualTo(15);
+            assertThat(output.get(2).getKind()).isEqualTo(RowKind.UPDATE_AFTER);
+            assertThat(output.get(2).getField(0)).isEqualTo(20);
+            assertThat(output.get(3).getKind()).isEqualTo(RowKind.DELETE);
+            assertThat(output.get(3).getField(0)).isEqualTo(30);
+        }
+    }
+
+    @Test
+    void testPassColumnsThroughTrait() throws Exception {
+        // Verify PASS_COLUMNS_THROUGH prepends ALL input columns (not just partition keys)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassColumnsThroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 10, 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("B", 20, 40));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithoutPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY allows omitting partition configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+            harness.processElement(Row.of("C", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of(20));
+            assertThat(output.get(1)).isEqualTo(Row.of(40));
+            assertThat(output.get(2)).isEqualTo(Row.of(60));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY still works when partition is configured
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("A", 5));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("A", 10));
+            assertThat(output.get(2)).isEqualTo(Row.of("B", 40));
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Data Type Conversion Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testNamedRowFieldOrdering() throws Exception {
+        // Test what happens when Row field order differs from DataType schema order
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row rowA = Row.withNames();
+            rowA.setField("value", 100);
+            rowA.setField("user", "Alice");
+
+            harness.processElement(rowA);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+
+            // Positional access follows schema order
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testPositionalRowWithWrongTypeOrder() throws Exception {
+        // Verify that type mismatches are caught when Row values don't match schema types
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row wrongOrderRow = Row.of(10, "Alice");
+
+            Exception exception =
+                    assertThrows(
+                            ClassCastException.class, () -> harness.processElement(wrongOrderRow));
+
+            assertThat(exception.getMessage()).contains("Integer");
+            assertThat(exception.getMessage()).contains("String");
+            assertThat(exception.getMessage()).contains("cannot be cast");
+        }
+    }
+
+    @Test
+    void testStructuredTypeInput() throws Exception {
+        // Test that a PTF can declare an input type as a structured type,
+        // and that the harness can handle the conversion from Row into
+        // that type.
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+            harness.processElement(Row.of("Bob", 17));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(25);
+        }
+    }
+
+    @Test
+    void testStructuredTypeInputAndOutput() throws Exception {
+        // Test PTF with structured type inputs and outputs
+        try (ProcessTableFunctionTestHarness<User> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserTransformPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+
+            List<User> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            User result = output.get(0);
+            assertThat(result.getClass()).isEqualTo(User.class);
+            assertThat(result.name).isEqualTo("Alice");
+            assertThat(result.age).isEqualTo(26);
+        }
+    }
+
+    @Test
+    void testInlineTypeAnnotation() throws Exception {
+        // Verify that PTFs can declare table argument types via @ArgumentHint(type = ...)
+        // without needing .withTableArgument() configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class).build()) {
+
+            harness.processElement(Row.of(5));
+            harness.processElement(Row.of(10));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0)).isEqualTo(Row.of(10));
+            assertThat(output.get(1)).isEqualTo(Row.of(20));
+        }
+    }
+
+    @Test
+    void testInlineTypeMatchesBuilderConfig() throws Exception {
+        // Verify that when both inline annotation and builder config are provided with matching
+        // types, the harness builds successfully
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(7));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0)).isEqualTo(Row.of(14));
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Partitioning Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testSetSemanticWithPartitionByName() throws Exception {
+        // Verify set-semantic table with partition configuration by column name
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key") // Partition by "key" column name
+                        .build()) {
+
+            harness.processElement(Row.of("X", 10));
+            harness.processElement(Row.of("Y", 20));
+            harness.processElement(Row.of("X", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0)).isEqualTo(Row.of("X", 10));
+            assertThat(output.get(1)).isEqualTo(Row.of("Y", 20));
+            assertThat(output.get(2)).isEqualTo(Row.of("X", 30));
+        }
+    }
+
+    @Test
+    void testSetSemanticWithMultiplePartitionColumns() throws Exception {
+        // Verify composite partition key (multiple columns)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument(
+                                "input",
+                                DataTypes.of("ROW<region STRING, country STRING, value INT>"))
+                        .withPartitionBy("input", "region", "country")
+                        .build()) {
+
+            harness.processElement(Row.of("EU", "DE", 100));
+            harness.processElement(Row.of("EU", "DE", 200));
+            harness.processElement(Row.of("EU", "FR", 300));
+            harness.processElement(Row.of("US", "NY", 400));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+            assertThat(output.get(0)).isEqualTo(Row.of("EU", "DE", 100));
+            assertThat(output.get(1)).isEqualTo(Row.of("EU", "DE", 200));
+            assertThat(output.get(2)).isEqualTo(Row.of("EU", "FR", 300));
+            assertThat(output.get(3)).isEqualTo(Row.of("US", "NY", 400));
+        }
+    }
+
+    @Test
+    void testSetSemanticWithSelectivePartitioning() throws Exception {
+        // Verify that only partition columns are automatically included in output
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument(
+                                "input",
+                                DataTypes.of(
+                                        "ROW<id INT, region STRING, country STRING, city STRING, value INT>"))
+                        .withPartitionBy("input", "region")
+                        .build()) {
+
+            harness.processElement(Row.of(1, "EU", "DE", "Berlin", 100));
+            harness.processElement(Row.of(4, "US", "CA", "LA", 200));
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output.get(0)).isEqualTo(Row.of("EU", 100));
+            assertThat(output.get(1)).isEqualTo(Row.of("US", 200));
+        }
+    }
+
+    @Test
+    void testMultipleSetSemanticTablesWithMatchingPartitionKeys() throws Exception {
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(MultiTableUnionPTF.class)
+                        .withTableArgument("leftTable", DataTypes.of("ROW<name STRING, score INT>"))
+                        .withPartitionBy("leftTable", "name")
+                        .withTableArgument(
+                                "rightTable", DataTypes.of("ROW<name STRING, city STRING>"))
+                        .withPartitionBy("rightTable", "name")

Review Comment:
   nice, thank you!



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "autophagy (via GitHub)" <gi...@apache.org>.
autophagy commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3217432727


##########
docs/content.zh/docs/dev/table/functions/ptfs.md:
##########
@@ -2034,3 +2034,336 @@ Limitations
 PTFs are in an early stage. The following limitations apply:
 - PTFs cannot run in batch mode.
 - Broadcast state
+
+Testing Process Table Functions
+-------------------------------
+
+The `ProcessTableFunctionTestHarness` provides a lightweight unit testing framework for Process Table
+Functions (PTFs). It is useful for unit testing and validating PTF business logic, multi-table PTF
+behaviour and validating errors.
+
+For end-to-end integration testing with the full Flink planner and runtime, use integration tests
+instead.
+
+{{< top >}}
+
+### Quick Start
+
+{{< tabs "quickstart" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.*;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.runtime.functions.ProcessTableFunctionTestHarness;
+import org.apache.flink.types.Row;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+// PTF under test
+@DataTypeHint("ROW<doubled INT>")
+public class DoublePTF extends ProcessTableFunction<Row> {
+  public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+    int value = input.getFieldAs("value");
+    collect(Row.of(value * 2));
+  }
+}
+
+// Test
+@Test
+void testDoublePTF() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(DoublePTF.class)
+          .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+          .build()) {
+
+    harness.processElement(Row.of(5));
+    harness.processElement(Row.of(10));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).hasSize(2);
+    assertThat(output.get(0)).isEqualTo(Row.of(10));
+    assertThat(output.get(1)).isEqualTo(Row.of(20));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+{{< top >}}
+
+### Common Testing Scenarios
+
+#### Testing Row-Semantic Tables
+
+Use `.withTableArgument()` to configure the input table schema:
+
+{{< tabs "row-semantic" >}}
+{{< tab "Java" >}}
+```java
+public class PassthroughPTF extends ProcessTableFunction<Integer> {
+  public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+    collect(input.getFieldAs("value"));
+  }
+}
+
+@Test
+void testPassthrough() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+          .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+          .build()) {
+
+    harness.processElement(Row.of(42));
+    harness.processElement(Row.of(100));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).containsExactly(42, 100);
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Testing Set-Semantic Tables with Partitioning
+
+For `SET_SEMANTIC_TABLE`, use `.withPartitionBy()` to configure partition columns:
+
+{{< tabs "set-semantic" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<doubled INT>")
+public class PartitionedPTF extends ProcessTableFunction<Row> {
+  public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+    int value = input.getFieldAs("value");
+    collect(Row.of(value * 2));
+  }
+}
+
+@Test
+void testPartitionedPTF() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+          .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+          .withPartitionBy("input", "key")
+          .build()) {
+
+    harness.processElement(Row.of("A", 10));
+    harness.processElement(Row.of("B", 20));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+    assertThat(output.get(1)).isEqualTo(Row.of("B", 40));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Testing Multiple Table Arguments
+
+Use `processElementForTable()` to specify which table receives each row:
+
+{{< tabs "multi-table" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<output STRING>")
+public class JoinPTF extends ProcessTableFunction<Row> {
+  public void eval(
+      @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row left,
+      @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row right) {
+    if (left != null) {
+      collect(Row.of("LEFT: " + left));
+    }
+    if (right != null) {
+      collect(Row.of("RIGHT: " + right));
+    }
+  }
+}
+
+@Test
+void testMultiTable() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(JoinPTF.class)
+          .withTableArgument("left", DataTypes.of("ROW<id INT, name STRING>"))
+          .withPartitionBy("left", "id")
+          .withTableArgument("right", DataTypes.of("ROW<id INT, city STRING>"))
+          .withPartitionBy("right", "id")
+          .build()) {
+
+    // Use processElementForTable() to target specific tables
+    harness.processElementForTable("left", Row.of(1, "Alice"));
+    harness.processElementForTable("right", Row.of(1, "Berlin"));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output.get(0)).isEqualTo(Row.of(1, null, "LEFT: +I[1, Alice]"));
+    assertThat(output.get(1)).isEqualTo(Row.of(null, 1, "RIGHT: +I[1, Berlin]"));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Testing with Scalar Arguments
+
+Use `.withScalarArgument()` to configure scalar parameter values:
+
+{{< tabs "scalar-args" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<value INT>")
+public class FilterPTF extends ProcessTableFunction<Row> {
+  public void eval(
+      @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+      int threshold) {
+    int value = input.getFieldAs("value");
+    if (value > threshold) {
+      collect(Row.of(value));
+    }
+  }
+}
+
+@Test
+void testFilter() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+          .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+          .withScalarArgument("threshold", 50)  // Configure scalar value
+          .build()) {
+
+    harness.processElement(Row.of(30));
+    harness.processElement(Row.of(70));
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).containsExactly(Row.of(70));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+**Scalar-Only PTFs**: For PTFs with only scalar arguments, use `process()` to trigger evaluation:
+
+{{< tabs "scalar-only" >}}
+{{< tab "Java" >}}
+```java
+@DataTypeHint("ROW<sum INT>")
+public class AddPTF extends ProcessTableFunction<Row> {
+  public void eval(int a, int b) {
+    collect(Row.of(a + b));
+  }
+}
+
+@Test
+void testScalarOnly() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(AddPTF.class)
+          .withScalarArgument("a", 5)
+          .withScalarArgument("b", 7)
+          .build()) {
+
+    harness.process();  // Use process() instead of processElement()
+
+    List<Row> output = harness.getOutput();
+    assertThat(output).containsExactly(Row.of(12));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+#### Configuring Table Argument Types
+
+The harness supports two ways to specify table argument types:
+
+{{< tabs "type-config" >}}
+{{< tab "Java" >}}
+```java
+// Option 1: Inline type annotation using DataTypeHint
+@DataTypeHint("ROW<doubled INT>")
+public class InlineTypePTF extends ProcessTableFunction<Row> {
+  public void eval(
+      @ArgumentHint(
+        value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+        type = @DataTypeHint("ROW<value INT>")
+      ) Row input) {
+    int value = input.getFieldAs("value");
+    collect(Row.of(value * 2));
+  }
+}
+
+@Test
+void testInlineType() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class).build()) {
+
+    harness.processElement(Row.of(5));
+    assertThat(harness.getOutput()).containsExactly(Row.of(10));
+  }
+}
+
+// Option 2: Builder configuration
+@Test
+void testBuilderType() throws Exception {
+  try (ProcessTableFunctionTestHarness<Row> harness =
+      ProcessTableFunctionTestHarness.ofClass(DoublePTF.class)
+          .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+          .build()) {
+
+    harness.processElement(Row.of(5));
+    assertThat(harness.getOutput()).containsExactly(Row.of(10));
+  }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}

Review Comment:
   Yeah, that language is better. The first example is technically a way to specify the type for the harness (since the harness extracts the type from the system type inference for the input/output converters) but the user doesnt need to do anything in that case, so it's not really necessary to inform them



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "autophagy (via GitHub)" <gi...@apache.org>.
autophagy commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3256942930


##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -240,19 +240,64 @@ public void process() throws Exception {
 
         try {
             evalMethod.invoke(function, args);
+        } catch (IllegalArgumentException e) {

Review Comment:
   Ah right, yes, we do. This is unnecessary



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "autophagy (via GitHub)" <gi...@apache.org>.
autophagy commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3257186333


##########
flink-table/flink-table-test-utils/src/test/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarnessTest.java:
##########
@@ -0,0 +1,1021 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.api.DataTypes;
+import org.apache.flink.table.api.ValidationException;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class ProcessTableFunctionTestHarnessTest {
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PassthroughPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** Filter PTF for testing scalar argument handling. */
+    @DataTypeHint("ROW<value INT>")
+    public static class FilterPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer threshold) {
+            // Use named field access - converter enriches Row with field names
+            int value = input.getFieldAs("value");
+            if (value >= threshold) {
+                collect(input);
+            }
+        }
+    }
+
+    /** PTF for testing transformation of output types. */
+    @DataTypeHint("ROW<doubled INT, original INT>")
+    public static class DoublePTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2, value));
+        }
+    }
+
+    /** PTF with for testing table argument names set via argument hints. */
+    @DataTypeHint("ROW<value INT>")
+    public static class ExplicitNamePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "customName")
+                        Row actualParamName) {
+            collect(actualParamName);
+        }
+    }
+
+    /** PTF with inline type annotation - no builder config needed. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class InlineTypePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(
+                                value = ArgumentTrait.ROW_SEMANTIC_TABLE,
+                                type = @DataTypeHint("ROW<value INT>"))
+                        Row input) {
+            int value = (Integer) input.getField(0);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    @DataTypeHint("ROW<value INT>")
+    public static class PartitionedPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row input) {
+            collect(Row.of((Integer) input.getFieldAs("value")));
+        }
+    }
+
+    /**
+     * PTF with PASS_COLUMNS_THROUGH for validating that all input columns are prepended to output.
+     */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class PassColumnsThroughPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** PTF with OPTIONAL_PARTITION_BY for validating that partition setup can be omitted. */
+    @DataTypeHint("ROW<doubled INT>")
+    public static class OptionalPartitionPTF extends ProcessTableFunction<Row> {
+
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.OPTIONAL_PARTITION_BY
+                        })
+                        Row input) {
+            int value = (Integer) input.getField(1);
+            collect(Row.of(value * 2));
+        }
+    }
+
+    /** Simple POJO for testing structured type input/output. */
+    public static class User {
+        public String name;
+        public int age;
+
+        public User() {}
+
+        public User(String name, int age) {
+            this.name = name;
+            this.age = age;
+        }
+
+        @Override
+        public String toString() {
+            return "User{name='" + name + "', age=" + age + '}';
+        }
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o) {
+                return true;
+            }
+            if (o == null || getClass() != o.getClass()) {
+                return false;
+            }
+            User user = (User) o;
+            return age == user.age && java.util.Objects.equals(name, user.name);
+        }
+
+        @Override
+        public int hashCode() {
+            return java.util.Objects.hash(name, age);
+        }
+    }
+
+    /** PTF for testing structured type inputs. */
+    @DataTypeHint("ROW<name STRING, age INT>")
+    public static class UserPTF extends ProcessTableFunction<Row> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            if (user.age >= 18) {
+                collect(Row.of(user.name, user.age));
+            }
+        }
+    }
+
+    /** PTF that transforms structured type inputs and outputs. */
+    public static class UserTransformPTF extends ProcessTableFunction<User> {
+        public void eval(@ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) User user) {
+            User transformed = new User(user.name, user.age + 1);
+            collect(transformed);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "on_time". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgOnTimePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(value = ArgumentTrait.ROW_SEMANTIC_TABLE, name = "on_time")
+                        Row input) {
+            collect(input);
+        }
+    }
+
+    /** Invalid PTF - uses reserved argument name "uid". */
+    @DataTypeHint("ROW<value INT>")
+    public static class InvalidReservedArgUidPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input,
+                @ArgumentHint(ArgumentTrait.SCALAR) String uid) {
+            collect(input);
+        }
+    }
+
+    /** Multi-table PTF for validating multi-input processing. */
+    @DataTypeHint("ROW<output STRING>")
+    public static class MultiTableUnionPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /**
+     * Multi-table PTF with one POJO and one Row argument, for testing partitioning with structured
+     * types.
+     */
+    @DataTypeHint("ROW<source STRING, age INT>")
+    public static class MixedTypeMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) User userTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rowTable) {
+            if (userTable != null) {
+                collect(Row.of("USER", userTable.age));
+            }
+            if (rowTable != null) {
+                collect(Row.of("ROW", rowTable.getFieldAs("age")));
+            }
+        }
+    }
+
+    /**
+     * Invalid PTF - uses PASS_COLUMNS_THROUGH with multiple table arguments (not allowed per Flink
+     * docs).
+     */
+    @DataTypeHint("ROW<output STRING>")
+    public static class InvalidPassColumnsThroughMultiTablePTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint({
+                            ArgumentTrait.SET_SEMANTIC_TABLE,
+                            ArgumentTrait.PASS_COLUMNS_THROUGH
+                        })
+                        Row leftTable,
+                @ArgumentHint(ArgumentTrait.SET_SEMANTIC_TABLE) Row rightTable) {
+            if (leftTable != null) {
+                collect(Row.of("LEFT: " + leftTable));
+            }
+            if (rightTable != null) {
+                collect(Row.of("RIGHT: " + rightTable));
+            }
+        }
+    }
+
+    /** PTF with only scalar arguments, no tables. */
+    @DataTypeHint("ROW<sum INT>")
+    public static class ScalarOnlyPTF extends ProcessTableFunction<Row> {
+        public void eval(
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer a,
+                @ArgumentHint(ArgumentTrait.SCALAR) Integer b) {
+            collect(Row.of(a + b));
+        }
+    }
+
+    /** PTF with Context parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithContext extends ProcessTableFunction<Row> {
+        public void eval(Context ctx, @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    /** PTF with State parameter - should be rejected by test harness. */
+    @DataTypeHint("ROW<value INT>")
+    public static class PTFWithState extends ProcessTableFunction<Row> {
+        public static class CountState {
+            public long counter = 0L;
+        }
+
+        public void eval(
+                @StateHint CountState state,
+                @ArgumentHint(ArgumentTrait.ROW_SEMANTIC_TABLE) Row input) {
+            collect(input);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Builder Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testBuilderRejectsDuplicateScalarArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("threshold", 50)
+                                    .withScalarArgument("threshold", 100);
+                        });
+
+        assertThat(exception.getMessage()).contains("threshold");
+    }
+
+    @Test
+    void testBuilderRejectsDuplicateTableArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(MultiTableUnionPTF.class)
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, name STRING>"))
+                                    .withTableArgument(
+                                            "leftTable", DataTypes.of("ROW<id INT, value INT>"));
+                        });
+
+        assertThat(exception.getMessage()).contains("leftTable");
+    }
+
+    @Test
+    void testBuilderRejectsMixedDuplicateArguments() {
+        Exception exception =
+                assertThrows(
+                        IllegalArgumentException.class,
+                        () -> {
+                            ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                                    .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                                    .withScalarArgument("input", 42);
+                        });
+
+        assertThat(exception.getMessage()).contains("input");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentOnTime() {
+        // We should reject PTFs that use reserved argument name "on_time"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgOnTimePTF.class)
+                        .withTableArgument("on_time", DataTypes.of("ROW<id INT>"));
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("on_time");
+    }
+
+    @Test
+    void testBuilderRejectsReservedArgumentUid() {
+        // We should reject PTFs that use reserved argument name "uid"
+        ProcessTableFunctionTestHarness.Builder harnessBuilder =
+                ProcessTableFunctionTestHarness.ofClass(InvalidReservedArgUidPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<id INT>"))
+                        .withScalarArgument("uid", "my-id");
+
+        ValidationException exception =
+                assertThrows(
+                        ValidationException.class,
+                        () -> {
+                            harnessBuilder.build();
+                        });
+
+        assertThat(exception.getMessage())
+                .contains("Function signature must not declare system arguments")
+                .contains("uid");
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Configuration Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testExplicitNameTakesPrecedence() throws Exception {
+        // Verify that @ArgumentHint(name="customName") takes precedence over actual parameter
+        // name when processing elements and calling eval.
+
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ExplicitNamePTF.class)
+                        .withTableArgument("customName", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(42));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0).getField(0)).isEqualTo(42);
+            assertThat(output.get(1).getField(0)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testScalarOnlyPTF() throws Exception {
+        // Test scalar-only PTF with no table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(ScalarOnlyPTF.class)
+                        .withScalarArgument("a", 10)
+                        .withScalarArgument("b", 20)
+                        .build()) {
+
+            harness.process();
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0).getField(0)).isEqualTo(30);
+        }
+    }
+
+    @Test
+    void testInvokeRejectsTableArguments() throws Exception {
+        // Verify that invoke() rejects PTFs with table arguments
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50)
+                        .build()) {
+
+            Exception exception =
+                    assertThrows(
+                            IllegalStateException.class,
+                            () -> {
+                                harness.process();
+                            });
+
+            assertThat(exception.getMessage()).contains("process() is only for scalar-only PTFs");
+        }
+    }
+
+    @Test
+    void testTableProcessingWithScalarArgument() throws Exception {
+        // Test a PTF that uses a scalar parameter
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(FilterPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .withScalarArgument("threshold", 50) // Scalar argument: threshold = 50
+                        .build()) {
+
+            harness.processElement(Row.of(25));
+            harness.processElement(Row.of(75));
+            harness.processElement(Row.of(50));
+            harness.processElement(Row.of(10));
+            harness.processElement(Row.of(100));
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0).getField(0)).isEqualTo(75);
+            assertThat(output.get(1).getField(0)).isEqualTo(50);
+            assertThat(output.get(2).getField(0)).isEqualTo(100);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Argument Trait Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testProcessElementWithRowKind() throws Exception {
+        // Verify RowKind is preserved through processing (ROW_SEMANTIC_TABLE)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(RowKind.INSERT, 10);
+            harness.processElement(RowKind.UPDATE_BEFORE, 15);
+            harness.processElement(RowKind.UPDATE_AFTER, 20);
+            harness.processElement(RowKind.DELETE, 30);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+            assertThat(output.get(0).getKind()).isEqualTo(RowKind.INSERT);
+            assertThat(output.get(0).getField(0)).isEqualTo(10);
+            assertThat(output.get(1).getKind()).isEqualTo(RowKind.UPDATE_BEFORE);
+            assertThat(output.get(1).getField(0)).isEqualTo(15);
+            assertThat(output.get(2).getKind()).isEqualTo(RowKind.UPDATE_AFTER);
+            assertThat(output.get(2).getField(0)).isEqualTo(20);
+            assertThat(output.get(3).getKind()).isEqualTo(RowKind.DELETE);
+            assertThat(output.get(3).getField(0)).isEqualTo(30);
+        }
+    }
+
+    @Test
+    void testPassColumnsThroughTrait() throws Exception {
+        // Verify PASS_COLUMNS_THROUGH prepends ALL input columns (not just partition keys)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassColumnsThroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 10, 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("B", 20, 40));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithoutPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY allows omitting partition configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("B", 20));
+            harness.processElement(Row.of("C", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of(20));
+            assertThat(output.get(1)).isEqualTo(Row.of(40));
+            assertThat(output.get(2)).isEqualTo(Row.of(60));
+        }
+    }
+
+    @Test
+    void testOptionalPartitionByWithPartition() throws Exception {
+        // Verify OPTIONAL_PARTITION_BY still works when partition is configured
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(OptionalPartitionPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key")
+                        .build()) {
+
+            harness.processElement(Row.of("A", 10));
+            harness.processElement(Row.of("A", 5));
+            harness.processElement(Row.of("B", 20));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+
+            assertThat(output.get(0)).isEqualTo(Row.of("A", 20));
+            assertThat(output.get(1)).isEqualTo(Row.of("A", 10));
+            assertThat(output.get(2)).isEqualTo(Row.of("B", 40));
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Data Type Conversion Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testNamedRowFieldOrdering() throws Exception {
+        // Test what happens when Row field order differs from DataType schema order
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row rowA = Row.withNames();
+            rowA.setField("value", 100);
+            rowA.setField("user", "Alice");
+
+            harness.processElement(rowA);
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+
+            // Positional access follows schema order
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(100);
+        }
+    }
+
+    @Test
+    void testPositionalRowWithWrongTypeOrder() throws Exception {
+        // Verify that type mismatches are caught when Row values don't match schema types
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PassthroughPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<user STRING, value INT>"))
+                        .build()) {
+
+            Row wrongOrderRow = Row.of(10, "Alice");
+
+            Exception exception =
+                    assertThrows(
+                            ClassCastException.class, () -> harness.processElement(wrongOrderRow));
+
+            assertThat(exception.getMessage()).contains("Integer");
+            assertThat(exception.getMessage()).contains("String");
+            assertThat(exception.getMessage()).contains("cannot be cast");
+        }
+    }
+
+    @Test
+    void testStructuredTypeInput() throws Exception {
+        // Test that a PTF can declare an input type as a structured type,
+        // and that the harness can handle the conversion from Row into
+        // that type.
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+            harness.processElement(Row.of("Bob", 17));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            Row result = output.get(0);
+            assertThat(result.getField(0)).isEqualTo("Alice");
+            assertThat(result.getField(1)).isEqualTo(25);
+        }
+    }
+
+    @Test
+    void testStructuredTypeInputAndOutput() throws Exception {
+        // Test PTF with structured type inputs and outputs
+        try (ProcessTableFunctionTestHarness<User> harness =
+                ProcessTableFunctionTestHarness.ofClass(UserTransformPTF.class)
+                        .withTableArgument("user")
+                        .build()) {
+
+            harness.processElement(Row.of("Alice", 25));
+
+            List<User> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+
+            User result = output.get(0);
+            assertThat(result.getClass()).isEqualTo(User.class);
+            assertThat(result.name).isEqualTo("Alice");
+            assertThat(result.age).isEqualTo(26);
+        }
+    }
+
+    @Test
+    void testInlineTypeAnnotation() throws Exception {
+        // Verify that PTFs can declare table argument types via @ArgumentHint(type = ...)
+        // without needing .withTableArgument() configuration
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class).build()) {
+
+            harness.processElement(Row.of(5));
+            harness.processElement(Row.of(10));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(2);
+            assertThat(output.get(0)).isEqualTo(Row.of(10));
+            assertThat(output.get(1)).isEqualTo(Row.of(20));
+        }
+    }
+
+    @Test
+    void testInlineTypeMatchesBuilderConfig() throws Exception {
+        // Verify that when both inline annotation and builder config are provided with matching
+        // types, the harness builds successfully
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(InlineTypePTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<value INT>"))
+                        .build()) {
+
+            harness.processElement(Row.of(7));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(1);
+            assertThat(output.get(0)).isEqualTo(Row.of(14));
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Partitioning Tests
+    // -------------------------------------------------------------------------
+
+    @Test
+    void testSetSemanticWithPartitionByName() throws Exception {
+        // Verify set-semantic table with partition configuration by column name
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument("input", DataTypes.of("ROW<key STRING, value INT>"))
+                        .withPartitionBy("input", "key") // Partition by "key" column name
+                        .build()) {
+
+            harness.processElement(Row.of("X", 10));
+            harness.processElement(Row.of("Y", 20));
+            harness.processElement(Row.of("X", 30));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(3);
+            assertThat(output.get(0)).isEqualTo(Row.of("X", 10));
+            assertThat(output.get(1)).isEqualTo(Row.of("Y", 20));
+            assertThat(output.get(2)).isEqualTo(Row.of("X", 30));
+        }
+    }
+
+    @Test
+    void testSetSemanticWithMultiplePartitionColumns() throws Exception {
+        // Verify composite partition key (multiple columns)
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument(
+                                "input",
+                                DataTypes.of("ROW<region STRING, country STRING, value INT>"))
+                        .withPartitionBy("input", "region", "country")
+                        .build()) {
+
+            harness.processElement(Row.of("EU", "DE", 100));
+            harness.processElement(Row.of("EU", "DE", 200));
+            harness.processElement(Row.of("EU", "FR", 300));
+            harness.processElement(Row.of("US", "NY", 400));
+
+            List<Row> output = harness.getOutput();
+            assertThat(output).hasSize(4);
+            assertThat(output.get(0)).isEqualTo(Row.of("EU", "DE", 100));
+            assertThat(output.get(1)).isEqualTo(Row.of("EU", "DE", 200));
+            assertThat(output.get(2)).isEqualTo(Row.of("EU", "FR", 300));
+            assertThat(output.get(3)).isEqualTo(Row.of("US", "NY", 400));
+        }
+    }
+
+    @Test
+    void testSetSemanticWithSelectivePartitioning() throws Exception {
+        // Verify that only partition columns are automatically included in output
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(PartitionedPTF.class)
+                        .withTableArgument(
+                                "input",
+                                DataTypes.of(
+                                        "ROW<id INT, region STRING, country STRING, city STRING, value INT>"))
+                        .withPartitionBy("input", "region")
+                        .build()) {
+
+            harness.processElement(Row.of(1, "EU", "DE", "Berlin", 100));
+            harness.processElement(Row.of(4, "US", "CA", "LA", 200));
+
+            List<Row> output = harness.getOutput();
+
+            assertThat(output.get(0)).isEqualTo(Row.of("EU", 100));
+            assertThat(output.get(1)).isEqualTo(Row.of("US", 200));
+        }
+    }
+
+    @Test
+    void testMultipleSetSemanticTablesWithMatchingPartitionKeys() throws Exception {
+        try (ProcessTableFunctionTestHarness<Row> harness =
+                ProcessTableFunctionTestHarness.ofClass(MultiTableUnionPTF.class)
+                        .withTableArgument("leftTable", DataTypes.of("ROW<name STRING, score INT>"))
+                        .withPartitionBy("leftTable", "name")
+                        .withTableArgument(
+                                "rightTable", DataTypes.of("ROW<name STRING, city STRING>"))
+                        .withPartitionBy("rightTable", "name")

Review Comment:
   You're right, I hadn't considered this. Looking at the existing `PROCESS_MULTI_INPUT` test in `ProcessTableFunctionTestPrograms`, it looks like the columns get renamed. Partitioning by two `name` column returns a row with a `name` and a `name0` column. I'll update the harness to mirror this



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "fhueske (via GitHub)" <gi...@apache.org>.
fhueske merged PR #27928:
URL: https://github.com/apache/flink/pull/27928


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "fhueske (via GitHub)" <gi...@apache.org>.
fhueske commented on code in PR #27928:
URL: https://github.com/apache/flink/pull/27928#discussion_r3232417409


##########
flink-table/flink-table-test-utils/src/main/java/org/apache/flink/table/runtime/functions/ProcessTableFunctionTestHarness.java:
##########
@@ -0,0 +1,1214 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.flink.table.runtime.functions;
+
+import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.table.annotation.ArgumentTrait;
+import org.apache.flink.table.annotation.StateHint;
+import org.apache.flink.table.catalog.DataTypeFactory;
+import org.apache.flink.table.data.conversion.DataStructureConverter;
+import org.apache.flink.table.data.conversion.DataStructureConverters;
+import org.apache.flink.table.functions.FunctionContext;
+import org.apache.flink.table.functions.FunctionKind;
+import org.apache.flink.table.functions.ProcessTableFunction;
+import org.apache.flink.table.types.AbstractDataType;
+import org.apache.flink.table.types.DataType;
+import org.apache.flink.table.types.FieldsDataType;
+import org.apache.flink.table.types.inference.StaticArgument;
+import org.apache.flink.table.types.inference.StaticArgumentTrait;
+import org.apache.flink.table.types.inference.SystemTypeInference;
+import org.apache.flink.table.types.inference.TypeInference;
+import org.apache.flink.table.types.logical.LogicalType;
+import org.apache.flink.table.types.logical.RowType;
+import org.apache.flink.table.types.logical.StructuredType;
+import org.apache.flink.table.types.utils.TypeConversions;
+import org.apache.flink.types.Row;
+import org.apache.flink.types.RowKind;
+import org.apache.flink.util.Collector;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.apache.flink.util.Preconditions.checkArgument;
+import static org.apache.flink.util.Preconditions.checkNotNull;
+import static org.apache.flink.util.Preconditions.checkState;
+
+/**
+ * Test harness for {@link ProcessTableFunction}.
+ *
+ * <p>Provides a fluent builder API for configuring and testing ProcessTableFunctions (PTFs) with
+ * table and scalar arguments, lifecycle management, and output collection.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * ProcessTableFunctionTestHarness<Row> harness =
+ *     ProcessTableFunctionTestHarness.ofClass(MyPTF.class)
+ *         .withTableArgument("input", DataTypes.of("ROW<id INT, name STRING>"))
+ *         .withScalarArgument("threshold", 100)
+ *         .build();
+ *
+ * harness.processElement(Row.of(1, "Alice"));
+ * harness.processElement(Row.of(2, "Bob"));
+ *
+ * List<Row> output = harness.getOutput();
+ * }</pre>
+ */
+@PublicEvolving
+public class ProcessTableFunctionTestHarness<OUT> implements AutoCloseable {
+
+    private final ProcessTableFunction<OUT> function;
+    private final FunctionContext functionContext;
+    private final List<OUT> output;
+    private boolean isOpen;
+    private final HarnessCollector collector;
+
+    private final String defaultTableArgument;
+    private final Method evalMethod;
+    private final List<ArgumentInfo> arguments;
+
+    private final Map<String, ArgumentInfo> argumentsByName;
+    private final boolean isSingleTableFunction;
+    private final Map<String, Object> scalarArgumentValues;
+
+    private final boolean hasTableArguments;
+    private final Map<String, DataStructureConverter<Object, Object>> inputConverters;
+    private final Map<String, DataStructureConverter<Object, Object>> outputConverters;
+
+    private ProcessTableFunctionTestHarness(
+            ProcessTableFunction<OUT> function,
+            FunctionContext functionContext,
+            String defaultTableArgument,
+            Method evalMethod,
+            List<ArgumentInfo> arguments,
+            Map<String, ArgumentInfo> argumentsByName,
+            boolean isSingleTableFunction,
+            Map<String, Object> scalarArgumentValues,
+            Map<String, DataStructureConverter<Object, Object>> inputConverters,
+            Map<String, DataStructureConverter<Object, Object>> outputConverters)
+            throws Exception {
+        this.function = function;
+        this.functionContext = functionContext;
+        this.defaultTableArgument = defaultTableArgument;
+        this.evalMethod = evalMethod;
+        this.arguments = arguments;
+        this.argumentsByName = argumentsByName;
+        this.isSingleTableFunction = isSingleTableFunction;
+        this.scalarArgumentValues = scalarArgumentValues;
+        this.hasTableArguments = arguments.stream().anyMatch(arg -> arg.isTableArgument);
+        this.inputConverters = inputConverters;
+        this.outputConverters = outputConverters;
+        this.output = new ArrayList<>();
+        this.collector = new HarnessCollector();
+        this.isOpen = false;
+
+        openFunction();
+    }
+
+    /** Creates a new harness builder for the given ProcessTableFunction class. */
+    public static <OUT> Builder<OUT> ofClass(
+            Class<? extends ProcessTableFunction<OUT>> functionClass) {
+        return new Builder<>(functionClass);
+    }
+
+    private void openFunction() throws Exception {
+        function.open(functionContext);
+        function.setCollector(collector);
+        isOpen = true;
+    }
+
+    @Override
+    public void close() throws Exception {
+        if (isOpen) {
+            function.close();
+            isOpen = false;
+        }
+    }
+
+    /**
+     * Process a single element for the default table argument.
+     *
+     * <p>For PTFs with a single table argument, this processes one row. For multiple table
+     * arguments, use {@link #processElementForTable(String, Row)}.
+     */
+    public void processElement(Row row) throws Exception {
+        if (!isSingleTableFunction) {
+            throw new IllegalStateException(
+                    "PTF has multiple table arguments. Use processElementForTable(argumentName, row) "
+                            + "to specify which table argument should receive the row.");
+        }
+
+        processElementForTable(defaultTableArgument, row);
+    }
+
+    /** Process a single element constructed from values. */
+    public void processElement(Object... values) throws Exception {
+        processElement(Row.of(values));
+    }
+
+    /** Process a single element with a specific RowKind. */
+    public void processElement(RowKind rowKind, Object... values) throws Exception {
+        processElement(Row.ofKind(rowKind, values));
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Row row) throws Exception {
+        checkState(isOpen, "Harness not open");
+        checkNotNull(tableArgument, "tableArgument must not be null");
+
+        ArgumentInfo tableArg = argumentsByName.get(tableArgument);
+        if (tableArg == null) {
+            throw new IllegalArgumentException("Unknown table argument: " + tableArgument);
+        }
+        invokeEval(tableArg, row);
+    }
+
+    /** Process a single element for a specific table argument. */
+    public void processElementForTable(String tableArgument, Object... values) throws Exception {
+        processElementForTable(tableArgument, Row.of(values));
+    }
+
+    /** Process a single element for a specific table argument with RowKind. */
+    public void processElementForTable(String tableArgument, RowKind rowKind, Object... values)
+            throws Exception {
+        processElementForTable(tableArgument, Row.ofKind(rowKind, values));
+    }
+
+    /**
+     * Processes the PTF's eval() method with scalar arguments only.
+     *
+     * <p>This method is specifically for scalar-only PTFs (PTFs with only scalar arguments and no
+     * table arguments). For PTFs that accept table arguments, use {@link #processElement(Row)} or
+     * {@link #processElementForTable(String, Row)} instead.
+     *
+     * @throws IllegalStateException if the PTF has any table arguments
+     * @throws Exception if the eval() invocation fails
+     */
+    public void process() throws Exception {
+        checkState(isOpen, "Harness not open");
+
+        if (hasTableArguments) {
+            throw new IllegalStateException(
+                    "process() is only for scalar-only PTFs. This PTF has table arguments. "
+                            + "Use processElement() or processElementForTable() instead.");
+        }
+
+        // Clear collector context since there's no active table argument
+        collector.setContext(null, null);
+
+        Object[] args = new Object[arguments.size()];
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+            if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected non-scalar argument at position " + i + ": " + arg.name);
+            }
+        }
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during scalar-only PTF eval() invocation. "
+                                                + "Scalar arguments: %s",
+                                        scalarArgumentValues)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /** Returns all collected output rows. */
+    public List<OUT> getOutput() {
+        return List.copyOf(output);
+    }
+
+    /** Clears all collected output. */
+    public void clearOutput() {
+        output.clear();
+    }
+
+    /**
+     * Given a target table argument and a row to process, construct the right set of arguments for
+     * the PTF's eval function and attempt to invoke it.
+     */
+    private void invokeEval(ArgumentInfo activeTableArg, Row activeRow) throws Exception {
+        // Set collector context so it can prepend columns if needed
+        collector.setContext(activeTableArg, activeRow);
+
+        Object[] args = new Object[arguments.size()];
+
+        for (int i = 0; i < arguments.size(); i++) {
+            ArgumentInfo arg = arguments.get(i);
+
+            if (arg.isTableArgument && arg.name.equals(activeTableArg.name)) {
+                // If the argument is the active table argument, first convert the input row
+                // to an internal RowData type, and then convert the RowData to type that the
+                // argument expects. For Rows, this will structure the Row based on the table
+                // argument structure. Otherwise, for POJOs, it will pass the expected POJO to eval.
+
+                DataStructureConverter<Object, Object> inputConverter =
+                        inputConverters.get(arg.name);
+                DataStructureConverter<Object, Object> outputConverter =
+                        outputConverters.get(arg.name);
+
+                args[i] =
+                        outputConverter.toExternalOrNull(
+                                inputConverter.toInternalOrNull(activeRow));
+
+            } else if (arg.isScalar) {
+                args[i] = scalarArgumentValues.get(arg.name);
+
+            } else if (arg.isTableArgument) {
+                // Inactive table arguments receive null
+                args[i] = null;
+            } else {
+                throw new IllegalStateException(
+                        "Unexpected argument type at position " + i + ": " + arg.name);
+            }
+        }
+
+        try {
+            evalMethod.invoke(function, args);
+        } catch (InvocationTargetException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof Exception) {
+                Exception userException = (Exception) cause;
+                String partitionInfo =
+                        activeTableArg.partitionColumnNames != null
+                                        && activeTableArg.partitionColumnNames.length > 0
+                                ? String.format(
+                                        ", partition columns: %s",
+                                        Arrays.toString(activeTableArg.partitionColumnNames))
+                                : ", no partitioning";
+                userException.addSuppressed(
+                        new Exception(
+                                String.format(
+                                        "Exception occurred during PTF eval() while processing table argument '%s'%s. "
+                                                + "Input row: %s",
+                                        activeTableArg.name, partitionInfo, activeRow)));
+                throw userException;
+            } else {
+                throw new RuntimeException("Error invoking PTF eval() method", e);
+            }
+        }
+    }
+
+    /**
+     * Collector implementation that stores output in the harness.
+     *
+     * <p>For SET_SEMANTIC_TABLE arguments, automatically prepends partition key columns to the PTF
+     * output. If the argument has PASS_COLUMNS_THROUGH trait, prepends all input columns.
+     */
+    private class HarnessCollector implements Collector<OUT> {
+        // Context set before each eval() invocation
+        private ArgumentInfo activeTableArg;
+        private Row activeRow;
+
+        void setContext(ArgumentInfo tableArg, Row row) {
+            this.activeTableArg = tableArg;
+            this.activeRow = row;
+        }
+
+        @Override
+        public void collect(OUT record) {
+            if (activeTableArg == null || !activeTableArg.isTableArgument) {
+                output.add(record);
+                return;
+            }
+
+            if (activeTableArg.hasPassColumnsThrough) {
+                output.add(prependAllColumns(record));
+            } else if (activeTableArg.isSetSemantic
+                    && activeTableArg.partitionColumnNames != null) {
+                output.add(prependPartitionKeys(record));
+            } else {
+                output.add(record);
+            }
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependPartitionKeys(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend partition keys to non-Row output type: "
+                                + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+
+            // For multi-table PTFs, prepend partition keys from ALL SET_SEMANTIC_TABLE arguments
+            // Active table contributes actual partition key values, inactive tables contribute
+            // nulls
+            int totalPartitionKeyCount = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    totalPartitionKeyCount += arg.partitionColumnNames.length;
+                }
+            }
+
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = totalPartitionKeyCount + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            // Prepend partition key values from all SET_SEMANTIC_TABLE arguments
+            int resultIndex = 0;
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    boolean isActive = arg.name.equals(activeTableArg.name);
+
+                    for (String columnName : arg.partitionColumnNames) {
+                        if (isActive) {
+                            int columnIndex = getFieldIndex(arg.dataType, columnName);
+                            result.setField(resultIndex++, activeRow.getField(columnIndex));
+                        } else {
+                            result.setField(resultIndex++, null);
+                        }
+                    }
+                }
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(resultIndex++, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        /** Helper to get field index by name from a DataType. */
+        private int getFieldIndex(DataType dataType, String fieldName) {
+            LogicalType logicalType = dataType.getLogicalType();
+
+            if (logicalType instanceof RowType) {
+                RowType rowType = (RowType) logicalType;
+                int index = 0;
+                for (RowType.RowField field : rowType.getFields()) {
+                    if (field.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            } else if (logicalType instanceof StructuredType) {
+                StructuredType structuredType = (StructuredType) logicalType;
+                int index = 0;
+                for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                    if (attr.getName().equals(fieldName)) {
+                        return index;
+                    }
+                    index++;
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format("Field '%s' not found in type %s", fieldName, dataType));
+        }
+
+        @SuppressWarnings("unchecked")
+        private OUT prependAllColumns(OUT ptfOutput) {
+            if (!(ptfOutput instanceof Row)) {
+                throw new IllegalStateException(
+                        "Cannot prepend columns to non-Row output type: " + ptfOutput.getClass());
+            }
+
+            Row ptfRow = (Row) ptfOutput;
+            int inputArity = activeRow.getArity();
+            int ptfOutputArity = ptfRow.getArity();
+            int totalArity = inputArity + ptfOutputArity;
+
+            Row result = new Row(ptfRow.getKind(), totalArity);
+
+            for (int i = 0; i < inputArity; i++) {
+                result.setField(i, activeRow.getField(i));
+            }
+
+            for (int i = 0; i < ptfOutputArity; i++) {
+                result.setField(inputArity + i, ptfRow.getField(i));
+            }
+
+            return (OUT) result;
+        }
+
+        @Override
+        public void close() {}
+    }
+
+    /**
+     * Builder for {@link ProcessTableFunctionTestHarness}.
+     *
+     * @param <OUT> The output type of the ProcessTableFunction
+     */
+    @PublicEvolving
+    public static class Builder<OUT> {
+        private final Class<? extends ProcessTableFunction<OUT>> functionClass;
+
+        private final LinkedHashMap<String, ScalarArgumentConfiguration> scalarArgs =
+                new LinkedHashMap<>();
+        private final LinkedHashMap<String, TableArgumentConfiguration> tableArgs =
+                new LinkedHashMap<>();
+        private final Map<String, PartitionConfiguration> partitionConfigs = new HashMap<>();
+
+        private Builder(Class<? extends ProcessTableFunction<OUT>> functionClass) {
+            this.functionClass = checkNotNull(functionClass, "functionClass must not be null");
+        }
+
+        // ---------------------------------------------------------------------
+        // Table & Scalar Arguments
+        // ---------------------------------------------------------------------
+
+        /**
+         * Configures a table argument with its schema (named argument).
+         *
+         * <p>Use this for dynamic tables that receive elements during the test. Elements are
+         * provided via {@link #processElement(Row)} or {@link #processElementForTable(String,
+         * Row)}.
+         *
+         * @param argumentName The table argument name
+         * @param dataType The schema/structure of the table
+         */
+        public Builder<OUT> withTableArgument(String argumentName, AbstractDataType<?> dataType) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(dataType, "dataType must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            config.explicitType = dataType;
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a table argument without an explicit schema.
+         *
+         * <p>Use this for structured type arguments where the type can be inferred from the PTF's
+         * eval() signature. For Row arguments, use {@link #withTableArgument(String,
+         * AbstractDataType)} with an explicit schema.
+         *
+         * @param argumentName The table argument name
+         */
+        public Builder<OUT> withTableArgument(String argumentName) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Argument already configured as scalar: " + argumentName);
+            }
+
+            if (tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Table argument already configured: " + argumentName);
+            }
+
+            TableArgumentConfiguration config = new TableArgumentConfiguration();
+            tableArgs.put(argumentName, config);
+            return this;
+        }
+
+        /**
+         * Configures a scalar (non-table) argument for the PTF's eval() method.
+         *
+         * <p>Scalar arguments are constant values passed to every eval() invocation, such as
+         * thresholds, multipliers, or configuration parameters.
+         *
+         * @param argumentName Must match the parameter name in eval() or the @ArgumentHint name
+         * @param value The value to pass for this argument in all eval() calls
+         */
+        public Builder<OUT> withScalarArgument(String argumentName, Object value) {
+            checkNotNull(argumentName, "argumentName must not be null");
+
+            if (scalarArgs.containsKey(argumentName) || tableArgs.containsKey(argumentName)) {
+                throw new IllegalArgumentException("Argument already configured: " + argumentName);
+            }
+
+            ScalarArgumentConfiguration config = new ScalarArgumentConfiguration(value);
+            scalarArgs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Partitioning
+        // ---------------------------------------------------------------------
+
+        /**
+         * Specifies partition columns for a set semantic table.
+         *
+         * @param argumentName The table argument name
+         * @param columnNames The partition column names
+         * @return This builder
+         */
+        public Builder<OUT> withPartitionBy(String argumentName, String... columnNames) {
+            checkNotNull(argumentName, "argumentName must not be null");
+            checkNotNull(columnNames, "columnNames must not be null");
+            checkArgument(columnNames.length > 0, "Must specify at least one column");
+
+            if (partitionConfigs.containsKey(argumentName)) {
+                throw new IllegalArgumentException(
+                        "Partition config already exists for: " + argumentName);
+            }
+
+            PartitionConfiguration config = new PartitionConfiguration(columnNames);
+            partitionConfigs.put(argumentName, config);
+            return this;
+        }
+
+        // ---------------------------------------------------------------------
+        // Build
+        // ---------------------------------------------------------------------
+
+        /**
+         * Builds the test harness.
+         *
+         * <p>This instantiates the PTF, validates configuration via type inference, creates the
+         * FunctionContext, and opens the function.
+         *
+         * @return The configured test harness
+         * @throws Exception If instantiation or opening fails
+         */
+        public ProcessTableFunctionTestHarness<OUT> build() throws Exception {
+            ProcessTableFunction<OUT> function = instantiateFunction();
+
+            List<ArgumentInfo> arguments = extractAndValidateTypeInference(function);
+
+            FunctionContext functionContext =
+                    new FunctionContext(null, Thread.currentThread().getContextClassLoader(), null);
+
+            Method evalMethod = findEvalMethod();
+
+            validateEvalMethodSupported(evalMethod, arguments);
+            validatePartitionConsistency(arguments);
+
+            // In cases where PTFs have only a single table argument, set it as a default
+            // and mark as a single table function so that processElement without specifying
+            // a table argument can be used.
+            String defaultTableArg = null;
+            boolean isSingleTableFunction = false;
+
+            List<ArgumentInfo> tableArguments = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    tableArguments.add(arg);
+                }
+            }
+
+            if (tableArguments.size() == 1) {
+                defaultTableArg = tableArguments.get(0).name;
+                isSingleTableFunction = true;
+            }
+
+            Map<String, DataStructureConverter<Object, Object>> inputConverters = new HashMap<>();
+            Map<String, DataStructureConverter<Object, Object>> outputConverters = new HashMap<>();
+            createConverters(arguments, inputConverters, outputConverters);
+
+            Map<String, ArgumentInfo> argumentsByName = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.name != null) {
+                    argumentsByName.put(arg.name, arg);
+                }
+            }
+
+            return new ProcessTableFunctionTestHarness<>(
+                    function,
+                    functionContext,
+                    defaultTableArg,
+                    evalMethod,
+                    arguments,
+                    argumentsByName,
+                    isSingleTableFunction,
+                    extractScalarValues(arguments),
+                    inputConverters,
+                    outputConverters);
+        }
+
+        /** Extracts scalar values from configs, creating a map keyed by argument name. */
+        private Map<String, Object> extractScalarValues(List<ArgumentInfo> arguments) {
+            Map<String, Object> values = new HashMap<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isScalar) {
+                    ScalarArgumentConfiguration config = scalarArgs.get(arg.name);
+                    if (config != null) {
+                        values.put(arg.name, config.value);
+                    }
+                }
+            }
+            return values;
+        }
+
+        /**
+         * Creates and initializes data structure converters for all table arguments.
+         *
+         * <p>For Row types, both input and output converters are the same (between Row and
+         * RowData).
+         *
+         * <p>For structured types, input converter uses Row types (Row to RowData), and the output
+         * converter uses the structured type.
+         */
+        private void createConverters(
+                List<ArgumentInfo> arguments,
+                Map<String, DataStructureConverter<Object, Object>> inputConverters,
+                Map<String, DataStructureConverter<Object, Object>> outputConverters) {
+            ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isTableArgument) {
+                    String converterKey = arg.name;
+
+                    LogicalType logicalType = arg.dataType.getLogicalType();
+                    boolean isStructuredType =
+                            logicalType instanceof StructuredType
+                                    && ((StructuredType) logicalType)
+                                            .getImplementationClass()
+                                            .isPresent();
+
+                    if (isStructuredType) {
+                        StructuredType structuredType = (StructuredType) logicalType;
+                        List<RowType.RowField> rowFields = new ArrayList<>();
+                        for (StructuredType.StructuredAttribute attr :
+                                structuredType.getAttributes()) {
+                            rowFields.add(new RowType.RowField(attr.getName(), attr.getType()));
+                        }
+                        RowType rowType = new RowType(logicalType.isNullable(), rowFields);
+                        DataType rowDataType = TypeConversions.fromLogicalToDataType(rowType);
+
+                        DataStructureConverter<Object, Object> inputConverter =
+                                DataStructureConverters.getConverter(rowDataType);
+                        inputConverter.open(classLoader);
+
+                        DataStructureConverter<Object, Object> outputConverter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        outputConverter.open(classLoader);
+
+                        inputConverters.put(converterKey, inputConverter);
+                        outputConverters.put(converterKey, outputConverter);
+                    } else {
+                        DataStructureConverter<Object, Object> converter =
+                                DataStructureConverters.getConverter(arg.dataType);
+                        converter.open(classLoader);
+
+                        inputConverters.put(converterKey, converter);
+                        outputConverters.put(converterKey, converter);
+                    }
+                }
+            }
+        }
+
+        private Method findEvalMethod() throws NoSuchMethodException {
+            Method[] methods = functionClass.getMethods();
+            Method evalMethod = null;
+            int evalMethodCount = 0;
+
+            for (Method method : methods) {
+                if (method.getName().equals("eval")) {
+                    evalMethod = method;
+                    evalMethodCount++;
+                }
+            }
+
+            if (evalMethodCount == 0) {
+                throw new NoSuchMethodException(
+                        "No eval() method found in " + functionClass.getSimpleName());
+            } else if (evalMethodCount > 1) {
+                throw new IllegalStateException(
+                        "Multiple eval() methods found in "
+                                + functionClass.getSimpleName()
+                                + ". ProcessTableFunction must have exactly one eval() method.");
+            } else {
+                return evalMethod;
+            }
+        }
+
+        /**
+         * Validates that the eval() method doesn't use unsupported features. Temporary, until state
+         * and context is supported.
+         */
+        private void validateEvalMethodSupported(Method evalMethod, List<ArgumentInfo> arguments) {
+            Parameter[] parameters = evalMethod.getParameters();
+
+            for (int i = 0; i < parameters.length; i++) {
+                Parameter param = parameters[i];
+                Class<?> paramType = param.getType();
+
+                if (ProcessTableFunction.Context.class.isAssignableFrom(paramType)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support Context parameters. "
+                                            + "Found Context parameter at position %d in eval() method. ",
+                                    i));
+                }
+
+                if (param.isAnnotationPresent(StateHint.class)) {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "ProcessTableFunctionTestHarness does not yet support state parameters. "
+                                            + "Found @StateHint parameter at position %d in eval() method. ",
+                                    i));
+                }
+            }
+
+            // Parameter count should also match our arguments list
+            if (parameters.length != arguments.size()) {
+                throw new IllegalStateException(
+                        String.format(
+                                "Parameter count mismatch: eval() has %d parameters but only %d arguments were extracted. "
+                                        + "This may indicate missing @ArgumentHint annotations.",
+                                parameters.length, arguments.size()));
+            }
+        }
+
+        /**
+         * Validates that all SET_SEMANTIC_TABLE arguments with partitioning use consistent
+         * partitioning. All such arguments must have the same number of partition columns with
+         * matching data types.
+         */
+        private void validatePartitionConsistency(List<ArgumentInfo> arguments) {
+            List<ArgumentInfo> partitionedTables = new ArrayList<>();
+            for (ArgumentInfo arg : arguments) {
+                if (arg.isSetSemantic && arg.partitionColumnNames != null) {
+                    partitionedTables.add(arg);
+                }
+            }
+
+            if (partitionedTables.size() <= 1) {
+                return;
+            }
+
+            ArgumentInfo first = partitionedTables.get(0);
+            int expectedPartitionColumnCount = first.partitionColumnNames.length;
+
+            for (int i = 1; i < partitionedTables.size(); i++) {
+                ArgumentInfo current = partitionedTables.get(i);
+
+                if (current.partitionColumnNames.length != expectedPartitionColumnCount) {
+                    throw new IllegalArgumentException(
+                            String.format(
+                                    "Inconsistent partitioning: Table argument '%s' has %d partition column(s), "
+                                            + "but table argument '%s' has %d partition column(s). "
+                                            + "All SET_SEMANTIC_TABLE arguments must use consistent partitioning "
+                                            + "(same number of columns and matching data types).",
+                                    first.name,
+                                    expectedPartitionColumnCount,
+                                    current.name,
+                                    current.partitionColumnNames.length));
+                }
+
+                // Check that partition column types match
+                for (int colIdx = 0; colIdx < expectedPartitionColumnCount; colIdx++) {
+                    String firstColName = first.partitionColumnNames[colIdx];
+                    String currentColName = current.partitionColumnNames[colIdx];
+                    DataType firstColType = extractPartitionColumnType(first, firstColName);
+                    DataType currentColType = extractPartitionColumnType(current, currentColName);
+
+                    if (!firstColType.getLogicalType().equals(currentColType.getLogicalType())) {
+                        throw new IllegalArgumentException(
+                                String.format(
+                                        "Inconsistent partitioning: Partition column '%s' of table argument '%s' "
+                                                + "has type %s, but partition column '%s' of table argument '%s' "
+                                                + "has type %s. All SET_SEMANTIC_TABLE arguments must use "
+                                                + "consistent partitioning (same number of columns and matching data types).",
+                                        firstColName,
+                                        first.name,
+                                        firstColType,
+                                        currentColName,
+                                        current.name,
+                                        currentColType));
+                    }
+                }
+            }
+        }
+
+        private DataType extractPartitionColumnType(ArgumentInfo arg, String columnName) {
+            if (arg.dataType instanceof FieldsDataType) {
+                FieldsDataType fieldsDataType = (FieldsDataType) arg.dataType;
+                LogicalType logicalType = fieldsDataType.getLogicalType();
+                List<DataType> fieldDataTypes = fieldsDataType.getChildren();
+
+                if (logicalType instanceof RowType) {
+                    RowType rowType = (RowType) logicalType;
+                    int fieldIndex = 0;
+                    for (RowType.RowField field : rowType.getFields()) {
+                        if (field.getName().equals(columnName)) {
+                            return fieldDataTypes.get(fieldIndex);
+                        }
+                        fieldIndex++;
+                    }
+                } else if (logicalType instanceof StructuredType) {
+                    StructuredType structuredType = (StructuredType) logicalType;
+                    int attrIndex = 0;
+                    for (StructuredType.StructuredAttribute attr : structuredType.getAttributes()) {
+                        if (attr.getName().equals(columnName)) {
+                            return fieldDataTypes.get(attrIndex);
+                        }
+                        attrIndex++;
+                    }
+                }
+            }
+
+            throw new IllegalStateException(
+                    String.format(
+                            "Cannot extract data type for partition column '%s' of argument '%s'",
+                            columnName, arg.name));
+        }
+
+        // ---------------------------------------------------------------------
+        // Type Inference
+        // ---------------------------------------------------------------------
+
+        /**
+         * Extracts type inference from the PTF and validates builder configuration.
+         *
+         * <p>Uses SystemTypeInference to validate things like reserved argument names, multiple
+         * table argument rules, static argument trait validation, etc.
+         */
+        private List<ArgumentInfo> extractAndValidateTypeInference(
+                ProcessTableFunction<OUT> function) {
+
+            DataTypeFactory dataTypeFactory = createDataTypeFactory();
+            TypeInference baseTypeInference = function.getTypeInference(dataTypeFactory);
+            TypeInference systemTypeInference =
+                    SystemTypeInference.of(FunctionKind.PROCESS_TABLE, baseTypeInference);
+
+            Optional<List<StaticArgument>> staticArgsOpt = systemTypeInference.getStaticArguments();
+            if (staticArgsOpt.isEmpty()) {
+                throw new IllegalStateException(
+                        "PTF does not provide static argument information. "
+                                + "Ensure @ArgumentHint annotations are present on all eval() parameters.");
+            }
+
+            List<StaticArgument> allArgs = staticArgsOpt.get();
+            List<StaticArgument> userArgs = new ArrayList<>();
+            for (StaticArgument arg : allArgs) {
+                if (!isSystemArgument(arg.getName())) {
+                    userArgs.add(arg);
+                }
+            }
+
+            List<ArgumentInfo> arguments = new ArrayList<>();
+
+            for (StaticArgument staticArg : userArgs) {
+                boolean isScalar = staticArg.getTraits().contains(StaticArgumentTrait.SCALAR);
+                boolean isTableArg =
+                        staticArg.getTraits().contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)
+                                || staticArg
+                                        .getTraits()
+                                        .contains(StaticArgumentTrait.SET_SEMANTIC_TABLE);
+
+                if (isScalar || isTableArg) {
+                    ArgumentInfo argInfo = buildArgumentInfo(staticArg);
+                    arguments.add(argInfo);
+                } else {
+                    throw new IllegalStateException(
+                            "Unknown argument type for StaticArgument. "
+                                    + "Expected SCALAR, ROW_SEMANTIC_TABLE, or SET_SEMANTIC_TABLE trait.");
+                }
+            }
+
+            validateArgumentConfiguration(arguments);
+
+            return arguments;
+        }
+
+        /** Checks if an argument name is a system-reserved argument. */
+        private boolean isSystemArgument(String argName) {
+            return SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_ON_TIME.equals(argName)
+                    || SystemTypeInference.PROCESS_TABLE_FUNCTION_ARG_UID.equals(argName);
+        }
+
+        private DataTypeFactory createDataTypeFactory() {
+            return new TestHarnessDataTypeFactory();
+        }
+
+        private ArgumentInfo buildArgumentInfo(StaticArgument staticArg) {
+
+            String name = staticArg.getName();
+            ArgumentTrait primaryTrait = extractPrimaryTrait(staticArg.getTraits());
+
+            DataType dataType;
+            if (primaryTrait == ArgumentTrait.SCALAR) {
+                Optional<DataType> dataTypeOpt = staticArg.getDataType();
+                if (dataTypeOpt.isPresent()) {
+                    dataType = dataTypeOpt.get();
+                } else {
+                    throw new IllegalStateException(
+                            String.format(
+                                    "Cannot determine data type for scalar argument '%s'", name));
+                }
+            } else {
+                // For table arguments, check both annotation and builder config
+                Optional<DataType> annotationTypeOpt = staticArg.getDataType();
+                TableArgumentConfiguration config = tableArgs.get(name);
+
+                if (annotationTypeOpt.isPresent()
+                        && config != null
+                        && config.explicitType != null) {
+                    // Both specified - validate they match
+                    DataTypeFactory factory = createDataTypeFactory();
+                    DataType builderType = factory.createDataType(config.explicitType);
+                    DataType annotationType = annotationTypeOpt.get();
+
+                    if (!annotationType.equals(builderType)) {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Type mismatch for table argument '%s': "
+                                                + "annotation declares type %s but builder declares type %s. "
+                                                + "Use either @ArgumentHint(type = ...) OR .withTableArgument(...), not both.",
+                                        name, annotationType, builderType));
+                    }
+                    dataType = annotationType;
+                } else if (annotationTypeOpt.isPresent()) {
+                    dataType = annotationTypeOpt.get();
+                } else if (config != null && config.explicitType != null) {
+                    DataTypeFactory factory = createDataTypeFactory();
+                    dataType = factory.createDataType(config.explicitType);
+                } else {
+                    // Try to infer from Java parameter class (for structured types)
+                    Optional<Class<?>> conversionClassOpt = staticArg.getConversionClass();
+                    if (conversionClassOpt.isPresent()) {
+                        DataTypeFactory factory = createDataTypeFactory();
+                        dataType = factory.createDataType(conversionClassOpt.get());
+                    } else {
+                        throw new IllegalStateException(
+                                String.format(
+                                        "Table argument '%s' requires explicit type configuration. "
+                                                + "Use @ArgumentHint(type = @DataTypeHint(\"ROW<...>\")) or "
+                                                + ".withTableArgument(\"%s\", DataTypes.of(\"ROW<...>\"))",
+                                        name, name));
+                    }
+                }
+            }
+
+            String[] partitionColumnNames = null;
+            if (primaryTrait == ArgumentTrait.SET_SEMANTIC_TABLE) {
+                boolean hasOptionalPartitionBy =
+                        staticArg.getTraits().contains(StaticArgumentTrait.OPTIONAL_PARTITION_BY);
+                partitionColumnNames =
+                        extractAndValidatePartitionColumns(name, dataType, hasOptionalPartitionBy);
+            }
+
+            boolean hasPassColumnsThrough =
+                    staticArg.getTraits().contains(StaticArgumentTrait.PASS_COLUMNS_THROUGH);
+
+            return new ArgumentInfo(
+                    name, dataType, primaryTrait, partitionColumnNames, hasPassColumnsThrough);
+        }
+
+        private ArgumentTrait extractPrimaryTrait(EnumSet<StaticArgumentTrait> staticTraits) {
+            if (staticTraits.contains(StaticArgumentTrait.SCALAR)) {
+                return ArgumentTrait.SCALAR;
+            }
+            if (staticTraits.contains(StaticArgumentTrait.ROW_SEMANTIC_TABLE)) {
+                return ArgumentTrait.ROW_SEMANTIC_TABLE;
+            }
+            if (staticTraits.contains(StaticArgumentTrait.SET_SEMANTIC_TABLE)) {
+                return ArgumentTrait.SET_SEMANTIC_TABLE;
+            }

Review Comment:
   Great, thank you!



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39377][table] Add initial implementation of ProcessTableFunctionTestHarness [flink]

Posted by "flinkbot (via GitHub)" <gi...@apache.org>.
flinkbot commented on PR #27928:
URL: https://github.com/apache/flink/pull/27928#issuecomment-4244551744

   <!--
   Meta data
   {
     "version" : 1,
     "metaDataEntries" : [ {
       "hash" : "4e8ec8439bea84ca89e028b0d323a27f6965e0d7",
       "status" : "UNKNOWN",
       "url" : "TBD",
       "triggerID" : "4e8ec8439bea84ca89e028b0d323a27f6965e0d7",
       "triggerType" : "PUSH"
     } ]
   }-->
   ## CI report:
   
   * 4e8ec8439bea84ca89e028b0d323a27f6965e0d7 UNKNOWN
   
   <details>
   <summary>Bot commands</summary>
     The @flinkbot bot supports the following commands:
   
    - `@flinkbot run azure` re-run the last Azure build
   </details>


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org