Skip to content

Allow providers to ship testing Dags separately from example Dags - #70541

Open
ColtenOuO wants to merge 1 commit into
apache:mainfrom
ColtenOuO:split-testing-dags-loading
Open

Allow providers to ship testing Dags separately from example Dags#70541
ColtenOuO wants to merge 1 commit into
apache:mainfrom
ColtenOuO:split-testing-dags-loading

Conversation

@ColtenOuO

Copy link
Copy Markdown
Contributor

Summary

Adds the loading mechanism for a per-provider testing_dags/ folder, so Dags that
exist to exercise Airflow itself can be told apart from Dags that teach Dag authoring.

No Dags move in this PR. Moving them happens one provider at a time in follow-ups.

Why

Example Dags currently serve four audiences at once: teaching Dag authoring, backing
documentation snippets, verifying a deployment, and propping up CI. Because they all
share one folder:

  • a user who enables [core] load_examples also gets Dags that only exist for testing
    example_failed_dag is designed to fail;
  • nobody can safely delete a stale example without first checking whether a test depends
    on it. Today example_failed_dag, example_skip_dag,
    example_passing_params_via_test_command and example_kubernetes_executor are
    referenced from airflow-core/tests/unit/cli/, airflow-core/tests/unit/api_fastapi/,
    airflow-e2e-tests/ and kubernetes-tests/.

What's in here

  • [core] load_testing_dags config option, defaulting to False and independent of
    load_examples.
  • DagBundlesManager discovers <provider>/testing_dags/ and exposes it as an
    apache-airflow-providers-*-testing-dags bundle. The provider-resolution loop added in
    Load example DAGs from providers via ProvidersManager (continuation of #57320) #66161 is factored out into _iter_provider_module_paths() so both folder kinds share
    it.
  • breeze shell / breeze start-airflow --load-testing-dags, plumbed through to
    AIRFLOW__CORE__LOAD_TESTING_DAGS.
  • load_provider_testing_dags pytest fixture in tests_common, so the follow-up PRs can
    pull these Dags into unit tests from both breeze and a local venv.
  • Folder convention documented in contributing-docs/12_provider_distributions.rst.

Since no provider ships a testing_dags/ folder yet, this is inert for existing
deployments.

related: #52475


Was generative AI tooling used to co-author this PR?
  • Yes — Claude Code (Opus 5)

Example Dags currently serve four different audiences at once: they teach Dag
authoring, they back documentation snippets, they verify a deployment, and some
of them are load-bearing for CI. Because everything lives in one folder, a user
who enables `[core] load_examples` gets Dags that only exist to exercise Airflow
itself -- `example_failed_dag`, for instance, is designed to fail -- and nobody
can safely delete a stale example without first working out whether a test
depends on it.

This adds the loading mechanism for a separate `testing_dags` folder per
provider so the two purposes can be told apart. No Dags move yet; that happens
per provider in follow-ups.

Part of apache#52475.
@ColtenOuO

Copy link
Copy Markdown
Contributor Author

Just a couple more questions before we wrap this up!

  1. The issue only specifies the per-provider testing_dags/ rule, which is what I implemented — but every example Dag that CI currently depends on (example_failed_dag, example_skip_dag, example_passing_params_via_test_command, example_kubernetes_executor) lives in core's own airflow/example_dags/, so should core get a sibling airflow/testing_dags/ as well?

  2. And for the dual-use Dags that stay in example_dags but are "tagged for testing", is tags=["example", "testing"] the intended shape — if so, the check-example-dags-have-example-tag hook from Add prek hook enforcing the "example" tag on example DAGs #67354 will need to be relaxed to allow it.

@jason810496 jason810496 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO, I prefer not to touch the prod code at all to fulfill the purpose of #52475. IIUC, how about setting up another "test-only" DagBundle in breeze if the AIRFLOW__CORE__LOAD_TESTING_DAGS ENV flag is set.

cc @jscheffl - the main stakeholder for this one on the direction.

@potiuk potiuk added the ready for maintainer review Set after triaging when all criteria pass. label Jul 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants