docs: add basic and advanced documentation and refactor main readme

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

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.

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)

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.