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"})