From cbb726ffce8b158432af90b34d4b8336ba9cf1b1 Mon Sep 17 00:00:00 2001 From: Osagie Okoedo Date: Fri, 23 Sep 2022 12:41:26 +0100 Subject: [PATCH 1/9] Updated CONTRIBUTING.md file to aid testing and knowledge transfer --- CONTRIBUTING.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 880b033..a74f53c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,24 @@ # Contributing Please first discuss the change you wish to make via an issue before making a change. + +## Testing + +1. Set up powerapps binding +2. Application user musy be added with the system admin rights +3. Tests by default is on US datetime format, therefore change it based on your personal location. For example, if you are based in India, set the datetime format to the local time. +- This can be done by going to the Power Apps settings > +- Select Pernalization Settings > +- From the Set Personal Options page, click on the Formats menu > +- Change the Current Format from the dropdown by ther selecting the country of your location > +- Click on the Customize button > +- Click OK button + +NB: Running all tests are not required as the CI build will do these. Test verify any tests you have impacted. ## Pull request process 1. Ensure that there are automated tests that cover any changes -1. Update the README.md with details of any significant changes to functionality -1. Ensure that your commit messages increment the version using [GitVersion syntax](https://gitversion.readthedocs.io/en/latest/input/docs/more-info/version-increments/). If no message is found then the patch version will be incremented by default. -1. You may merge the pull request once it meets all of the required checks. If you do not have permision, a reviewer will do it for you \ No newline at end of file +2. Update the README.md with details of any significant changes to functionality +3. Ensure that your commit messages increment the version using [GitVersion syntax](https://gitversion.readthedocs.io/en/latest/input/docs/more-info/version-increments/). If no message is found then the patch version will be incremented by default. +4. You may merge the pull request once it meets all of the required checks. If you do not have permision, a reviewer will do it for you \ No newline at end of file From 7fdbc9ab161ac98309c53d7ea8480a351a426bd5 Mon Sep 17 00:00:00 2001 From: Osagie Okoedo Date: Fri, 23 Sep 2022 14:57:09 +0100 Subject: [PATCH 2/9] Corrected some typo errors in the CONTRIBUTING.md file --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a74f53c..dbc96cf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,7 +5,7 @@ Please first discuss the change you wish to make via an issue before making a ch ## Testing 1. Set up powerapps binding -2. Application user musy be added with the system admin rights +2. Application user may be added with the system admin rights 3. Tests by default is on US datetime format, therefore change it based on your personal location. For example, if you are based in India, set the datetime format to the local time. - This can be done by going to the Power Apps settings > - Select Pernalization Settings > @@ -14,7 +14,7 @@ Please first discuss the change you wish to make via an issue before making a ch - Click on the Customize button > - Click OK button -NB: Running all tests are not required as the CI build will do these. Test verify any tests you have impacted. +NB: Running all tests are not required as the CI build will do these. Test and verify only the steps or features you have impacted or made changes to. ## Pull request process From 9b73b633f2f1ae79c74f6951724def3212f51e0f Mon Sep 17 00:00:00 2001 From: Tom Ashworth Date: Mon, 26 Sep 2022 10:59:15 +0100 Subject: [PATCH 3/9] docs: elaborate on testing process for new contributors Resolves #132 --- CONTRIBUTING.md | 40 ++++++++++++++++++++++++++-------------- 1 file changed, 26 insertions(+), 14 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dbc96cf..a3c13b3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,21 +4,33 @@ Please first discuss the change you wish to make via an issue before making a ch ## Testing -1. Set up powerapps binding -2. Application user may be added with the system admin rights -3. Tests by default is on US datetime format, therefore change it based on your personal location. For example, if you are based in India, set the datetime format to the local time. -- This can be done by going to the Power Apps settings > -- Select Pernalization Settings > -- From the Set Personal Options page, click on the Formats menu > -- Change the Current Format from the dropdown by ther selecting the country of your location > -- Click on the Customize button > -- Click OK button - -NB: Running all tests are not required as the CI build will do these. Test and verify only the steps or features you have impacted or made changes to. +For a PR to be successfully merged, we aim for all tests to pass. Sometimes this isn't possible as the Power Platform changes, our tests aren't always kept up to date. We do require that there are tests for new/changed features and these. + + +In order to test the library locally, please follow these steps: + +1. Open the solution in Visual Studio - we've found this has the best developer experience. Install the [SpecFlow extension](https://marketplace.visualstudio.com/items?itemName=TechTalkSpecFlowTeam.SpecFlowForVisualStudio2022) to add intellisense to the `.feature` files. +1. [Optional] Create a PowerApps environment. You need a PowerApps environment to execute the tests against so if you don't have System Administrator access to an existing one, we recommend using the free [Developer Plan](https://powerapps.microsoft.com/en-us/developerplan/). +1. [Adjust environment personalization](https://powerusers.microsoft.com/t5/Building-Power-Apps/Model-driven-app-dates-in-UK-format/td-p/1520165). Our tests expect a UK format for dates, times, and currency so please set this for any configured users (below). +1. Configure the test suite to use your environment. The `power-apps-bindings.yml` file holds these details. Each property value can either point to a [user environment variable](https://www.alphr.com/environment-variables-windows-10/) or hold the raw value. **We strongly recommend environment variables to avoid committing your credentials.** The following properties are required: + - `url` + - `applicationUser` - an [Application User](https://learn.microsoft.com/en-us/power-platform/admin/manage-application-users#create-an-application-user) must be added with the System Administrator role to your environment. + - `users` - this can be your account, there is no need to create additional user. All username and password can be identical. +1. Tweak config for local debugging. The `power-apps-bindings.yml` file is configured for use by the build server (that runs all tests before merge a PR) and therefore it is recommended to change the following properties without committing them. + - Change `headless` to `false` so you can observer the tests run. + - Comment `driversPath` as this environment variable won't exist locally e.g. + ```yml + #driversPath: ChromeWebDriver + ``` + +Other things to note: + +- Running all tests are **not** required as the CI/PR build will do these. Test and verify only the steps or features you have impacted or made changes to. +- The first time you run the test suite, a managed solution will be installed into the environment which takes a couple minutes. If the first test run times out, try again - it was likely due to this. ## Pull request process 1. Ensure that there are automated tests that cover any changes -2. Update the README.md with details of any significant changes to functionality -3. Ensure that your commit messages increment the version using [GitVersion syntax](https://gitversion.readthedocs.io/en/latest/input/docs/more-info/version-increments/). If no message is found then the patch version will be incremented by default. -4. You may merge the pull request once it meets all of the required checks. If you do not have permision, a reviewer will do it for you \ No newline at end of file +1. Update the README.md with details of any significant changes to functionality +1. Ensure that your commit messages increment the version using [GitVersion syntax](https://gitversion.readthedocs.io/en/latest/input/docs/more-info/version-increments/). If no message is found then the patch version will be incremented by default. +1. You may merge the pull request once it meets all of the required checks. If you do not have permision, a reviewer will do it for you \ No newline at end of file From 663b70373596f46e0eb9c781dd7fe00efefd89f2 Mon Sep 17 00:00:00 2001 From: Osagie Okoedo Date: Mon, 26 Sep 2022 14:58:11 +0100 Subject: [PATCH 4/9] Updating CONTRIBUTING.md file --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a3c13b3..238c69b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,6 +27,7 @@ Other things to note: - Running all tests are **not** required as the CI/PR build will do these. Test and verify only the steps or features you have impacted or made changes to. - The first time you run the test suite, a managed solution will be installed into the environment which takes a couple minutes. If the first test run times out, try again - it was likely due to this. +- At times when buiding a solution, it fails and you receive some Build.exe errors or warnings. This prevents you from cancelling the build process as it hangs. You can stop or kill the Build.exe proceess by starting the Task Master and ending the process - you can close the Visual Studio and restart it if this doesn't work. You can also run this code (taskkill /f /im chromedriver.exe) on your terminal. ## Pull request process From 3961e365f20b56d5029d0d9bd538cbe43481d1c0 Mon Sep 17 00:00:00 2001 From: Osagie Okoedo Date: Mon, 26 Sep 2022 15:10:40 +0100 Subject: [PATCH 5/9] Added the 'Useful Resources' section on the CONTRIBUTING.md file --- CONTRIBUTING.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 238c69b..bae1885 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,4 +34,7 @@ Other things to note: 1. Ensure that there are automated tests that cover any changes 1. Update the README.md with details of any significant changes to functionality 1. Ensure that your commit messages increment the version using [GitVersion syntax](https://gitversion.readthedocs.io/en/latest/input/docs/more-info/version-increments/). If no message is found then the patch version will be incremented by default. -1. You may merge the pull request once it meets all of the required checks. If you do not have permision, a reviewer will do it for you \ No newline at end of file +1. You may merge the pull request once it meets all of the required checks. If you do not have permision, a reviewer will do it for you + +## Useful Resources +- A presentation on the SpecFlowBinding and EasyRepro setup with demo https://triciasinclair.com/2020/11/30/using-specflow-and-easyrepro-to-improve-automated-ui-testing/ From f60c37885c5beb2167e6abe507f32e55acf30efe Mon Sep 17 00:00:00 2001 From: Tom Ashworth Date: Tue, 27 Sep 2022 13:56:31 +0100 Subject: [PATCH 6/9] docs: project architecture --- CONTRIBUTING.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bae1885..6ebad9f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,31 @@ # Contributing Please first discuss the change you wish to make via an issue before making a change. - + +To build this project locally, you will need: +- [Visual Studio 2020](https://visualstudio.microsoft.com/vs/) +- [SpecFlow for Visual Studio 2022](https://marketplace.visualstudio.com/items?itemName=TechTalkSpecFlowTeam.SpecFlowForVisualStudio2022) +- [.NET Framework 4.6.2 Developer Pack](https://dotnet.microsoft.com/en-us/download/dotnet-framework/net462) +- [Node and NPM](https://nodejs.org/en/download/) + +## Architechture + +This project fundermentally utilises [Selenium](https://www.selenium.dev/) to automate user actions in the browser with the support of [Easy Repro](https://github.com/Microsoft/EasyRepro), which extends Selenium for Model-Driven apps. + +Typically the use of EasyRepro is preferred due to it's backing from Microsoft and the community although when an action isn't working, some temporary custom code will be used until the issue has been resolved. This is also the case in the rare instance that EasyRepro doesn't support a particular action. + +```mermaid +sequenceDiagram +Specflow->>Bindings: 1. Maps Given/When/Then scenarios to code +Bindings->>Easy Repro: 2a. Calls an existing Easy Repro action +Bindings-->>Selenium: 2b. Otherwise calls the Selenium API directly +Easy Repro->>Selenium: 3. Performs common and standard actions +Selenium->>Browser: 4. Queries the DOM/simulates user actions +Browser->>Driver: 5. Manages test data +``` + +In addition to the Specflow bindings, there is a custom "driver" that wraps the [Model-Driven Client-Side API](https://learn.microsoft.com/en-us/power-apps/developer/model-driven-apps/clientapi/reference) to support test data setup via the Dataverse API. This is written in TypeScript and compiled to JavaScript before being bundled in the DLL. + ## Testing For a PR to be successfully merged, we aim for all tests to pass. Sometimes this isn't possible as the Power Platform changes, our tests aren't always kept up to date. We do require that there are tests for new/changed features and these. From fa86187028d3bc0cb5da7b20637f787a93da190e Mon Sep 17 00:00:00 2001 From: Osagie Okoedo Date: Tue, 27 Sep 2022 15:01:53 +0100 Subject: [PATCH 7/9] Update CONTRIBUTING.md Co-authored-by: Tom Ashworth --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6ebad9f..7c7b932 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,7 +51,7 @@ Other things to note: - Running all tests are **not** required as the CI/PR build will do these. Test and verify only the steps or features you have impacted or made changes to. - The first time you run the test suite, a managed solution will be installed into the environment which takes a couple minutes. If the first test run times out, try again - it was likely due to this. -- At times when buiding a solution, it fails and you receive some Build.exe errors or warnings. This prevents you from cancelling the build process as it hangs. You can stop or kill the Build.exe proceess by starting the Task Master and ending the process - you can close the Visual Studio and restart it if this doesn't work. You can also run this code (taskkill /f /im chromedriver.exe) on your terminal. +- At times when building a solution, it fails and you receive some MSBuild.exe errors or warnings. This prevents you from cancelling the build process as it hangs. You can stop or kill the MSBuild.exe process by starting the Task Manager and ending the process - you can close the Visual Studio and restart it if this doesn't work. You can also run this code `taskkill /f /im chromedriver.exe` on your terminal. ## Pull request process From eb9bf7b0db4832c87b742e97c781c699541988d0 Mon Sep 17 00:00:00 2001 From: Osagie Okoedo Date: Tue, 27 Sep 2022 15:02:22 +0100 Subject: [PATCH 8/9] Update CONTRIBUTING.md Co-authored-by: Tom Ashworth --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7c7b932..7745909 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -61,4 +61,4 @@ Other things to note: 1. You may merge the pull request once it meets all of the required checks. If you do not have permision, a reviewer will do it for you ## Useful Resources -- A presentation on the SpecFlowBinding and EasyRepro setup with demo https://triciasinclair.com/2020/11/30/using-specflow-and-easyrepro-to-improve-automated-ui-testing/ +- [A presentation on the SpecFlowBinding and EasyRepro setup with demo] (https://triciasinclair.com/2020/11/30/using-specflow-and-easyrepro-to-improve-automated-ui-testing/) From fd76417c58d969dcaf579351f519013b60701bb0 Mon Sep 17 00:00:00 2001 From: Tom Ashworth Date: Tue, 27 Sep 2022 15:28:23 +0100 Subject: [PATCH 9/9] Update CONTRIBUTING.md --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7745909..65536e2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -61,4 +61,4 @@ Other things to note: 1. You may merge the pull request once it meets all of the required checks. If you do not have permision, a reviewer will do it for you ## Useful Resources -- [A presentation on the SpecFlowBinding and EasyRepro setup with demo] (https://triciasinclair.com/2020/11/30/using-specflow-and-easyrepro-to-improve-automated-ui-testing/) +- [A presentation on the SpecFlowBinding and EasyRepro setup with demo](https://triciasinclair.com/2020/11/30/using-specflow-and-easyrepro-to-improve-automated-ui-testing/)