[#409] Update docs based on feedback (#472)

ceciliaavila · web-flow · commit 25e704d1ceca · 2021-07-27T14:27:06.000-04:00
* Update documentation

* Update variables and TestRunner docs

* Fix file paths

* Fix typo in TranscriptConverter's Readme
diff --git a/Docs/README.md b/Docs/README.md
@@ -7,8 +7,8 @@
 ## Guides
 
 - [Add a Service Connection to an Azure Resource Manager](./addARMServiceConnection.md)
-- [Create WebApp Deployment credentials](./createWebAppDeploymentCredentials.md)
 - [Get the Service Principal's Object ID](./getServicePrincipalObjectID.md)
+- [Setup App Registrations](./setupAppRegistrations.md)
 - [Setup Pipelines](./setupPipelines.md)
 - [Setup custom Docker container](./setupDockerContainer.md)
 - [Regional Virtual Network integration](./regionalVirtualNetworkIntegration.md)
diff --git a/Docs/addARMServiceConnection.md b/Docs/addARMServiceConnection.md
@@ -9,15 +9,18 @@ Go to [Service connections](https://docs.microsoft.com/en-us/azure/devops/pipeli
 ## Requirements
 
 - An [Azure DevOps Organization](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/create-organization?view=azure-devops).
+- An [Azure AD application and Service Principal](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal) (*).
 - Access to an active [Azure Resource Manager](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/overview).
 
+(*) The Service Principal needs to have a `Contributor` role in the suscription to be able to create resource groups.
+
 ## Steps
 
 - From your Azure DevOps project, go to `Project settings -> Service Connections -> New Service connection`.
 
   ![addARMServiceConnection1](./media/addARMServiceConnection1.png)
 
-- Select `Azure Resource Manager -> Service principal (manual)` and fill out the form. Check the `Grant access permission to all pipelines` option. The name you use for the Subscription Name field will be your `AzureSubscription` variable in the pipelines.
+- Select `Azure Resource Manager -> Service principal (manual)` and fill out the form. Check the `Grant access permission to all pipelines` option. The name you use for the Subscription Name field will be your `AzureSubscription` variable in the pipelines. [More Info](https://docs.microsoft.com/en-us/azure/devops/pipelines/library/connect-to-azure?view=azure-devops#create-an-azure-resource-manager-service-connection-with-an-existing-service-principal).
 
   ![addARMServiceConnection2](./media/addARMServiceConnection2.png)
 
diff --git a/Docs/availableBotsList.md b/Docs/availableBotsList.md
@@ -0,0 +1,33 @@
+# Available Bots 
+These are the bots currently available. This list will be expanded in the future.
+
+### Bot Names
+- DotNet
+  - Consumers
+    - BffnSimpleComposerHostBotDotNet
+    - BffnSimpleHostBotDotNet
+    - BffnSimpleHostBotDotNet21
+    - BffnWaterfallHostBotDotNet
+  - Skills
+    - BffnEchoComposerSkillBotDotNet
+    - BffnEchoSkillBotDotNet
+    - BffnEchoSkillBotDotNet21
+    - BffnEchoSkillBotDotNetV3
+    - BffnWaterfallSkillBotDotNet
+
+- JS
+  - Consumers
+    - BffnSimpleHostBotJS
+    - BffnWaterfallHostBotJS
+  - Skills
+    - BffnEchoSkillBotJS
+    - BffnEchoSkillBotJSV3
+    - BffnWaterfallSkillBotJS
+
+- Python
+  - Consumers
+    - BffnSimpleHostBotPython
+    - BffnWaterfallHostBotPython
+  - Skills
+    - BffnEchoSkillBotPython
+    - BffnWaterfallSkillBotPython
diff --git a/Docs/createWebAppDeploymentCredentials.md b/Docs/createWebAppDeploymentCredentials.md
diff --git a/Docs/media/CreateAppRegistrations.ps1 b/Docs/media/CreateAppRegistrations.ps1
@@ -2,7 +2,7 @@ Write-Host "You will be prompted to login into your Azure account to create App
 az login
 
 $defaultPrefix = "generic-app-registration"
-$defaultAmount = 14
+$defaultAmount = 18
 $appRegistrations = @()
 do {
     $prefix = Read-Host -Prompt "App Registrations prefix ('$defaultPrefix' by default)"
diff --git a/Docs/media/dependenciesParameters.png b/Docs/media/dependenciesParameters.png
diff --git a/Docs/pipelines.md b/Docs/pipelines.md
diff --git a/Docs/setupAppRegistrations.md b/Docs/setupAppRegistrations.md
@@ -1,4 +1,4 @@
-# How to setup up App Registrations
+# How to setup App Registrations
 
 The following steps will guide you on how to manually set up App Registrations.
 By default, App Registrations are created and used automatically across the [pipelines](./pipelines.md), but the possibility of setting them up manually is available.
@@ -16,12 +16,12 @@ To skip stages, simple click on Stages to run, deselect them, and click Use sele
 
 ## Create App Registrations
 
-App Registration credentials must be created for each bot to be deployed and tested (there are fourteen currently, but the number is expected to increase in the future).
+App Registration credentials must be created for each bot to be deployed and tested (see [Available Bots](./availableBotsList.md)).
 To do this, you could head to [App Registrations](https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) on Azure and create them one by one, but we created a PowerShell script to create registration batches automatically. The only requirement to run it is to have access to an active Azure account.
 
 Click [here](./media/CreateAppRegistrations.ps1) to go to the script.
 
-Executing it will prompt you to log into your account with your default browser, then to define a prefix for the registration names, and finally for the amount of registrations to create. Both have default values (triggered by pressing Enter) to accommodate for the creation of fourteen credentials with generic names.
+Executing the script will prompt you to log into your account with your default browser, then to define a prefix for the registration names, and finally for the amount of registrations to create. Both have default values (triggered by pressing Enter) to accommodate for the creation of eighteen credentials with generic names.
 The creation process will start, displaying each registration's name, ID, and password created while running.
 
 ![setupAppRegistrations2](media/setupAppRegistrations2.png)
@@ -40,49 +40,21 @@ If you didn't have any variables set up already, it will look like the picture o
 
 ![setupAppRegistrations4](media/setupAppRegistrations4.png)
 
-The following list contains all current variable names to be created, each credential pair can be populated with any of the ones created in the [Create App Registrations](#create-app-registrations) step.
-
+You must create a pair of variables for each bot in the [list of available bots](./availableBotsList.md) adding `AppId` and `AppSecret` to the bot's name.
+For example:
 - BffnEchoSkillBotComposerDotNetAppId
 - BffnEchoSkillBotComposerDotNetAppSecret
-- BffnEchoSkillBotDotNet21AppId
-- BffnEchoSkillBotDotNet21AppSecret
-- BffnEchoSkillBotDotNetAppId
-- BffnEchoSkillBotDotNetAppSecret
-- BffnEchoSkillBotDotNetV3AppId
-- BffnEchoSkillBotDotNetV3AppSecret
-- BffnEchoSkillBotJSAppId
-- BffnEchoSkillBotJSAppSecret
-- BffnEchoSkillBotJSV3AppId
-- BffnEchoSkillBotJSV3AppSecret
-- BffnEchoSkillBotPythonAppId
-- BffnEchoSkillBotPythonAppSecret
-- BffnSimpleHostBotComposerDotNetAppId
-- BffnSimpleHostBotComposerDotNetAppSecret
-- BffnSimpleHostBotDotNet21AppId
-- BffnSimpleHostBotDotNet21AppSecret
-- BffnSimpleHostBotDotNetAppId
-- BffnSimpleHostBotDotNetAppSecret
-- BffnSimpleHostBotJSAppId
-- BffnSimpleHostBotJSAppSecret
-- BffnSimpleHostBotPythonAppId
-- BffnSimpleHostBotPythonAppSecret
-- BffnWaterfallHostBotDotNetAppId
-- BffnWaterfallHostBotDotNetAppSecret
-- BffnWaterfallSkillBotDotNetAppId
-- BffnWaterfallSkillBotDotNetAppSecret
+
+Each credential pair can be populated with any of the ones created in the [Create App Registrations](#create-app-registrations) step.
 
 Don't forget to click on SAVE once you've finished setting up every variable.
 
 ![setupAppRegistrations5](media/setupAppRegistrations5.png)
 
 Lastly, you'll have to create new variables for the [Run Test Scenarios](../build/yaml/testScenarios/runTestScenarios.yml), same steps apply.
-This pipeline requires only the App Registration IDs of the skill bots, so the list is shorter. Just be sure to use the same IDs as with the [Deploy Bot Resources](../build/yaml/deployBotResources/deployBotResources.yml) pipeline.
-
+This pipeline requires only the App Registration IDs of the skill bots, so the list is shorter. 
+For example:
 - BffnEchoSkillBotComposerDotnetAppId
-- BffnEchoSkillBotDotNet21AppId
-- BffnEchoSkillBotDotNetAppId
-- BffnEchoSkillBotDotNetV3AppId
-- BffnEchoSkillBotJSAppId
-- BffnEchoSkillBotJSV3AppId
-- BffnEchoSkillBotPythonAppId
-- BffnWaterfallSkillBotDotNetAppId
+
+Just be sure to use the same IDs as with the [Deploy Bot Resources](../build/yaml/deployBotResources/deployBotResources.yml) pipeline.
+
diff --git a/Libraries/TranscriptConverter/README.md b/Libraries/TranscriptConverter/README.md
@@ -0,0 +1,56 @@
+# Transcript Converter
+
+## Summary
+
+Transcript Converter is a command line tool to convert `.transcript` files from different channels (BotFramework-Emulator, Teams, Slack, etc.)* into a test script used to replicate the messages sent by the user and evaluate the answers from the bot.
+This test script is the input for the [Transcript Test Runner](../TranscriptTestRunner/TranscriptTestRunner.csproj).
+
+(*) _This first version supports BotFramework-Emulator transcript files. Stay tuned for the next features._
+
+## The Test Script
+A Test Script is basically a JSON file with an array of [TestScriptItem](TestScriptItem.cs) that will be used by the `TranscriptTestRunner` as a test input.
+
+You can also create a test script file using this [JSON schema](../TranscriptTestRunner/testscript.schema).
+```json
+[
+ {
+   "type": "conversationUpdate",
+   "role": "user"
+ },
+ {
+   "type": "message",
+   "role": "bot",
+   "text": "Hello and welcome!",
+   "assertions": [
+     "type == 'message'",
+     "from.role == 'bot'",
+     "recipient.role == 'user'",
+     "text == 'Hello and welcome!'",
+     "inputHint == 'acceptingInput'"
+   ]
+ },
+ {
+   "type": "message",
+   "role": "user",
+   "text": "Hi"
+ }
+]
+```
+> **Note:** The JSON Schema is still a work in progress.
+
+## User Step-by-step Guide
+This step-by-step guide shows how to convert a BotFramework-Emulator transcript file into a test script.
+
+1- After installing the tool open a terminal and execute the following command:
+
+```
+btc convert "path-to-source-transcript" "path-to-target-test-script"
+```
+- The first argument is the absolute or relative path to the transcript file.
+To create a transcript file, follow [these steps](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-debug-transcript?view=azure-bot-service-4.0#creatingstoring-a-bot-transcript-file).
+
+- The second argument is optional, and sets the path to the folder where the test script will be created. If not provided, the test script will have the same name and location that the transcript.
+
+2- Once the Test Script file is created, store it in a folder on your test project and pass it to the _RunTestAsync_ method of the `TestRunner` to execute the test.
+
+
diff --git a/Libraries/TranscriptTestRunner/README.md b/Libraries/TranscriptTestRunner/README.md
@@ -3,21 +3,15 @@
 ## Summary
 
 Transcript Test Runner aims to simplify complex conversation scenarios against bots.
-Starting from a transcript file containing the user-bot interactions to be tested, the Transcript Test Runner converts the transcript into a test script used to replicate the messages sent by the user and evaluate the answers from the bot.
+Starting from a [test script](testscript.schema) file containing the user-bot interactions to be tested, the Transcript Test Runner replicates the messages sent by the user and evaluates the answers from the bot.
 
-The Transcript Test Runner also offers the possibility of running the tests directly from a [test script](testscript.schema), adding flexibility to the assertions for the bot's messages.
-
-The Test Runner supports different formats of transcript files (Emulator, Teams, Slack, etc.) and
-can be connected to the bots using different channels (*):
-- DirectLineClient
-- TeamsClient
-- SlackClient
-- FacebookClient
-
-(*) _This first version implements the DirectLineClient and uses Emulator transcript files. Stay tuned for the next features._
+A Test Script is basically a JSON file with an array of [TestScriptItem](TestScriptItem.cs) that will be used by the `TestRunner` as a test input.
 
 ## User Step-by-step Guide
-This step-by-step guide shows how to run a test with the `TestRunner` configuring a `DirectLine` client to communicate with the bots, and starting from an Emulator transcript file.
+This step-by-step guide shows how to run a test with the `TestRunner` configuring a `DirectLine` client to communicate with the bots.
+
+### Creating the Test Script file
+You can convert a transcript file into a test script using the [Transcript Converter](../TranscriptConverter/TranscriptConverter.csproj) tool or create one manually using this [JSON schema](testscript.schema).
 
 ### Using the TestRunner
 1- Open your test project and install the `TranscriptTestRunner` package.
@@ -32,65 +26,37 @@ This step-by-step guide shows how to run a test with the `TestRunner` configurin
 
 > **Note:** For more information on how to obtain the bot `DIRECTLINE` secret key, follow [this guide](https://docs.microsoft.com/en-us/azure/bot-service/bot-service-channel-connect-directline).
 
-3- Add the `Emulator Transcript` file in a folder on your test project. To create a transcript file, follow [these steps](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-debug-transcript?view=azure-bot-service-4.0#creatingstoring-a-bot-transcript-file).
+3- Add the `Test Script` file in a folder on your test project.
 
 4- Add the `TestRunner` to your test.
 
 ```csharp
+// Create the test options
+var options = new DirectLineTestClientOptions { BotId = "<bot-id>", DirectLineSecret = "<direct-line-secret>" };
+
 // Create a DirectLine client with the `TestClientFactory`.
-var directLineClient = new TestClientFactory(ClientType.DirectLine).GetTestClient();
+var directLineClient = new TestClientFactory(ClientType.DirectLine, options).GetTestClient();
 
 // Instantiate the TestRunner and set up the DirectLine client.
 var runner = new TestRunner(directLineClient);
 
-// Run the test recorded in the transcript file.
-await runner.RunTestAsync("<path to the transcript file>");
-```
-The `TestRunner` will convert the transcript file into a Test Script with the messages the user sends to the bot and the assertions that should be made to the bot's answers.
-
-The `TestRunner` also allows you to run the test from a custom Test Script file.
-
-### Using a Test Script file
-A Test Script is basically a JSON file with an array of [TestScriptItem](TestScriptItem.cs) that will be used by the `TestRunner` as a test input.
-
-Create a test script file using this [JSON schema](testscript.schema).
-```json
-[
- {
-   "type": "conversationUpdate",
-   "role": "user"
- },
- {
-   "type": "message",
-   "role": "bot",
-   "text": "Hello and welcome!",
-   "assertions": [
-     "type == 'message'",
-     "from.role == 'bot'",
-     "recipient.role == 'user'",
-     "text == 'Hello and welcome!'",
-     "inputHint == 'acceptingInput'"
-   ]
- },
- {
-   "type": "message",
-   "role": "user",
-   "text": "Hi"
- }
-]
+// Run the test recorded in the test script file.
+await runner.RunTestAsync("<path to the test script file>");
 ```
-> **Note:** The JSON Schema is still a work in progress.
+The `TestRunner` will execute test script sending the user messages to the bot performing the assertions over the bot's answers.
 
-Once the Test Script file is created, store it in a folder on your test project and pass it to the _RunTestAsync_ method of the TestRunner instead of the transcript file.
 
 ### Creating tests programmatically
-The `TestRunner` allows you to run tests in a programmatic way, sending Activities to the bot and Assert its reply.
+The `TestRunner` allows you to run tests in a programmatic way, sending Activities to the bot and asserting its reply.
 
 The following sample shows how to create a simple test programmatically.
 
 ```csharp
+// Create the test options
+var options = new DirectLineTestClientOptions { BotId = "<bot-id>", DirectLineSecret = "<direct-line-secret>" };
+
 // Create a DirectLine client instance that will be used to communicate with your bot.
-var directLineClient = new TestClientFactory(ClientType.DirectLine).GetTestClient();
+var directLineClient = new TestClientFactory(ClientType.DirectLine, options).GetTestClient();
 
 // Instantiate the TestRunner and set up the DirectLine client.
 var runner = new TestRunner(directLineClient);
@@ -119,8 +85,10 @@ This method is used when your bot has an authentication implementation and you w
 The following sample shows how to use the `ClientSignInAsync` method to sign in.
 
 ```csharp
+// Create the test options.
+var options = new DirectLineTestClientOptions { BotId = "<bot-id>", DirectLineSecret = "<direct-line-secret>" };
 // Create a DirectLine client instance that will be used to communicate with your bot.
-var directLineClient = new TestClientFactory(ClientType.DirectLine).GetTestClient();
+var directLineClient = new TestClientFactory(ClientType.DirectLine, options).GetTestClient();
 // Instantiate the TestRunner and set up the DirectLine client.
 var runner = new TestRunner(directLineClient);
 var signInUrl = string.Empty;
@@ -168,20 +136,22 @@ var loggerFactory = LoggerFactory.Create(builder =>
 // Create the `Logger` instance with a Category name.
 var logger = loggerFactory.CreateLogger("Category");
 
+// Create the test options
+var options = new DirectLineTestClientOptions { BotId = "<bot-id>", DirectLineSecret = "<direct-line-secret>" };
 // Create a DirectLine client instance that will be used to communicate with your bot.
-var directLineClient = new TestClientFactory(ClientType.DirectLine).GetTestClient();
+var directLineClient = new TestClientFactory(ClientType.DirectLine, options).GetTestClient();
 // Instantiate the TestRunner, set up the DirectLine client, and send the created `Logger`.
-var runner = new TestRunner(directLineClient, logger);
+var runner = new TestRunner(directLineClient, logger = logger);
 ```
 
 ### Extend TestRunner functionality
-TestRunner has an Xunit extention to allow the users that prefer this test framework, to override the `AssertActivityAsync` with Xunit assertions.
+TestRunner has an Xunit extension to allow the users that prefer this test framework, to override the `AssertActivityAsync` with Xunit assertions.
 
 ```csharp
 public class XUnitTestRunner : TestRunner
 {
-    public XUnitTestRunner(TestClientBase client, ILogger logger = null)
-        : base(client, logger)
+    public XUnitTestRunner(TestClientBase client, int replyTimeout = 180000, int thinkTime = 0, ILogger logger = null)
+            : base(client, replyTimeout, thinkTime, logger)
     {
     }
 
