From c17369891a8a1f9ff5f888c0a238c33b5feacb51 Mon Sep 17 00:00:00 2001 From: Arjen Kroezen Date: Tue, 6 Feb 2024 12:13:58 +0100 Subject: [PATCH] docs: add basic and advanced documentation and refactor main readme --- README.md | 14 ++++++++------ docs/basic/activity-testing.md | 4 +++- .../installing-and-initializing-framework.md | 4 ++-- docs/basic/pipeline-testing.md | 19 +++++++++++++++++-- 4 files changed, 30 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 353c0cf4..5d636bc7 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ The stand-alone framework allows you to validate locally that the configuration ### High-level example -Given a WebActivity with a `typeProperties.url` containing the following expression: +Given a `WebActivity` with a `typeProperties.url` containing the following expression: ```datafactoryexpression @concat(pipeline().globalParameters.baseUrl, variables('JobName')) @@ -38,11 +38,6 @@ A simple test to validate that the concatenation is working as expected can be w assert "https://example.com/some-path" == activity.type_properties["url"].value ``` -More advanced examples demonstrating the capabilities of the framework: - -1. [Batch job example](examples/fabric/batch_job/README.md) -2. [Copy blobs example](examples/data_factory/copy_blobs/README.md) - ## Why Data Factory does not support unit testing pipelines and activities. It also does not support testing your pipelines locally. Having integration and e2e tests is great, but having unit tests on top of them provides additional means of quick iteration and validation. Unit testing with the _Data Factory Testing Framework_ has the following benefits: @@ -71,6 +66,13 @@ The following pages go deeper into different topics and concepts of the framewor 4. [Overriding expression functions](docs/advanced/overriding-expression-functions.md) 5. [Framework internals](docs/advanced/framework-internals.md) +## Examples + +More advanced examples demonstrating the capabilities of the framework: + +1. [Batch job example](examples/fabric/batch_job/README.md) +2. [Copy blobs example](examples/data_factory/copy_blobs/README.md) + ## Contributing This project welcomes contributions and suggestions. Most contributions require you to agree to a diff --git a/docs/basic/activity-testing.md b/docs/basic/activity-testing.md index c8272a32..768215f5 100644 --- a/docs/basic/activity-testing.md +++ b/docs/basic/activity-testing.md @@ -56,7 +56,7 @@ Let's write a test for validating correct evaluation of the `url` property. ## Arrange -Get a reference to the activity you want to test using the `get_activity_by_name` method on the `PipelineResource` instance. Create a `PipelineRunState` instance with the input parameters and variables of the scenario you want to test. +Get a reference to the activity you want to test using the `get_activity_by_name` method on the `Pipeline` instance. ```python activity = pipeline.get_activity_by_name("Trigger job") @@ -82,6 +82,8 @@ Call the `evaluate` method on the activity with the `PipelineRunState` instance. activity.evaluate(state) ``` +The `evaluate` method might throw an exception if the expression is invalid or if the state is missing required parameters or variables. Make sure to supply the correct state to the activity. + ## Assert Verify that the output of the activity matches the expected result. diff --git a/docs/basic/installing-and-initializing-framework.md b/docs/basic/installing-and-initializing-framework.md index e5b62945..38854b5a 100644 --- a/docs/basic/installing-and-initializing-framework.md +++ b/docs/basic/installing-and-initializing-framework.md @@ -31,5 +31,5 @@ activity = pipeline.get_activity_by_name("webactivity_name") See the following pages for more information on how to write tests for activities and pipelines: -1. [Activity testing](docs/basic/activity-testing.md) -2. [Pipeline testing](docs/basic/pipeline-testing.md) +1. [Activity testing](activity-testing.md) +2. [Pipeline testing](pipeline-testing.md) diff --git a/docs/basic/pipeline-testing.md b/docs/basic/pipeline-testing.md index ac0dcae3..67d718ea 100644 --- a/docs/basic/pipeline-testing.md +++ b/docs/basic/pipeline-testing.md @@ -2,9 +2,9 @@ The framework provides a way to evaluate a pipeline and validate the execution flow of each activity and ensure that the outcome of one activity is correctly passed to the next activity. -Get acquainted with the [Activity testing](docs/basic/activity-testing.md) page before proceeding with pipeline testing, because similar concepts are used. +Get acquainted with the [Activity testing](activity-testing.md) page before proceeding with pipeline testing, because similar concepts are used. -Make sure to have initialized the framework before writing tests. See [Installing and initializing the framework](docs/basic/installing-and-initializing-framework.md) for more information. +Make sure to have initialized the framework before writing tests. See [Installing and initializing the framework](installing-and-initializing-framework.md) for more information. Now that you have a `TestFramework` instance, you can start writing tests for your pipelines. A test always follows the Arrange-Act-Assert pattern: @@ -101,6 +101,21 @@ assert "https://example.com/Job-123/version" == get_version_activity.type_proper assert "GET" == get_version_activity.type_properties["method"] ``` +### Activity output references + +If an activity output is being referenced (e.g. `activity('Get version of job').output.version`), make sure to set the result of the activity using the `set_result` method before requesting the next activity from the generator. + +```python +get_version_activity.set_result(DependencyCondition.Succeeded, { "version", "1.0.0" }) +``` + +The next(activities) method might throw an exception if the expression is invalid or if a property of an expression is not (yet) available in the state. Make sure that: + +1. Parameters are supplied +2. Variables are being set correctly through the `SetVariable` activity +3. Activity outputs being referenced are set through `activity.set_result` method +4. Dependency conditions are met + ## No more activities When the generator has no more activities to return, it will raise a `StopIteration` exception. This is a signal that all activities have been evaluated and the pipeline has been executed as expected.