added docs on output API

SpecFlowOSS · May 17, 2021 · ffbe9fb · ffbe9fb
1 parent 246643e
commit ffbe9fb
Show file tree

Hide file tree

Showing 8 changed files with 68 additions and 2 deletions.
diff --git a/docs/_static/images/explorervs.png b/docs/_static/images/explorervs.png
diff --git a/docs/_static/images/livingdoc.png b/docs/_static/images/livingdoc.png
diff --git a/docs/_static/images/output.png b/docs/_static/images/output.png
diff --git a/docs/_static/images/outputerror.png b/docs/_static/images/outputerror.png
diff --git a/docs/_static/images/writeattachment.png b/docs/_static/images/writeattachment.png
diff --git a/docs/_static/images/writeline.png b/docs/_static/images/writeline.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -114,6 +114,7 @@ You can find a number of step- by- step guides to start with SpecFlow `here <htt
    Execution/Test-Results.md
    Execution/Parallel-Execution.md
    Execution/Debugging.md
+   outputapi/outputapi.md
 
 .. toctree::
    :maxdepth: 1
@@ -172,13 +173,13 @@ You can find a number of step- by- step guides to start with SpecFlow `here <htt
    Extend/Available-Plugins.md
    Extend/Available-Containers-&-Registrations.md
    Extend/Decorators.md
+
 
 .. toctree::
    :maxdepth: 1
    :caption: Tools
    :hidden:
-
-   Tools/Tools.md
+
    Tools/Generate-Tests-From-MsBuild.md   
    Tools/Cucumber-Messages.md
    Tools/Reporting.md
@@ -204,6 +205,7 @@ You can find a number of step- by- step guides to start with SpecFlow `here <htt
    legacy/Plugins-(Legacy).md
    legacy/CodedUI.md
    Guides/UpgradeSpecFlow2To3.md
+   Tools/Tools.md
 
 .. toctree::
    :maxdepth: 1

diff --git a/docs/outputapi/outputapi.md b/docs/outputapi/outputapi.md
@@ -0,0 +1,64 @@
+# Output API
+
+The SpecFlow Output API allows you to display texts and attachments in your IDE's test explorer output window and also in SpecFlow+LivingDoc.
+
+To use the SpecFlow output API interface you must inject the `ISpecFlowOutputHelper` interface via [Context Injection](https://docs.specflow.org/projects/specflow/en/latest/Bindings/Context-Injection.html):
+
+```csharp
+private readonly ISpecFlowOutputHelper _specFlowOutputHelper;
+
+public CalculatorStepDefinitions(ISpecFlowOutputHelper outputHelper)
+ {
+ _outputHelper = outputHelper;
+ }
+```
+
+There are two methods available:
+
+**1-** This method simply adds text:
+
+```csharp
+_specFlowOutputHelper.WriteLine("TEXT");
+```
+
+**2-** This method adds an attachment and requires the file path:
+
+```csharp
+_specFlowOutputHelper.AddAttachment(file path);
+```
+
+*> Note: Handling of attachments depends on your runner. MStest, NUnit, and SpecFlow+ Runner currently support this feature but xUnit does **not**.*
+
+## Example
+
+This example is based on the [Selenium with Page Object Model Pattern](https://docs.specflow.org/projects/specflow/en/latest/ui-automation/Selenium-with-Page-Object-Pattern.html) project which tests a simple calculator web application. You can download the repo for this example [here](https://github.com/SpecFlowOSS/SpecFlow-Examples/tree/master/OutputAPI).
+
+The `_specFlowOutputHelper.WriteLine` is used to indicate when the browser launches and closes:
+
+![Writeline example](../_static/images/writeline.png)
+
+Since this project tests a web application using a browser, the `_specFlowOutputHelper.AddAttachment` method has been used in the logging [Hook](https://docs.specflow.org/projects/specflow/en/latest/Bindings/Hooks.html) to display the saved screen shots taken during testing:
+
+![Writeattachment example](../_static/images/writeattachment.png)
+
+### Results
+
+To view the output window in Visual Studio, go to the text explorer and click on *Open Additional output for this result*:
+
+![Test Explorer in VS](../_static/images/explorervs.png)
+
+The resulting output for the example project used above would look like this:
+
+![Output in VS](../_static/images/output.png)
+
+The added text lines on browser launch and termination can help you easily identify the exact point at which the action takes place. The screen shots taken during testing are all also listed as image files under *Attachments*.
+
+If an attachment fails, the output explorer will display this message:
+
+![Output error](../_static/images/outputerror.png)
+
+In SpecFlow+LivingDoc, no additional setup is required, simply [generate LivingDoc](https://docs.specflow.org/projects/specflow-livingdoc/en/latest/LivingDocGenerator/Using-the-command-line-tool.html) as you normally do. You can then view the output texts and attachments by toggling the *Show/Hide Test Output* :
+
+![Output API in LivingDoc](../_static/images/livingdoc.png)
+
+*> Note: If the test output toggle is missing, it may be that you are on an older version of SpecFlow+LivingDoc, click [here](https://docs.specflow.org/projects/specflow-livingdoc/en/latest/LivingDocGenerator/Installing-the-command-line-tool.html) to update to the latest version.*