Multi Feature Merge - Test Engine Authentication, Providers and Power Fx extensions

README.md

@@ -26,8 +26,8 @@ To get started, you will need to clone the Test Engine code from GitHub, locally
 
 ### Prerequisites for building Test Engine
 
-1. Install [.NET Core 6.0.x SDK](https://dotnet.microsoft.com/en-us/download/dotnet/6.0)
-1. Ensure that your `MSBuildSDKsPath` environment variable is pointing to [.NET Core 6.0.x SDK](https://dotnet.microsoft.com/en-us/download/dotnet/6.0).
+1. Install [.NET Core 8.0.x SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0)
+1. Ensure that your `MSBuildSDKsPath` environment variable is pointing to [.NET Core 8.0.x SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0).
 1. Make sure [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2) is installed.
 
 ### Build locally

azure-pipelines.yml

@@ -27,9 +27,9 @@ jobs:
 
   steps:
   - task: UseDotNet@2
-    displayName: 'Use dotnet sdk 6.0'
+    displayName: 'Use dotnet sdk 8.0'
     inputs:
-      version: 6.0.x
+      version: 8.0.x
       installationPath: '$(Agent.ToolsDirectory)/dotnet'
 
   - task: CodeQL3000Init@0

build-pipelines/scripts/yaml-integration-tests.sh

@@ -44,7 +44,7 @@ do
        fi                                                                
     done
   if [[ -n "${envId}" && -n "${tenantId}" && -n "${domain}" && -n "${testPlanFile}" && -n "${outputDir}" ]]; then     # null checks on args
-    dotnet run -f net6.0 -- -e ${envId} -t ${tenantId} -d ${domain} -i ${testPlanFile} -o ${outputDir} -q "&PAOverrideFGRollout.OnePlayerStandaloneWebPlayer=false";
-    dotnet run -f net6.0 -- -e ${envId} -t ${tenantId} -d ${domain} -i ${testPlanFile} -o ${outputDir} -q "&PAOverrideFGRollout.OnePlayerStandaloneWebPlayer=true";
+    dotnet run -f net8.0 -- -e ${envId} -t ${tenantId} -d ${domain} -i ${testPlanFile} -o ${outputDir} -q "&PAOverrideFGRollout.OnePlayerStandaloneWebPlayer=false";
+    dotnet run -f net8.0 -- -e ${envId} -t ${tenantId} -d ${domain} -i ${testPlanFile} -o ${outputDir} -q "&PAOverrideFGRollout.OnePlayerStandaloneWebPlayer=true";
   fi
 done

docs/PowerFX/Pause.md

@@ -1,9 +1,13 @@
 # Pause
 
-`Pause()`
+`TestEngine.Pause()`
 
-This will open the interactive Playwright Inspector and wait for the user to resume execution.
+This will open the interactive [Playwright Inspector](https://playwright.dev/dotnet/docs/debug#playwright-inspector) and wait for the user to resume execution. 
+
+## Using with Simulation commands
+
+Using the playwright inspector you can access the [Browser Developer Tools](https://playwright.dev/dotnet/docs/debug#browser-developer-tools) to monitor network traffic between the page and the services
 
 ## Example
 
-`Pause()`
+`TestEngine.Pause()`

docs/PowerFX/README.md

@@ -4,11 +4,21 @@ There are several specifically defined functions for the test framework.
 
 - [Assert](./Assert.md)
 - [Screenshot](./Screenshot.md)
-- [Pause](./Pause.md)
 - [Select](./Select.md)
 - [SetProperty](./SetProperty.md)
 - [Wait](./Wait.md)
 
+- [TestEngine.Pause](./Pause.md)
+- [TestEngine.PlaywrightAction](./PlaywrightAction.md)
+- [TestEngine.PlaywrightScript](./PlaywrightAction.md)
+
+## Experimental Functions
+
+The following functions will be enabled in Debug build and when Experimental is enabled as a Namespace
+
+- [Experimental.SimulateConnector](./SimulateConnector.md)
+- [Experimental.SimulateDataverse](./SimulateDataverse.md)
+
 ## Naming
 
 When creating additional functions using [modules](../modules.md) for Power Fx in the Test Engine, it's important to follow naming standards to ensure consistency and readability.
@@ -23,6 +33,14 @@ Here are some guidelines for naming your functions in Power Fx:
 
 By following these naming standards, your Power Fx code will be easier to read and maintain, and other developers will be able to understand your code more easily.
 
+### Use Namespaces
+
+Namespaces should be used for Power Fx functions in the Power Apps Test Engine for several reasons. First, using namespaces ensures that there is no clash with built-in functions, which can cause confusion and errors. By using namespaces, Power Fx functions can be organized and grouped together in a clear and concise manner.
+
+Additionally, namespaces make it clear that these Power Fx functions belong to the Test Engine, and are not part of the larger Power Apps ecosystem. This helps to avoid confusion and ensures that the functions are used appropriately within the context of the Test Engine.
+
+Overall, using namespaces for Power Fx functions in the Power Apps Test Engine is a best practice that helps to ensure clarity, organization, and consistency in the testing process.
+
 ### Using Descriptive Names
 
 Using descriptive names is important because it makes it easier for others (and yourself) to understand what the function or service does. A good name should be concise but also convey the function's or service's purpose. For example, instead of naming a function "Calculate," you could name it "CalculateTotalCost" to make it clear what the function is doing.

docs/PowerFX/SimulateConnector.md

@@ -0,0 +1,41 @@
+# Simulate Connection
+
+The Experimental.SimluateConnection function allows you to simulate requests to Power Platform connector and provide responses without actually making live requests. This is particularly useful for testing and development purposes, as it enables you to create predictable and controlled responses for various scenarios.
+
+```powerfx
+Experimental.SimulateConnection({Name: "connectorname", Action: "actionname", Parameters: {}, Filter: "optionalfilter", Then: {Value: Table()}})
+```
+
+## Parameters
+
+| Name | Description |
+|------|-------------|
+| Name | The name of the connector from thr url of the [connector list](https://learn.microsoft.com/connectors/connector-reference/connector-reference-powerapps-connectors). For example the name of the [Office 365 Users](https://learn.microsoft.com/en-us/connectors/office365users/) is **office365users**
+| Action | The part of the url request that will match against the action
+| Parameters | A Power Fx Record that will be mapped to Query parameters required to me matched
+| Filter | A Power Fx expression that needs to be matched |
+
+## Recording Sample Values
+
+To obtain values for the `Experimental.SimulateConnection()` function you can use the network trace of the Browser Developer Tools when using [Experimental.Pause()](./Pause.md) where you can filter traffic by searching for **/invoke**
+
+## Examples
+
+1. Query user using Power 365 Users connector
+
+```powerfx
+Experimental.SimulateConnection({Name: "office365users", Action: "/v1.0/me", Then: {
+    displayName: "Sample User",
+    "id": "c12345678-1111-2222-3333-44445555666",
+    "jobTitle": null,
+    "mail": "[email protected]",
+    "userPrincipalName": "[email protected]",
+    "userType": "Member"
+}})
+```
+
+2. Query groups using Power 365 groups connector
+
+```powerfx
+Experimental.SimulateConnection({Name: "office365groups", Filter: "name = '[email protected]'", Then: Table()})
+```

docs/PowerFX/SimulateDataverse.md

@@ -0,0 +1,46 @@
+# Simulate Dataverse
+
+The Experimental.SimulateDataverse function allows you to simulate responses from the Dataverse without actually querying the live data. This is particularly useful for testing and development purposes, as it enables you to create predictable and controlled responses for various scenarios.
+
+```powerfx
+Experimental.SimulateDatarse({ Action: "query", Entity: "TableName", When: { Field: "value" }, Then: Table({Name: "Test"}) })
+```
+
+| Name | Description |
+|------|-------------|
+| Action | The dataverse action to simulate from Query, Create, Update, Delete
+| Entity | The name pluralized entity name from [metadata](https://learn.microsoft.com/power-apps/developer/data-platform/webapi/web-api-service-documents)
+| When | The optional query string to apply
+| Filter | A Power Fx expression that needs to be matched. This will automatically be mapped to odata $filter command |
+| When | The Power Fx table to return in the odata value response that will be returned to the Power App
+
+## Recording Sample Values
+
+To obtain values for the `Experimental.SimulateDataverse()` function you can use the network trace of the Browser Developer Tools when using [Experimental.Pause()](./Pause.md) where you can filter traffic by searching for **/api/data/v**
+
+## Example
+
+1. Simulate a Query Response with Sample Data
+
+When the Power App queries all accounts, respond with sample data:
+
+```powerfx
+Experimental.SimulateDataverse({Action:"query",Entity: "accounts", Then: Table({accountid: "a1234567-1111-2222-3333-44445555666", name: "Test"}) });
+```
+
+2. Simulate a Query with Specific Conditions
+
+When make request with account with query name of Other return no results
+
+```powerfx
+Experimental.SimulateDataverse({Action:"query",Entity: "accounts", When: {Name: "Other"}, Then: Table()});
+```
+
+## Why This Function is Useful
+The `Experimental.SimulateDataverse()` function is useful because it allows developers and makers to:
+
+1. **Test and Debug**: Simulate different scenarios and responses without affecting live data, making it easier to test and debug applications.
+1. **Predictable Results**: Create controlled and predictable responses, which is essential for automated testing and ensuring consistent behavior.
+1. **Development Efficiency**: Speed up the development process by allowing developers to work with simulated data instead of waiting for actual data to be available.
+
+By using this function, you can ensure that your Power Apps behave as expected in various scenarios, leading to more robust and reliable applications.

docs/PowerFX/TestEngine.PlaywrightAction.md

@@ -0,0 +1,36 @@
+# TestEngine.PlaywrightAction
+
+` TestEngine.PlaywrightAction(Locator, Action)`
+
+` TestEngine.PlaywrightAction(Url, Action)`
+
+This use the locators or Url to apply an action to the current web page.
+
+## Locators
+
+When selecting actions that require a locator you can make use of [CSS Selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) or XPath queries.
+
+Locators for web pages are based on Playwright locators. More information on locators is available from [Playwright documentation](https://playwright.dev/docs/other-locators).
+
+Playwright also supports experimental React and vue base selectors that can be useful for selecting elements on code first extensions like PCF controls within a Power App.
+
+## Actions
+
+The following actions are supported
+
+| Action   | Description                            |
+|----------|----------------------------------------|
+| click    | Select matching locator items          |
+| exists   | Returns True or False is locator exist |
+| navigate | Navigate to the url                    |
+| wait     | Wait for locator items to exist        |
+
+## Examples
+
+` TestEngine.PlaywrightAction("//button", "click")`
+
+` Assert(TestEngine.PlaywrightAction("//button", "exists") = true)`
+
+` TestEngine.PlaywrightAction("https://www.microsoft.com", "navigate")`
+
+` TestEngine.PlaywrightAction("//button", "wait")`

docs/PowerFX/TestEngine.PlaywrightScript.md

@@ -0,0 +1,44 @@
+# TestEngine.PlaywrightScript
+
+`TestEngine.PlaywrightScript(csxFileName)`
+
+The PlaywrightScript function provides a "no cliffs" extensibility for Test Engine providing the ability to execute CSharp Scripts (*.csx) files inside a Test Engine web provider based test that uses Playwright as web page test framework.
+
+You can use the playwright inspector to record C# commands to build the C# script
+
+## C# Script
+
+This action takes advantage of [dotnet-script](https://github.com/dotnet-script/dotnet-script) and the underlying [Rosyln](https://github.com/dotnet/roslyn) compiler to allow projectless scripting of Playwright code. The Action assumes the following:
+
+1. Any required .Net Assemblies are globally available or in the current folder and can be loaded using #r compiler directive
+2. A public class named **PlaywrightScript** MUST exist
+3. A method with **public static void Run(IBrowserContext context, ILogger logger)** MUST exist
+
+## Sample Test
+
+A sample [testPlan.fx.yaml](../../samples/playwrightscript/testPlan.fx.yaml) and [sample.csx](../../samples/playwrightscript/sample.csx) provide a demonstration of how this action can be integrated into a Test Engine test.
+
+## Example
+
+` TestEngine.PlaywrightScript("sample.csx")
+
+Where sample could use template to include Playwright
+
+```csharp
+#r "Microsoft.Playwright.dll"
+#r "Microsoft.Extensions.Logging.dll"
+using Microsoft.Playwright;
+using Microsoft.Extensions.Logging;
+using System.Linq;
+using System.Threading.Tasks;
+
+public class PlaywrightScript {
+    public static void Run(IBrowserContext context, ILogger logger) {
+        Execute(context, logger).Wait();
+    }
+
+    public static async Task Execute(IBrowserContext context, ILogger logger) {
+        // Insert your code here
+    }
+}
+```

samples/coe-kit-setup-wizard/.gitignore

@@ -0,0 +1,2 @@
+config.json
+config.**.json

samples/coe-kit-setup-wizard/GetAppId.powerfx

@@ -0,0 +1 @@
+Filter('Model-driven Apps', 'Unique Name' = "admin_CoESetupWizardPreview")

samples/coe-kit-setup-wizard/README.md

@@ -1,18 +1,108 @@
 # Overview
 
-The Power Platform Center of Excellence (CoE) starter kit is made up of a number of Power Platform low code solution elements. Amoung these is a model driven application that can be used to setup and upgrade the CoE Starter Kit.
+The Power Platform Center of Excellence (CoE) starter kit is made up of a number of Power Platform low code solution elements. Among these is a model driven application that can be used to setup and upgrade the CoE Starter Kit.
 
-This sample includes Power Apps Test Engine tests that can be used to automate and test ket elemenets of the expected behaviour of the Setup and Upgrade Wizard
+This sample includes Power Apps Test Engine tests that can be used to automate and test ket elements of the expected behavior of the Setup and Upgrade Wizard
+
+## What You Need
+
+Before you start, you'll need a few tools and permissions:
+- **Power Platform Command Line Interface (CLI)**: This is a tool that lets you interact with Power Platform from your command line.
+- **PowerShell**: A task automation tool from Microsoft.
+- **.Net 8.0 SDK**: A software development kit needed to build and run the tests.
+- **Power Platform Environment**: A space where your Power Apps live.
+- **Admin or Customizer Rights**: Permissions to make changes in your Power Platform environment.
+
+## Prerequisites
+
+1. Install of .Net SDK 8.0 from [Downloads](https://dotnet.microsoft.com/download/dotnet/8.0)
+2. An install of PowerShell following the [Install Overview](https://learn.microsoft.com/powershell/scripting/install/installing-powershel) for your operating system
+3. The Power Platform Command Line interface installed using the [Learn install guidance](https://learn.microsoft.com/power-platform/developer/cli/introduction?tabs=windows#install-microsoft-power-platform-cli)
+4. A created Power Platform environment using the [Power Platform Admin Center](https://learn.microsoft.com/power-platform/admin/create-environment) or [Power Platform Command Line](https://learn.microsoft.com/power-platform/developer/cli/reference/admin#pac-admin-create)
+5. Granted System Administrator or System Customizer roles as documented in [Microsoft Learn](https://learn.microsoft.compower-apps/maker/model-driven-apps/privileges-required-customization#system-administrator-and-system-customizer-security-roles)
+6. Git Client has been installed. For example using [GitHub Desktop](https://desktop.github.com/download/) or the [Git application](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+7. The CoE Starter Kit core module has been installed into the environment
 
 ## Getting Started
 
-To get started ensure that you have followed the [Build locally](../../README.md) to have a working version of the Power Apps Test Engine available
+1. Clone the repository using the git application and PowerShell command line
+
+```pwsh
+git clone https://github.com/microsoft/PowerApps-TestEngine.git
+```
+
+2. Change to cloned folder
+
+```pwsh
+cd PowerApps-TestEngine
+```
+
+3. Checkout the integration branch
+
+```pwsh
+git checkout grant-archibald-ms/data-record-386
+```
 
-## Usage
+3. Ensure logged out out of pac cli. This ensures you're logged out of any previous sessions.
+
+```pwsh
+pac auth clear
+```
 
-You can execute this sample using the following commands
+4. Login to Power Platform CLI using [pac auth](https://learn.microsoft.com/power-platform/developer/cli/reference/auth#pac-auth-create)
 
-```bash
-cd bin/Debug/PowerAppsTestEngine
-dotnet PowerAppsTestEngine.dll -i ../../../samples/coe-kit-setup-wizard/testPlan.fx.yaml -u browser -p mda -d https://contoso.crm.dynamics.com/main.aspx?appid=06f88e88-163e-ef11-840a-0022481fcc8d&pagetype=custom&name=admin_initialsetuppage_d45cf
+```pwsh
+pac auth create --environment <Your environment ID>
 ```
+
+5. Add the config.json in the same folder as RunTests.ps1 replacing the value with your tenant and  environment id
+
+```json
+{
+    "tenantId": "a222222-1111-2222-3333-444455556666",
+    "environmentId": "12345678-1111-2222-3333-444455556666",
+    "customPage": "admin_initialsetuppage_d45cf",
+    "runInstall": true,
+    "installPlaywright": true
+}
+```
+
+## Run Test
+
+To Run the sample tests from PowerShell assuming the Getting started steps have been completed
+
+```pwsh
+.\RunTests.ps1
+```
+
+## Record and Replay
+
+To record interaction with Dataverse and generate a sample Test Engine script perform the following steps assuming the Getting started steps have been completed
+
+1. Start record process
+
+```pwsh
+.\Record.ps1
+```
+
+2. If required login to the Power App
+
+3. Wait for the Playwright Inspector to be displayed
+
+4. Interact with the Setup and Upgrade Wizard
+
+5. When ready to complete the record session press play in the Playwright Inspector
+
+6. Open the generated **recorded.te.yaml** that includes data from recorded Dataverse and Connector calls.
+
+## What to Expect
+
+- **Login Prompt**: You'll be asked to log in to the Power Apps Portal.
+- **Test Execution**: The Test Engine will run the steps to test your Power Apps Portal.
+- **Cached Credentials**: If you choose "Stay Signed In," future tests will use your saved credentials.
+- **Interactive Testing**: Commands like `TestEngine.Pause()` will let you pause and inspect the test steps.
+- **Recorded Sessions**: Test Engine provides the ability to generate recorded video of the test session in the TestOutput folder.
+
+## Context
+
+This sample is an example of a "build from source" using the open source licensed version of Test Engine. Features in the the source code version can include feature not yet release as part of the ```pac test run`` command in the Power Platform Command line interface action.