This is an automated email from the ASF dual-hosted git repository.

uranusjr pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git


The following commit(s) were added to refs/heads/main by this push:
     new ba4a8117e2c Add Task SDK client contract tests (#77146)
ba4a8117e2c is described below

commit ba4a8117e2c7716d6f89a863743c99fd85074f82
Author: Tzu-ping Chung <[email protected]>
AuthorDate: Tue Nov 17 12:41:01 2026 +0800

    Add Task SDK client contract tests (#77146)
    
    The Task SDK client is tested against a mocked server, and the
    Execution API routes against a hand-written client. Neither catches
    a client that assumes something the server doesn't do. #76825's
    first version had that bug, and only the Kubernetes e2e job caught
    it.
    
    Add a task_sdk_client fixture that sends the real client's requests
    to this tree's routes in process, as the Dag processor and triggerer
    do. Use it to test the client methods that interpret a response:
    XCom reads, and the not-found mapping for Variables, Connections and
    the task and asset state stores. Document the convention in the
    Execution API AGENTS.md.
    
    Two cases are left out on purpose:
    
    - Reading a mapped task's XCom with no map index. main returns null
      for it until #76825 is merged, and that PR adds the case here.
    - 401/403 to PERMISSION_DENIED. The in-process API overrides the
      access checks, so a test would only send the client a hand-written
      403, which the mocked client tests already cover.
---
 .../airflow/api_fastapi/execution_api/AGENTS.md    |   9 +
 .../unit/api_fastapi/execution_api/conftest.py     |  19 ++
 .../execution_api/test_task_sdk_client_contract.py | 256 +++++++++++++++++++++
 3 files changed, 284 insertions(+)

diff --git a/airflow-core/src/airflow/api_fastapi/execution_api/AGENTS.md 
b/airflow-core/src/airflow/api_fastapi/execution_api/AGENTS.md
index 146f8171022..dedf941af1b 100644
--- a/airflow-core/src/airflow/api_fastapi/execution_api/AGENTS.md
+++ b/airflow-core/src/airflow/api_fastapi/execution_api/AGENTS.md
@@ -62,6 +62,15 @@ Adding a new Execution API feature touches multiple 
packages. All of these must
    - `task-sdk/tests/task_sdk/api/test_client.py` — client method tests
    - `task-sdk/tests/task_sdk/execution_time/test_supervisor.py` — add a 
`RequestTestCase` entry to `REQUEST_TEST_CASES` list
    - `task-sdk/tests/task_sdk/execution_time/test_task_runner.py` — task 
runner integration tests
+   - 
`airflow-core/tests/unit/api_fastapi/execution_api/test_task_sdk_client_contract.py`
 — if the client method interprets the response (see below)
+
+### Client/server contract tests
+
+The task-sdk client tests use a mocked server, and the endpoint tests use a 
hand-written client, so neither catches a client that assumes something the 
server doesn't do. When a client method does more than send a request and parse 
the reply (it maps a status code to an `ErrorResponse`, parses a header, or 
falls back to another request), add a test to 
`test_task_sdk_client_contract.py`. It uses the `task_sdk_client` fixture, 
which sends the real client's requests, with its real `Airflow- [...]
+
+- Set up rows with `dag_maker` or the models, and assert on the client's 
return value, not on HTTP details.
+- The in-process API always answers as the newest version. Keep the mocked 
tests in `test_client.py` for behaviour against older servers.
+- In-process requests skip authorization, so these tests can't cover 401/403 
handling. The mocked tests and `test_security.py` do.
 
 ### Key Paths
 
diff --git a/airflow-core/tests/unit/api_fastapi/execution_api/conftest.py 
b/airflow-core/tests/unit/api_fastapi/execution_api/conftest.py
index cf96f9bd069..fc2d4320370 100644
--- a/airflow-core/tests/unit/api_fastapi/execution_api/conftest.py
+++ b/airflow-core/tests/unit/api_fastapi/execution_api/conftest.py
@@ -25,7 +25,9 @@ from airflow import settings
 from airflow.api_fastapi.app import cached_app
 from airflow.api_fastapi.execution_api.app import lifespan
 from airflow.api_fastapi.execution_api.datamodels.token import TIClaims, 
TIToken
+from airflow.api_fastapi.execution_api.in_process import InProcessExecutionAPI
 from airflow.api_fastapi.execution_api.security import require_auth
+from airflow.sdk.api.client import Client
 
 
 @pytest.fixture(autouse=True)
@@ -90,3 +92,20 @@ def client(request: pytest.FixtureRequest, async_db_engine):
             client.portal.call(async_db_engine.dispose)
 
     exec_app.dependency_overrides.pop(require_auth, None)
+
+
[email protected]
+def task_sdk_client():
+    """
+    A Task SDK client that sends its real requests to this tree's Execution 
API in process.
+
+    It is built the way the Dag processor and triggerer build theirs. Requests 
carry the
+    client's real ``Airflow-API-Version`` header and reach the real routes and 
database,
+    so a mismatch between what the client assumes and what the server does 
fails here.
+    Authorization is bypassed in process; the security tests cover it.
+    """
+    client = Client(base_url=None, token="", dry_run=True, 
transport=InProcessExecutionAPI().transport)
+    client.base_url = "http://in-process.invalid./";
+    # The transport stops its event loop and thread when it is garbage 
collected.
+    with client:
+        yield client
diff --git 
a/airflow-core/tests/unit/api_fastapi/execution_api/test_task_sdk_client_contract.py
 
b/airflow-core/tests/unit/api_fastapi/execution_api/test_task_sdk_client_contract.py
new file mode 100644
index 00000000000..2572d1a97fa
--- /dev/null
+++ 
b/airflow-core/tests/unit/api_fastapi/execution_api/test_task_sdk_client_contract.py
@@ -0,0 +1,256 @@
+# 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.
+"""
+Contract tests between the Task SDK client and this tree's Execution API.
+
+Each test sends the client's real requests to the real routes in process and 
asserts on what
+the client returns. They cover client methods that interpret a response beyond 
parsing it,
+such as mapping a status code to an error. Behaviour against older servers 
still needs the
+mocked tests in ``task-sdk/tests/task_sdk/api/test_client.py``.
+"""
+
+from __future__ import annotations
+
+import json
+from uuid import uuid4
+
+import pytest
+from sqlalchemy import delete
+
+from airflow._shared.timezones import timezone
+from airflow.models.asset import AssetActive, AssetModel
+from airflow.models.asset_state_store import AssetStateStoreModel
+from airflow.models.connection import Connection
+from airflow.models.task_state_store import TaskStateStoreModel
+from airflow.models.variable import Variable
+from airflow.models.xcom import XCOM_RETURN_KEY, XComModelV2
+from airflow.providers.standard.operators.empty import EmptyOperator
+from airflow.providers.standard.operators.python import PythonOperator
+from airflow.sdk.api.datamodels._generated import (
+    AssetStateStoreResponse,
+    ConnectionResponse,
+    TaskStateStoreResponse,
+    VariableResponse,
+    XComResponse,
+    XComSequenceIndexResponse,
+    XComSequenceSliceResponse,
+)
+from airflow.sdk.exceptions import ErrorType
+from airflow.sdk.execution_time.comms import ErrorResponse, XComCountResponse
+from airflow.utils.session import create_session
+
+from tests_common.test_utils.db import clear_db_connections, clear_db_variables
+
+pytestmark = pytest.mark.db_test
+
+MAPPED_VALUES = ["a", "b"]
+
+
+class TestXComOperations:
+    @pytest.fixture(autouse=True)
+    def dag_run(self, dag_maker, session):
+        with dag_maker(dag_id="dag", serialized=True):
+            EmptyOperator(task_id="plain")
+            PythonOperator.partial(task_id="mapped", 
python_callable=str).expand(op_args=[[1], [2]])
+        dag_run = dag_maker.create_dagrun(run_id="runid")
+        for ti in dag_run.get_task_instances(session=session):
+            value = "plain" if ti.task_id == "plain" else 
MAPPED_VALUES[ti.region_index]
+            session.add(XComModelV2(key=XCOM_RETURN_KEY, value=value, 
task_instance_id=ti.id))
+        session.commit()
+        return dag_run
+
+    @pytest.mark.parametrize(
+        ("task_id", "map_index", "expected"),
+        [
+            pytest.param("mapped", 1, "b", id="mapped-one"),
+            pytest.param("mapped", 2, None, id="mapped-past-end"),
+            pytest.param("plain", None, "plain", id="unmapped-omitted"),
+            pytest.param("plain", 0, None, id="unmapped-with-index"),
+        ],
+    )
+    def test_get(self, task_sdk_client, task_id, map_index, expected):
+        result = task_sdk_client.xcoms.get("dag", "runid", task_id, 
XCOM_RETURN_KEY, map_index)
+        assert result == XComResponse(key=XCOM_RETURN_KEY, value=expected)
+
+    def test_get_missing_key(self, task_sdk_client):
+        result = task_sdk_client.xcoms.get("dag", "runid", "plain", "missing")
+        assert result == XComResponse(key="missing", value=None)
+
+    @pytest.mark.parametrize(
+        ("offset", "expected"),
+        [
+            pytest.param(0, "a", id="first"),
+            pytest.param(-1, "b", id="last"),
+        ],
+    )
+    def test_get_sequence_item(self, task_sdk_client, offset, expected):
+        result = task_sdk_client.xcoms.get_sequence_item("dag", "runid", 
"mapped", XCOM_RETURN_KEY, offset)
+        assert result == XComSequenceIndexResponse(expected)
+
+    @pytest.mark.parametrize(
+        ("key", "offset"),
+        [
+            pytest.param(XCOM_RETURN_KEY, 2, id="out-of-range"),
+            pytest.param("missing", 0, id="missing-key"),
+        ],
+    )
+    def test_get_sequence_item_not_found(self, task_sdk_client, key, offset):
+        result = task_sdk_client.xcoms.get_sequence_item("dag", "runid", 
"mapped", key, offset)
+        assert result == ErrorResponse(
+            error=ErrorType.XCOM_NOT_FOUND,
+            detail={"dag_id": "dag", "run_id": "runid", "task_id": "mapped", 
"key": key, "offset": offset},
+        )
+
+    @pytest.mark.parametrize(
+        ("key", "start", "expected"),
+        [
+            pytest.param(XCOM_RETURN_KEY, None, MAPPED_VALUES, id="all"),
+            pytest.param(XCOM_RETURN_KEY, 1, MAPPED_VALUES[1:], id="from-one"),
+            pytest.param("missing", None, [], id="missing-key"),
+        ],
+    )
+    def test_get_sequence_slice(self, task_sdk_client, key, start, expected):
+        result = task_sdk_client.xcoms.get_sequence_slice("dag", "runid", 
"mapped", key, start, None, None)
+        assert result == XComSequenceSliceResponse(expected)
+
+    @pytest.mark.parametrize(
+        ("task_id", "key", "expected"),
+        [
+            pytest.param("mapped", XCOM_RETURN_KEY, len(MAPPED_VALUES), 
id="mapped"),
+            pytest.param("plain", XCOM_RETURN_KEY, 1, id="unmapped"),
+            pytest.param("mapped", "missing", 0, id="missing-key"),
+        ],
+    )
+    def test_head(self, task_sdk_client, task_id, key, expected):
+        result = task_sdk_client.xcoms.head("dag", "runid", task_id, key)
+        assert result == XComCountResponse(len=expected)
+
+
+class TestVariableOperations:
+    @pytest.fixture(autouse=True)
+    def _clear_variables(self):
+        clear_db_variables()
+        yield
+        clear_db_variables()
+
+    def test_get(self, task_sdk_client, session):
+        session.add(Variable(key="var", val="value"))
+        session.commit()
+        result = task_sdk_client.variables.get("var")
+        assert result == VariableResponse(key="var", value="value")
+
+    def test_get_not_found(self, task_sdk_client):
+        result = task_sdk_client.variables.get("missing")
+        assert result == ErrorResponse(error=ErrorType.VARIABLE_NOT_FOUND, 
detail={"key": "missing"})
+
+
+class TestConnectionOperations:
+    @pytest.fixture(autouse=True)
+    def _clear_connections(self):
+        clear_db_connections(add_default_connections_back=False)
+        yield
+        clear_db_connections(add_default_connections_back=False)
+
+    def test_get(self, task_sdk_client, session):
+        session.add(Connection(conn_id="conn", conn_type="http", 
host="localhost", port=8080))
+        session.commit()
+        result = task_sdk_client.connections.get("conn")
+        assert result == ConnectionResponse(
+            conn_id="conn",
+            conn_type="http",
+            host="localhost",
+            schema=None,
+            login=None,
+            password=None,
+            port=8080,
+            extra=None,
+        )
+
+    def test_get_not_found(self, task_sdk_client):
+        result = task_sdk_client.connections.get("missing")
+        assert result == ErrorResponse(error=ErrorType.CONNECTION_NOT_FOUND, 
detail={"conn_id": "missing"})
+
+
+class TestTaskStateStoreOperations:
+    @pytest.fixture(autouse=True)
+    def ti(self, create_task_instance, session):
+        session.execute(delete(TaskStateStoreModel))
+        ti = create_task_instance(session=session)
+        for key, value in [("job_id", "spark_001"), ("stored_null", None)]:
+            session.add(
+                TaskStateStoreModel(
+                    dag_run_id=ti.dag_run.id,
+                    dag_id=ti.dag_id,
+                    run_id=ti.run_id,
+                    task_id=ti.task_id,
+                    region_id=ti.region_id,
+                    region_index=ti.region_index,
+                    key=key,
+                    value=json.dumps(value),
+                    updated_at=timezone.utcnow(),
+                )
+            )
+        session.commit()
+        yield ti
+        with create_session() as cleanup:
+            cleanup.execute(delete(TaskStateStoreModel))
+
+    def test_get(self, task_sdk_client, ti):
+        result = task_sdk_client.task_state_store.get(ti.id, "job_id")
+        assert result == TaskStateStoreResponse(value="spark_001")
+
+    @pytest.mark.parametrize("key", ["missing", "stored_null"])
+    def test_get_not_found(self, task_sdk_client, ti, key):
+        result = task_sdk_client.task_state_store.get(ti.id, key)
+        assert result == ErrorResponse(error=ErrorType.TASK_STORE_NOT_FOUND, 
detail={"key": key})
+
+    def test_get_missing_task_instance(self, task_sdk_client):
+        """A task instance that doesn't exist reads the same as a missing 
key."""
+        result = task_sdk_client.task_state_store.get(uuid4(), "job_id")
+        assert result == ErrorResponse(error=ErrorType.TASK_STORE_NOT_FOUND, 
detail={"key": "job_id"})
+
+
+class TestAssetStateStoreOperations:
+    @pytest.fixture(autouse=True)
+    def asset(self, session):
+        session.execute(delete(AssetStateStoreModel))
+        session.execute(delete(AssetModel))
+        asset = AssetModel(name="asset", uri="s3://bucket/asset", 
group="asset")
+        session.add(asset)
+        session.flush()
+        session.add(AssetActive.for_asset(asset))
+        session.add(AssetStateStoreModel(asset_id=asset.id, key="watermark", 
value=json.dumps("2026-04-29")))
+        session.commit()
+        yield asset
+        with create_session() as cleanup:
+            cleanup.execute(delete(AssetStateStoreModel))
+            cleanup.execute(delete(AssetModel))
+
+    @pytest.mark.parametrize("by", ["name", "uri"])
+    def test_get(self, task_sdk_client, asset, by):
+        result = task_sdk_client.asset_state_store.get("watermark", **{by: 
getattr(asset, by)})
+        assert result == AssetStateStoreResponse(value="2026-04-29")
+
+    def test_get_not_found(self, task_sdk_client, asset):
+        result = task_sdk_client.asset_state_store.get("missing", 
name=asset.name)
+        assert result == ErrorResponse(error=ErrorType.ASSET_STORE_NOT_FOUND, 
detail={"key": "missing"})
+
+    @pytest.mark.parametrize("by", [{"name": "missing"}, {"uri": 
"s3://bucket/missing"}])
+    def test_get_missing_asset(self, task_sdk_client, by):
+        """An asset that doesn't exist reads the same as a missing key."""
+        result = task_sdk_client.asset_state_store.get("watermark", **by)
+        assert result == ErrorResponse(error=ErrorType.ASSET_STORE_NOT_FOUND, 
detail={"key": "watermark"})

Reply via email to