docs: Improve unit-testing docs with runnable pytest examples for Operators

[suii2210]

This PR improves the unit-testing section of the Airflow documentation by adding runnable pytest examples for testing custom operators.

The existing docs show a dag.test() example which behaves differently inside pytest due to DAG serialization constraints.

To address this, the PR adds:

• DummySuccessOperator (used only for testing) • Example using TaskInstance.run() • Example using dag.create_dagrun() • Documentation updates under best-practices

All examples are fully runnable and compatible with Airflow 3.x.

Closes: #58893

[boring-cyborg[bot]]

Congratulations on your first Pull Request and welcome to the Apache Airflow community! If you have any issues or are unsure about any anything please check our Contributors' Guide (https://github.com/apache/airflow/blob/main/contributing-docs/README.rst) Here are some useful points:

• Pay attention to the quality of your code (ruff, mypy and type annotations). Our prek-hooks will help you with that.
• In case of a new feature add useful documentation (in docstrings or in docs/ directory). Adding a new operator? Check this short guide Consider adding an example DAG that shows how users should use it.
• Consider using Breeze environment for testing locally, it's a heavy docker but it ships with a working Airflow and a lot of integrations.
• Be patient and persistent. It might take some time to get a review or get the final approval from Committers.
• Please follow ASF Code of Conduct for all communication including (but not limited to) comments on Pull Requests, Mailing list and Slack.
• Be sure to read the Airflow Coding style.
• Always keep your Pull Requests rebased, otherwise your build might fail due to changes not related to your commits. Apache Airflow is a community-driven project and together we are making it better 🚀. In case of doubts contact the developers at: Mailing List: [email protected] Slack: https://s.apache.org/airflow-slack

[suii2210]

@jroachgolf84 Hi - could you please review #58969 when you have a moment? Thanks!

[suii2210]

Hi reviewers - this PR adds runnable pytest examples for operator unit tests and a tiny DummySuccessOperator used only for examples. I fixed all static checks (license headers, ruff formatting) and pushed the changes. PR: #58969 - please review when you get a chance; I’ll address review comments promptly. Thanks!

[jroachgolf84]

@suii2210 - I'm seeing all "placeholders" for now. Is that intended?

[suii2210]

@jroachgolf84 Thanks for pointing that out!

The placeholder comments were left in by mistake during an earlier draft.
I’ve now replaced all placeholders with the full runnable pytest examples,
including the DummySuccessOperator implementation and both unit test files.

The PR is updated and ready for review.
Please let me know if you'd like any adjustments!

[suii2210]

Thanks for the clarification!

You're right - adding a top-level tests/ directory would definitely be confusing in the Airflow repo.
I’ll remove the test files from the repository and include the runnable examples directly in the docs as code blocks instead.

I'll push an updated version shortly. Thanks for the feedback!

[suii2210]

Hi , thanks for the feedback! I've removed the top-level tests/ directory and moved all pytest examples directly into the documentation, as suggested. The docs now include complete runnable examples (operator + tests) inline, without modifying the project structure.

Let me know if you'd like the examples formatted differently or placed under a different docs subsection - happy to update!

[jroachgolf84]

What is the options file for?

[suii2210]

Hi @jroachgolf84, The options file was created locally by my environment and was committed accidentally. It isn't required for this PR and shouldn't be part of the repository.

I've removed it from the branch now.

Thanks for pointing it out!

[jroachgolf84]

@suii2210 - thanks for taking a look at that. I'm still seeing that file there, as well as an update to .gitignore. You're going to want to revert .gitignore to its original state, and remove options.

[suii2210]

Hi @jroachgolf84, thanks for pointing that out - I've now completely removed the stray options file and restored .gitignore to its original state. The PR is updated accordingly.

Let me know if you'd like anything else adjusted!

[jroachgolf84]

One last thing - there's a best-practices.rst file that already exists (airflow-core/docs/best-practices.rst). I think it might make sense to add those docs there, rather than creating a new page in the docs/ directory.

https://github.com/apache/airflow/blob/65ca7d337d4adc43ef89dfc83fcaedff60dd68aa/airflow-core/docs/best-practices.rst?plain=1#L650

[suii2210]

Hi @jroachgolf84, thanks for the suggestion - I’ve removed the separate documentation page and moved all operator unit-testing examples into the existing airflow-core/docs/best-practices.rst under the “Testing a DAG” section. Formatting has been aligned with the existing structure.

[potiuk]

@jroachgolf84 -> any more comments ?

[jroachgolf84]

LGTM - thanks for addressing all of my comments!

[suii2210]

Great work! Thanks for being so flexible!

Thank you

[suii2210]

Hello @jroachgolf84 , I accidentally triggered the re-request for review. That was my mistake - really sorry about that.

[jroachgolf84]

All good my friend :)

[potiuk]

I recommend you to install and use prek - as described in our docs. It will automatically fix all such problems when you commit stuff.

[potiuk]

And the problem is that you have some extra spaces at the end that you don't see

[choo121600]

And as a small suggestion, going forward, we’ve decided to DAG as Dag. It would be great if you could update this accordingly 😉

vote results as of https://lists.apache.org/thread/0651j4vdgzmlhgndmotvznlg97kyh328

[suii2210]

And the problem is that you have some extra spaces at the end that you don't see Hello @potiuk I’ve resolved the trailing whitespace issues and set up prek locally as well.

[potiuk]

And as a small suggestion, going forward, we’ve decided to DAG as Dag.

good point. Added suggestions

[choo121600]

Once this part is updated, everything looks good to me ;)

[boring-cyborg[bot]]

Awesome work, congrats on your first merged pull request! You are invited to check our Issue Tracker for additional contributions.

[github-actions[bot]]

Backport successfully created: v3-1-test

Status	Branch	Result
✅	v3-1-test

[suii2210]

Once this part is updated, everything looks good to me ;)

sure I will do this .

[choo121600]

Once this part is updated, everything looks good to me ;)

sure I will do this .

That’s okay! It was already fixed and has been merged 👍

[suii2210]

Thanks everyone for the review and guidance! Glad it’s merged !!!!