Test your Astro project

Check your Airflow dags for errors before you run them locally or deploy to Astro.

One of the Astro CLI’s main features is the ability to run Astro projects in a local Airflow environment. It additionally includes commands that you can use to test and debug dags both inside and outside of a locally running Airflow environment.

Use the following document to learn more about how you can test locally with the Astro CLI before deploying your code changes to a production environment.

Run a dag with astro run

Use the astro run command to run a dag from the command line. When you run the command, the CLI compiles your dag and runs it in a single Airflow worker container based on your Astro project configurations, including your Dockerfile, dag utility files, Python requirements, and environment variables. You can review task logs and task status in your terminal without opening the Airflow UI. Running dags without a scheduler or webserver can help reduce the time required to develop and test data pipelines.

To run a dag located within your local /dags directory, run:

astro run <dag-id>

You can only run one dag at a time. All the tasks in your dag run sequentially. Any errors produced by your code while parsing or running your dag appear in the command line. For more information about this command, see the CLI command reference.

Unit test dags

You can run dag unit tests with the following Astro CLI commands to quickly test code:

• astro dev parse
• astro dev pytest

These commands don’t require a running Airflow environment, meaning you can test dags without deploying to Astro or running Airflow locally. However, these commands do require Docker.

Parse dags

To quickly parse your dags, run:

astro dev parse

This command parses your dags to ensure that they don’t contain any basic syntax or import errors and that they can successfully render in the Airflow UI.

astro dev parse is a more convenient but less customizable version of astro dev pytest. If you don’t have any specific test files that you want to run on your dags, Astronomer recommends using astro dev parse as your primary testing tool. For more information about this command, see the CLI command reference.

Run tests with pytest

To run unit tests on your Astro project, run:

astro dev pytest

This command runs all tests in your project’s tests directory with pytest, a testing framework for Python. With pytest, you can test custom Python code and operators locally without having to start a local Airflow environment.

The tests directory in your Astro project includes an example dag test called test_dag_example.py. This test checks that:

• All Airflow tasks have required arguments.
• Dag IDs are unique across the Astro project.
• Dags have no cycles.
• There are no general import or syntax errors.

This test is just an example of the kinds of pytests one could run to test their dags. You may want to alter this test or create new ones that better fit the context of your dags. astro dev pytest will run any pytest file that you add to the tests directory. For more information about this command, see the CLI command reference.

Test before an Astro Runtime upgrade

You can use astro dev upgrade-test to test your local Astro project against a new version of Astro Runtime to prepare for an upgrade. By default, the command runs the following tests in order to create reports that can help you determine whether your upgrade will be successful:

• Dependency test: Identify the packages that have been added, removed, or changed in the upgrade version.
• Dag test: Identify Python dag import errors in the upgrade version.

To run these tests, open your Astro project and run:

astro dev upgrade-test

If the tests are successful, the Astro CLI creates a folder in your Astro project called upgrade-test-<your-current-version>--<your-upgrade-version>. The folder will contain the following reports:

• pip_freeze_<current-version>: The output of the pip freeze with your current version.
• pip_freeze_<upgrade-version>: The output of the pip freeze with your upgrade version.
• dependency_compare.txt: The result of the dependency test.
• Dockerfile: The updated file used in the upgrade test.
• dag-test-results.html: The results of the dag test.

Use the test results to fix any major package changes or broken dags before you upgrade. Refer to the Airflow and Provider package release notes to assist in upgrading your dags. After you resolve all conflicts and dag import errors, you can upgrade Astro Runtime and deploy your project to an Astro Deployment.

When you rerun the test for the same project and upgrade version, all the files in the test results folder will be updated. To keep results for a particular test, change the folder name before rerunning the command.

If you’re testing a local project before deploying to Astro, you can test more accurately by adding

--deployment-id

flag and specifying your Deployment ID. The Astro CLI uses the image currently running in your Deployment to test against the upgrade version. Note that this flag will use your local dags and dependencies against your Astro Deployment’s image with the upgrade version of runtime specified.

Read the following sections to learn more about the contents of each test report. For more information about the command’s settings, see the CLI reference guide.

Dependency test

To prepare for an upgrade, it’s helpful to identify all Python packages which will modified as a result of the upgrade. You can do this using the dependency test. When you run the test, the Astro CLI generates a report called dependency_compare.txt in upgrade-test-<current-version>--<upgrade-version>. The report shows all Airflow providers and packages that have been removed, added, or updated.

When you read the results of this test, pay close attention to the Major Updates section. Major updates to Python packages are more likely to cause your dags to fail. Visit the changelog for any providers listed in this section (for example, the HTTP provider changelog) to see if the major upgrade will affect your environment. You should also pay attention to anything listed under Unknown Updates. These are updates that Astro CLI could not categorize, which can include major upgrades that might cause dags to break.

To run only the dag test against the latest version of Astro Runtime, run the following command in your Astro Project:

astro dev upgrade-test --version-test

Dag test

When you upgrade, any Python packages that changed can generate import errors and cause your dags to break. These import errors are visible in the UI after you upgrade, but you can address them before upgrading by running the dag test.

This test uses the astro dev parse command against the upgrade version and produces a report called dag-test-report.html in upgrade-test-<current-version>--<upgrade-version>. This HTML report lists the dags that will have import errors, along with the first error encountered if you complete an upgrade. You can use this report along with the dependency test report to fix errors in your dags before your upgrade.

To run only the dag test against the latest version of Astro Runtime, run the following command in your Astro Project:

astro dev upgrade-test --dag-test

See also

• Debug dags
• astro dev pytest