msportalfx-test
Generated on 2020-05-06
- msportalfx-test
- Overview
- Getting Started
- Side loading a local extension during the test session
- Running
- Debugging
- Localization
- User Management
- Configuration
- Scenarios
Overview
MsPortalFx-Test is an end-to-end test framework that runs tests against the Microsoft Azure Portal interacting with it as a user would.
Goals
- Strive for zero breaking changes to partner team CI
- Develop tests in the same language as the extension
- Focus on partner needs rather than internal portal needs
- Distributed independently from the SDK
- Uses an open source contribution model
- Performant
- Robust
- Great Docs
General Architecture
3 layers of abstraction (note the names may change but the general idea should be the same). There may also be some future refactoring to easily differentiate between the layers.
-
Test layer
- Useful wrappers for testing common functionality. Will retry if necessary. Throws if the test/verification fails.
- Should be used in writing tests
- Built upon the action and control layers
- EG: parts.canPinAllBladeParts
-
Action layer
- Performs an action and verifies it was successful. Will retry if necessary.
- Should be used in writing tests
- Built upon the controls layer
- EG: portal.openBrowseBlade
-
Controls layer
- The basic controls used in the portal (eg blades, checkboxes, textboxes, etc). Little to no retry logic. Should be used mainly for composing the actions and tests layers.
- Should be used for writing test and action layers. Should not be used directly by tests in most cases.
- Built upon webdriver primitives
- EG: part, checkbox, etc
Getting Started
Installation
-
Install Node.js if you have not done so. This will also install npm, which is the package manager for Node.js. We have only verified support for LTS Node versions 4.5 and 5.1 which can be found in the "previous downloads" section. Newer versions of Node are known to have compilation errors.
-
Install Node Tools for Visual Studio
-
Install TypeScript 1.8.10 or greater.
-
Verify that your:
- node version is v8.11.3 LTS using
node -v
- npm version is 5.6.0 or greater using
npm -v
. To update npm version usenpm install npm -g
- tsc version is 1.8.10 or greater using tsc -v.
- node version is v8.11.3 LTS using
-
Open a command prompt and create a directory for your test files.
md e2etests
-
Switch to the new directory and install the msportalfx-test module via npm:
cd e2etests npm install msportalfx-test --no-optional
-
The msportalfx-test module comes with some TypeScript definitions and its dependencies. To make them available to your tests, we recommend that you use the typings Typescript Definition Manager.
-
First install the typings Typescript Definition Manager globally:
npm install typings -g
Next copy the provided typings.json file and the msportalfx-test.d.ts file from the node_modules/msportalfx-test/typescript folder to your test root directory and use typings to install the provided definitions:
*copy typings.json to your test root directory* *navigate to your test root directory* typings install
-
MsPortalFx-Test needs a WebDriver server in order to be able to drive the browser. Currently only ChromeDriver is supported, so downloaded it and place it in your machine's PATH or just install it from the chromedriver Node module. You may also need a C++ compiler (Visual Studio includes one):
npm install chromedriver
Write a test
You'll need an existing cloud service for the test you'll write below, so if you don't have one please go to the Azure Portal and create a new cloud service. Write down the dns name of your cloud service to use it in your test.
We'll use the Mocha testing framework to layout the following test, but you could use any framework that supports Node.js modules and promises. Let's install Mocha and its typescript definitions:
npm install mocha
npm install @types/mocha
Now, create a portaltests.ts file in your e2etests directory and paste the following:
/// ;;;; describe'Cloud Service Tests', ;
- write credentials to the windows credential manager
cmdkey /generic:msportalfx-test/johndoe@outlook.com/signInPassword /user:johndoe@outlook.com /pass:somePassword
Remember to replace "mycloudservice" with the dns name of your actual cloud service.
In this test we start by importing the MsPortalFx-Test module. Then the credentials are specified for the user that will sign in to the Portal. These should be the credentials of a user that already has an active Azure subscription.
After that we can use the Portal object to drive a test scenario that opens the Cloud Services Browse blade, filters the list of cloud services, checks that the grid has only one row after the filter, selects the only row and waits for the correct blade to open. Finally, the call to quit() closes the browser.
Add the configuration
Create a file named config.json next to portaltests.ts. Paste this in the file:
```json
{
"capabilities": {
"browserName": "chrome"
},
"portalUrl": "https://portal.azure.com"
}
```
This configuration tells MsPortalFx-Test that Google Chrome should be used for the test session and https://portal.azure.com should be the Portal under test.
Compile and run
Compile your TypeScript test file (note if you are using a newer version of TSC than 1.8 then you may need to pass in additional flags that aren't present in older versions of TSC):
(TSC 1.8) tsc portaltests.ts --module commonjs
(TSC 3+) tsc portaltests.ts --module commonjs --lib es2015 --moduleResolution classic
...and then run Mocha against the generated JavaScript file (note using an elevated command prompt may cause Chrome to crash. Use a non-elevated command prompt for best results):
node_modules\.bin\mocha portaltests.js
The following output will be sent to your console as the test progresses:
Portal Tests
Opening the Browse blade for the microsoft.classicCompute/domainNames resource type...
Starting the ChromeDriver process...
Performing SignIn...
Waiting for the Portal...
Waiting for the splash screen to go away...
Applying filter 'mycloudservice'...
√ Can Browse To A Cloud Service (37822ms)
1 passing (38s)
If you run into a compilation error with node.d.ts, verify that the tsc version you are using matches the compilation command above. You can check the version by running:
tsc --version
If the version is incorrect, then you may need to adjust your path variables or directly call the correct version of tsc.exe. A version of tsc is usually included in the node_modules folder at node_modules/.bin/tsc that can be used.
If you see errors regarding duplicate identifiers due to some definitions being imported twice, you can try setting moduleResolution compiler option to classic in your tsconfig.json file.
Updating
-
In order to keep up to date with the latest changes, we recommend that you update whenever a new version of MsportalFx-Test is released. npm install will automatically pull the latest version of msportalfx-test.
Make sure to copy typescript definition files in your *typings\* folder from the updated version in *\node_modules\msportalfx-test\typescript*.
More Examples
More examples can be found
- within this document
- in the msportalfx-test /test folder
- and the Contacts Extension Tests.
If you don't have access, please follow the enlistment instructions below.
Running tests in Visual Studio
-
Install Node Tools for Visual Studio (Note that we recommend using the Node.js “LTS” versions rather than the “Stable” versions since sometimes NTVS doesn’t work with newer Node.js versions.)
-
Once that’s done, you should be able to open Visual Studio and then create new project: New -> Project -> Installed, Templates, TypeScript, Node.js -> From Existing Node.js code.
- Then open the properties on your typescript file and set the TestFramework property to “mocha”.
- Once that is done you should be able to build and then see your test in the test explorer. If you don’t see your tests, then make sure you don’t have any build errors. You can also try restarting Visual Studio to see if that makes them show up.
Side loading a local extension during the test session
You can use MsPortalFx-Test to write end to end tests that side load your local extension in the Portal. You can do this by specifying additional options in the Portal object. If you have not done so, please take a look at the Installation section of this page to learn how to get started with MsPortalFx-Test.
We'll write a test that verifies that the Browse experience for our extension has been correctly implemented. But before doing that we should have an extension to test and something to browse to, so let's work on those first.
To prepare the target extension and resource:
-
Create a new Portal extension in Visual Studio following these steps and then hit CTRL+F5 to get it up and running. For the purpose of this example we named the extension 'LocalExtension' and we made it run in the default https://localhost:44300 address.
-
That should have taken you to the Portal, so sign in and then go to New --> Marketplace --> Local Development --> LocalExtension --> Create.
-
In the My Resource blade, enter theresource as the resource name, complete the required fields and hit Create.
-
Wait for the resource to get created.
To write a test verifies the Browse experience while side loading your local extension:
-
Create a new TypeScript file called localextensiontests.ts.
-
In the created file, import the MsPortalFx-Test module and layout the Mocha test:
///;;;describe'Local Extension Tests',; -
In the Can Browse To The Resource Blade test body, specify the credentials for the test session (replace with your actual Azure credentials):
// Hardcoding credentials to simplify the example, but you should never hardcode credentialstestFx.portal.portalContext.signInEmail = 'johndoe@outlook.com';testFx.portal.portalContext.signInPassword = '12345'; -
Now, use the features option of the portal.PortalContext object to enable the canmodifyextensions feature flag and use the testExtensions option to specify the name and address of the local extension to load:
testFx.portal.portalContext.features = ;testFx.portal.portalContext.testExtensions = ; -
Let's also declare a variable with the name of the resource that the test will browse to:
; -
To be able to open the browse blade for our resource we'll need to know three things: The resource provider, the resource type and the title of the blade. You can get all that info from the Browse PDL implementation of your extension. In this case the resource provider is Microsoft.PortalSdk, the resource type is rootResources and the browse blade title is My Resources. With that info we can call the openBrowseBlade function of the Portal object:
return testFx.portal.openBrowseBlade'Microsoft.PortalSdk', 'rootResources', 'My Resources' -
From there on we can use the returned Blade object to filter the list, verify that only one row remains after filtering and select that row:
.then.then -
And finally we'll verify the correct blade opened and will close the Portal when done:
.then.then; -
Here for the complete test:
/// ;;; describe'Local Extension Tests', ;
To add the required configuration and run the test:
-
Create a file named config.json next to localextensiontests.ts. Paste this in the file:
-
Compile your TypeScript test file:
tsc localextensiontests.ts --module commonjs
-
Run Mocha against the generated JavaScript file:
node_modules\.bin\mocha localextensiontests.js
The following output will be sent to your console as the test progresses:
Local Extension Tests
Opening the Browse blade for the Microsoft.PortalSdk/rootResources resource type...
Starting the ChromeDriver process...
Performing SignIn...
Waiting for the Portal...
Waiting for the splash screen...
Allowing trusted extensions...
Waiting for the splash screen to go away...
Applying filter 'theresource'...
√ Can Browse To The Resource Blade (22872ms)
1 passing (23s)
Running
In Dev
From VS
From cmdline
CI
Cloudtest
Running mocha nodejs tests in cloudtest requires a bit of engineering work to set up the test VM. Unfortunetly, the nodejs test adaptor cannot be used with vs.console.exe since it requires a full installation of Visual Studio which is absent on the VMs. Luckily, we can run a script to set up our environment and then the Exe Execution type for our TestJob against the powershell/cmd executable.
Environment Setup
Nodejs (and npm) is already installed on the cloudtest VMs. Chrome is not installed by default, so we can include the chrome executable in our build drop for quick installation.
setup.bat
cd UITests
call npm install --no-optional
call npm install -g typescript
call "%APPDATA%\npm\tsc.cmd"
call chrome_installer.exe /silent /install
exit 0
Running Tests
Use the Exe execution type in your TestJob to specify the powershell (or cmd) exe. Then, point to a script which will run your tests:
TestGroup.xml
<TestJob Name="WorkspaceExtension.UITests" Type="SingleBox" Size="Small" Tags="Suite=Suite0">
<Execution Type="Exe" Path="C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" Args='[SharedWorkingDirectory]\UITests\RunTests.ps1' />
</TestJob>
At the end of your script you will need to copy the resulting trx file to the TestResults folder where Cloudtest expects to pick it up from. To generate a trx file, we used the mocha-trx-reporter npm package. To pass secrets to cloudtest, you can either use test secretstore which has been configured to use a certificate installed on all cloudtest VMs for particular paths, or one of the other solutions shown here
RunTests.ps1
cd ..\UITests
$env:USER_EMAIL = ..\StashClient\StashClient.exe -env:test pgetdecrypted -name:Your/Secret/Path -cstorename:My -cstorelocation:LocalMachine -cthumbprint:0000000000000000000000000000000000000000
$env:USER_PASSWORD = ..\StashClient\StashClient.exe -env:test pgetdecrypted -name:Your/Secret/Path -cstorename:My -cstorelocation:LocalMachine -cthumbprint:0000000000000000000000000000000000000000
$env:TEST_ENVIRONMENT = [environment]::GetEnvironmentVariable("TEST_ENVIRONMENT","Machine")
mocha WorkspaceTests.js --reporter mocha-trx-reporter --reporter-file ./TestResults/result.trx
xcopy TestResults\* ..\TestResults
To pass non-secret parameters to your cloudtest session (and the msportalfx-tests) use the props switch when kicking off a cloudtest session. The properties will become machine level environment variables on your cloudtest VM. Once these are set as environment variables of the session, you can use nconf to pick them up in your UI test configuration.
ct -t "amd64\CloudTest\TestMap.xml" -tenant Default -BuildId "GUID" -props worker:TEST_ENVIRONMENT=canary
Windows Azure Engineering System (WAES)
See WAES
Jenkins
How to setup test run parallelization
Debugging
debug tests 101
debugging tests in VS Code
If you run mocha with the --debug-brk flag, you can press F5 and the project will attach to a debugger.
Checking the result of the currently running test in code
Sometimes it is useful to get the result of the currently running test, for example: you want to take a screenshot only when the test fails.
afterEach;
One thing to watch out for in typescript is how lambda functions, "() => {}", behave. Lambda functions (also called "fat arrow" sometimes) in Typescript capture the "this" variable from the surrounding context. This can cause problems when trying to access Mocha's current test state. See arrow functions for details.
How to take a screenshot of the browser
This is an example of how to take a screenshot of what is currently displayed in the browser.
//1. import test fx;... ;
Taking a screenshot when there is a test failure is a handy way to help diagnose issues. If you are using the mocha test runner, then you can do the following to take a screenshot whenever a test fails:
;... afterEach;
How to capture browser console output
When trying to identify reasons for failure of a test its useful to capture the console logs of the browser that was used to execute your test. You can capture the logs at a given level e.g error, warning, etc or at all levels using the LogLevel parameter. The following example demonstrates how to call getBrowserLogs and how to work with the result. getBrowserLogs will return a Promise of string[] which when resolved will contain the array of logs that you can view during debug or write to the test console for later analysis.
;... await testFx.portal.goHome20000; ; assert.oklogs.length > 0, "Expected to collect at least one log.";
Callstack
Test output artifacts
Localization
User Management
Configuration
Configuration options
This document will describe the behavior and list common configuration settings used by the MsPortalFx-Test framework.
Behavior
The test framework will search for a config.json in the current working directory (usually the directory the test is invoked from). If no config.json is found then it will check the parent folder for a config.json (and so on...).
PortalContext
This file contains a list of configuration values used by the test framework for context when running tests against the portal. These values are mutable to allow test writers to set the values in cases where they prefer not to store them in the config.json. We strongly recommend that passwords should not be stored in the config.json file.
;;;; /** * Represents The set of options used to configure a Portal instance. */ ;
Running tests against the Dogfood environment
In order to run tests against the Dogfood test environment, you will need to update the follow configuration settings in the config.json:
Scenarios
Create
Opening the create blade from a deployed gallery package
To open/navigate to the create blade a gallery package previously deployed to the Azure Marketplace you can use portal.openGalleryCreateBlade
. The returned promise will resolve with the CreateBlade defined by that gallery package.
;...FromLocalPackage await testFx.portal.openGalleryCreateBladeFromLocalPackage extensionResources.samplesExtensionStrings.Engine.engineNoPdl, //title of the item in the marketplace e.g "EngineNoPdlV1" extensionResources.samplesExtensionStrings.Engine.createEngine, //the title of the blade that will be opened e.g "Create Engine" 10000; //an optional timeout to wait on the blade await createEngineBlade.checkFieldValidation; await createEngineBlade.fillRequiredFieldsresourceName, "800cc", "type1", subscriptionName, resourceName, locationDescription; await createEngineBlade.reviewAndCreateButton.click; await testFx.portal.wait!await createEngineBlade.createButton.hasClassCssClassNames.Controls.buttonDisabled; await createEngineBlade.createButton.click; await testFx.portal.wait until.isPresenttestFx.portal.blade, 120000, "The resource blade was not opened, could be deployment timeout."; ...
Opening the create blade from a local gallery package
To open/navigate to the create blade a local gallery package that has been side loaded into the portal along with your extension you can use portal.openGalleryCreateBladeFromLocalPackage
. The returned promise will resolve with the CreateBlade defined by that gallery package.
;... await testFx.portal.openGalleryCreateBladeFromLocalPackage extensionResources.samplesExtensionStrings.Engine.engineNoPdl, //title of the item in the marketplace e.g "EngineNoPdlV1" extensionResources.samplesExtensionStrings.Engine.createEngine, //the title of the blade that will be opened e.g "Create Engine" 10000; //an optional timeout to wait on the blade await createEngineBlade.checkFieldValidation; await createEngineBlade.fillRequiredFieldsresourceName, "800cc", "type1", subscriptionName, resourceName, locationDescription; await createEngineBlade.reviewAndCreateButton.click; await testFx.portal.wait!await createEngineBlade.createButton.hasClassCssClassNames.Controls.buttonDisabled; await createEngineBlade.createButton.click; await testFx.portal.wait until.isPresenttestFx.portal.blade, 120000, "The resource blade was not opened, could be deployment timeout."; ...
Validation State
Get the validation state of fields on your create form
FormElement
exposes two useful functions for working with the ValidationState of controls.
The function getValidationState
returns a promise that resolves with the current state of the control and can be used as follows
;... //click the createButton on the create blade to fire validation await this.createButton.click; //get the validation state of the control await this.elementBy.chainedBy.className"fxs-blade-statusbg", By.className"fxs-bg-error"; await this.elementBy.classNametabClass.click; ; //assert state matches expected assert.equalstate, testFx.Constants.ControlValidationState.invalid, "name should have invalid state"; ...
Wait on a fields validation state
The function waitOnValidationState(someState, optionalTimeout)
returns a promise that resolves when the current state of the control is equivalent to someState supplied. This is particularly useful for scenarions where you may be performing serverside validation and the control remains in a pending state for the duration of the network IO.
;... //change the value to initiate validation await this.elementBy.classNametabClass.click; await this.primaryEngine.sendKeysnameTxt + webdriver.Key.TAB; //wait for the control to reach the valid state await this.primaryEngine.waitOnValidationStatetestFx.Constants.ControlValidationState.valid;...
Browse
How to test the context menu in browse shows your extensions commands?
There is a simple abstraction available in MsPortalFx.Tests.Browse. You can use it as follows:
//1. import test fx; ... it"Can Use Context Click On Browse Grid Rows",;
How to test the grid in browse shows the expected default columns for your extension resource
There is a simple abstraction available in MsPortalFx.Tests.Browse. You can use it as follows:
//1. import test fx; ... it"Browse contains default columns with expected column header",
How to test the grid in browse shows additional extension resource columns that are selected
There is a simple abstraction available in MsPortalFx.Tests.Browse that asserts extension resource specific columns can be selected in browse and that after selection they show up in the browse grid.
the function is called canSelectResourceColumns
. You can use it as follows:
// 1. import test fx; ... it"Can select additional columns for the resourcetype and columns have expected title",
Blades
Blade navigation
To navigate to blades within msportalfx-test can use one of several approaches
-
via a deep link to the blade using the
portal.navigateToUriFragment
function e.g;...;;;//form deep link to the quickstart bladeawait testFx.portal.navigateToUriFragment`blade/SamplesExtension/EngineQuickStartBlade/id/`, timeouts.defaultLongTimeout;return testFx.portal.waitExpectedConditions.isPresenttestFx.portal.blade, timeouts.defaultLongTimeout, "Quickstart blade was not found."; -
via clicking on another ux component that opens the blade
// New sample needed -
via
portal.open*
functions open common portal blades like create, browse and resource summary blades. See Opening common portal blades -
via
portal.search
function to search for, and open browse and resource blades;...// const subscriptionsBlade = testFx.portal.blade({ title: testSupport.subscription });// testFx.portal.portalContext.features.push({ name: "feature.resourcemenu", value: "true" });// return testFx.portal.goHome().then(() => {// return testFx.portal.search(testSupport.subscription);// }).then((results) => {// return testFx.portal.wait<SearchResult>(() => {// const result = results[0];// return result.title.getText().then((title) => {// return title === testSupport.subscription ? result : null;// });// });// }).then((result) => {// return result.click();// }).then(() => {// return testFx.portal.wait(until.isPresent(subscriptionsBlade));// });
Locating an open blade
There are several approaches that can be used for locating an already opened blade use testfx.portal.blade
.
-
by blade title
; -
by using an existing blade type and its predefined locator
;
Common portal blades
Opening the extensions Create blade
See Opening an extensions gallery package create blade
Opening the Browse blade for your resource
To open/navigate to the Browse blade from resource type you can use portal.openBrowseBlade
. The returned promise will resolve with the browse blade.
;... ; ...
Opening a Resource Summary blade
To open/navigate to the Resource Summary blade for a specific resource you can use portal.openResourceBlade
. The returned promise will resolve with the Resource summary blade for the given resource.
;... ; await testFx.portal.openResourceBladeresult.resourceGroup.id, result.resourceGroup.name, 70000; await resourceBlade.clickCommandextensionResources.hubsExtension.resourceGroups.deleteResourceGroupLabel;...
Spec Picker Blade
The SpecPickerBlade
can be used to select/change the current spec of a resource. The following example demonstrates how to navigate to the spec picker for a given resource then changes the selected spec.
//1. imports;; ; //2. Open navigate blade and select the pricing tier part. // Note if navigating to a resourceblade use testFx.portal.openResourceBlade and blade.element await testFx.portal.navigateToUriFragment"blade/SamplesExtension/PricingTierV3Blade", 75000; await pricingTierBlade.waitUntilBladeAndAllTilesLoaded; ; await pricingTierPart.click; //3. get a reference to the picker blade and pick a spec ; await pickerBlade.pickSpecextensionResources.M;
There are also several API's available to make testing common functionality within browse such as context menu commands and column picking fucntionality for more details see Browse Scenarios.
Properties Blade
Navigation to the PropertiesBlade
is done via the resource summary blade. The following demonstrates how to navigate to the properties blade
;...//2. navigate to the properties blade from the resource blade and check the value of one of the properties ; await resourceBlade.openMenuItemPortalFxResources.properties; ; await testFx.portal.wait, null, testFx.Utils.String.format"Expected to have {0} properties in the Properties blade.", expectedPropertiesCount; ; ; ; return assert.equalnameProperty, resourceName, testFx.Utils.String.format"Expected the value for the 'NAME' property to be '{0}' but found '{1}'.", resourceName, nameProperty; ...
QuickStart Blade
Using a deep link you can navigate directly into a QuickStartBlade
for a resource with Portal.navigateToUriFragment
.
;... ; ; ; //form deep link to the quickstart blade await testFx.portal.navigateToUriFragment`blade/SamplesExtension/EngineQuickStartBlade/id/`, timeouts.defaultLongTimeout; return testFx.portal.waitExpectedConditions.isPresenttestFx.portal.blade, timeouts.defaultLongTimeout, "Quickstart blade was not found.";
While deeplinking is fast it does not validate that the user can actually navigate to a QuickStartBlade via a ResourceSummaryPart
on a resource summary blade. The following demonstrates how to verify the user can do so.
;...//1. model your resource summary blade which contains a resource summary part ;; ...//2. navigate to the quickstart and click a link ; ; //click to open the quickstart blade await resourceBlade.openMenuItemPortalFxResx.quickStartMenu; await testFx.portal.wait, null, "Title of the blade should update to include the Quickstart suffix"; ...
Users Blade
Using a deep link you can navigate directly into the user access blade for a resource with Portal.navigateToUriFragment
.
;... ; ; ; //form deep link to the quickstart blade await testFx.portal.navigateToUriFragment`blade/Microsoft_Azure_AD/UserAssignmentsBlade/scope/`, timeouts.defaultLongTimeout; return await testFx.portal.waitExpectedConditions.isPresenttestFx.portal.elementtestFx.Blades.UsersBlade;
While deeplinking is fast it does not validate that the user can actually navigate to a UsersBlade via a ResourceSummaryPart
on a resource summary blade. The following demonstrates how to verify the user can do so.
;...//1. model your resource summary blade which contains a resource summary part ;; ...//2. navigate to the quickstart and click a link ; ; //click to open the user access blade await resourceBlade.openMenuItemPortalFxResx.usersMenu; await testFx.portal.wait, null, "Title of the blade should update to include the Users suffix"; ...
Move Resource Blade
The MoveResourcesBlade
represents the portals blade used to move resources from a resource group to a new resource group portal.startMoveResource
provides a simple abstraction that will iniate the move of an existing resource to a new resource group. The following example demonstrates how to initiate the move and then wait on successful notification of completion.
;... await testFx.portal.startMoveResource ; return await testFx.portal.elementNotificationsPane.waitForNewNotificationportalFxResources.movingResourcesComplete, null, 5 * 60 * 1000;
Blade Dialogs
On some blades you may use commands that cause a blade dialog that generally required the user to perform some acknowledgement action.
The Blade
class exposes a dialog
function that can be used to locate the dialog on the given blade and perform an action against it.
The following example demonstrates how to:
- get a reference to a dialog by title
- find a field within the dialog and sendKeys to it
- clicking on a button in a dialog
;... ; await testFx.portal.goHome70000; await testFx.portal.navigateToUriFragment"blade/InternalSamplesExtension/BladeWithToolbar"; ; blade = await blade.clickCommand"Form"; //get a reference to a dialog by title ; //sending keys to a field in a dialog await dialog.fieldtestFx.Controls.TextField, .sendKeys"Something goes here"; //clicking a button within a dialog await dialog.clickButtonextensionResources.ok;
Parts
How to get the reference to a part on a blade
- If it is a specific part, like the essentials for example:
let thePart = blade.element(testFx.Parts.ResourceSummaryPart);
- For a more generic part:
let thePart = blade.part({innerText: "some part text"});
- To get a handle of this part using something else than simple text you can also do this:
let thePart = blade.element(By.Classname("myPartClass")).AsType(testFx.Parts.Part);
CollectionPart
The following example demonstrates how to:
- get a reference to the collection part using
blade.element(...)
. - get the rollup count using
collectionPart.getRollupCount()
- get the rollup count lable using
collectionPart.getRollupLabel()
- get the grid rows using
collectionPart.grid.rows
it"Can get rollup count, rollup label and grid", ;
Note if you have multiple collection parts you may want to use blade.part(...)
to search by text.
Grid
Finding a row within a grid
The following demonstrates how to use Grid.findRow
to:
- find a
GridRow
with the given text at the specified index - get the text from all cells within the row using
GridRow.cells.getText
; ; return texts.length > 2 && texts === "John" && texts === "333";
CreateComboBoxField - Obsolete
use this for modeling the resouce group CreateComboBoxField
on create blades.
- use
selectOption(...)
to chose an existing resource group - use
setCreateValue(...)
andgetCreateValue(...)
to get and check the value of the create new field respectively
return testFx.portal.goHome40000.then.then;
ResourceGroupDropDownField
use this for modeling the resouce group ResourceGroupDropDownField
on create blades.
- use
setSelectedResourceGroup(...)
andgetSelectedResourceGroup
to get and check the value of the dropdown field respectively - use
setNewResourceGroup(...)
andgetNewResourceGroup(...)
to get and check the value of the create new field respectively
//1. open create blade await testFx.portal.openGalleryCreateBlade extensionResources.samplesExtensionStrings.Engine.engineNoPdl, //title of the item in the marketplace e.g "EngineNoPdlV1" extensionResources.samplesExtensionStrings.Engine.createEngine, //the title of the blade that will be opened e.g "Create Engine" 10000; //an optional timeout to wait on the blade //2. get a reference to the create blade ; //3. create the harness for the ResourceGroupDropDownField ; ; await createEngineBlade.checkFieldValidation; //4a. set the value of the Create New text field for the resource group await resourceGroup.setNewResourceGroup"NewResourceGroup"; ; assert.equal"NewResourceGroup", rgName, "Set resource group name"; //4b. set the value of the Use Existing dropdown await resourceGroup.setSelectedResourceGroup"Default-Storage-WestUS"; ; assert.equal"Default-Storage-WestUS", selectedRGName, "Set resource group dropdown"; await createEngineBlade.clickClose; await testFx.portal.acceptAlert; ; resourceGroup = await blade.fieldResourceGroupDropDown, ; resourceGroup.setNewResourceGroup"newRG";
Editor
Can read and write content
The following example demonstrates how to:
- use
read(...)
to read the content - use
empty(...)
to empty the content - use
sendKeys(...)
to write the content
; ; ; assert.equalcontent, expectedContent, "expectedContent is not matching"; await editor.empty; await editor.sendKeys"document."; await testFx.portal.wait; ; await editorBlade.elementsaveButton.click; await testFx.portal.wait; ; assert.equalcount, 0, "We did not find the expected number of iframes in the portal. It is likely that the editor is failing to start web workers and is falling back to creating new iframes";
essentials
Essentials tests
The following example demonstrates how to:
- use
countItems(...)
to count the number of all items. (MultiLine Item is counted as one) - use
isDisabled(...)
to get a value that determines whether the essentials is disabled - use
hasViewAll(...)
to get a value that determines whether the essentials has ViewAll button or not - use
getViewAllButton(...)
to get a PortalElement of the essentials' viewAll button - use
getItemByLabelText(...)
to get an EssentialsItem that is found by its label text - use
getPropertyElementByValue(...)
to get a PortalELement of matching property value - use
getExpandedState(...)
to get a value that determines the essentials' expanded state - use
setExpandedState(...)
to set the essentials' expanded state - use
getExpander(...)
to get the Expander element - use
getProperties(...)
to get an array of properties - use
getLabelText(...)
to get the item label text - use
hasMoveResource(...)
to get whether the item has move resource blade or not - use
getLabelId(...)
to get the item label id - use
getSide(...)
to get the item's side
try catch error
Command
Action Bar
Delete
Styling / layout regression detection
The CSS styling regression feature has been deprecated, please remove all usage of the portal.detectStylingRegression
function.
...
Locators
Consuming Updates
Mocking
How to show mock data into the Portal
The MsPortalFx-Mock package provides a framework for showing mock data in the portal. It come with builtin support for mocking ARM data.
Mocking ARM
Mock data including providers, subscriptions, resource groups and resources can be defined in JSON object and used to initialize the ArmManager.
;; ... ; ... ; armManager.initializeMockDatamockData;
The ArmProxy needs to initialized at the beginning of your tests with the ArmManager. The ArmProxy supports two modes for showing data 1) mock ONLY and 2) mock + actual.
You will need to initialize the portalContext->patches to the local server address setup by the proxy.
; armProxy = proxy; testFx.portal.portalContext.patches = ;
The proxy can be disposed at the end of your tests.
await testFx.portal.quit; await ArmProxy.disposearmProxy;
Code Coverage
Interop, how to run .NET code from your tests
edge.js
Accessibility Testing
Overview
Automated accessibility testing is enabled via './src/Accessibility.ts' which wraps two NPM libraries, 'axe-core' and 'axe-webdriverjs'.
- 'axe-core' is an accessibility testing library owned by "Deque Systems", see: https://github.com/dequelabs/axe-core.
- 'axe-webdriverjs' is a wrapper for 'axe-core' which simplifies the process of injecting axe-core code into the DOM when using selenium, see: https://github.com/dequelabs/axe-webdriverjs.
- In an effort to make accessibility testing as easy as possible, 'axe-webdriverjs' functionality was further wrapped by a function within 'Accessibility.ts' so that it can be executed with as little code as possible, and results can be surfaced as test failures. For microsoft tenants only: writing a pass/fail result to extension analyzer can be done by setting the optional parameter 'reportTestResult' to 'true'. For an example, see: https://extensionanalyzer.azure-test.net/extensions/Microsoft_Azure_Storage#blades, 'Accessibility (axe-core)' column.
- The function 'ensureAccessibilityIsAxeCoreClean' within './src/Accessibility.ts' is exposed as a public function by the PortalElement class within './src/PortalElement.ts', so any portal element can be tested for accessibilty compliance.
- The 'ensureAccessibilityIsAxeCoreClean' function is primarily intended to be used at the blade level, as script is executed to collect the extension and blade name for reporting purposes.
- In the case of blades which have controls which are dynamically rendered (create blades with tabs for example), the 'ensureAccessibilityIsAxeCoreClean' function can be called multiple times, and results can be differentiated by specifying a 'stepName' parameter, additional details below.
Sample Test
Here is the minimal amount of code necessary to test if a blade is accessible or not, from './test/AccessibilityTests.ts':
;;; describe"Can test accessibility of blades", ;
This code is opening the browse resource groups blade, and testing if it is accessible. The 'errorIdsToIgnore' parameter is used to ignore a set of errors by their error ID.
Options
Here is a copy of the options interface for the 'ensureAccessibilityIsAxeCoreClean' function, within './src/Accessibility.ts':
Contributing
To enlist
git clone https://github.com/azure/msportalfx-test.git
To build the source
Use Visual Studio or Visual Studio Code to build
How to build and push your changes
-
Go to the root directory
- npm run clean (This will wipe out any extra files you have in the directory)
-
Build the msportalfx-test package (see README.MD for details)
- npm install --no-optional
- Note the above command pulls dependencies and builds, if you just want to build use:
npm run build
-
Test your changes, see README.md for details on setup
- Check CI
- Alternatively run
npm test
to run tests locally
-
Push your changes
To setup the tests
- To run the tests you need:
- Create a dedicated test subscription that is used for tests only
- A user that has access to the test subscription only
- An AAD App and service principal with access
- Have run
setup.cmd
in the portal repo or have runpowershell.exe -ExecutionPolicy Unrestricted -file "%~dp0\Setup-OneCloud.ps1" -DeveloperType Shell %*
Once you have the first two use the following to create the AAD application and service principal.
msportalfx-test\scripts\Create-AdAppAndServicePrincipal.ps1 -TenantId "someguid" -SubscriptionId "someguid" -ADAppName "some ap name" -ADAppHomePage "https://somehomepage" -ADAppIdentifierUris "https://someidentiferuris" -ADAppPassword $someAdAppPassword -SPRoleDefinitionName "Reader"
Note: Don't forget to store the password you use below in key vault, secret store or other. You will not be able to retrieve it using the commandlets.
You will use the details of the created service principal in the next steps.
For more detail on [AAD Applications and Service Principals] see (https://azure.microsoft.com/en-us/documentation/articles/resource-group-authenticate-service-principal/#authenticate-with-password---powershell).
-
Open test\config.json and enter appropriate values for:
"aadAuthorityUrl": "https://login.windows.net/TENANT_ID_HERE", "aadClientId": "AAD_CLIENT_ID_HERE", "subscriptionId": "SUBSCRIPION_ID_HERE", "subscriptionName": "SUBSCRIPTION_NAME_HERE",
-
The account that corresponds to the specified credentials should have at least contributor access to the subscription specified in the config.json file. The account must be a Live Id account. It cannot be an account that requires two factor authentication (like most @microsoft.com accounts).
-
Install the Portal SDK from Aux Docs, then open Visual Studio and create a new Portal Extension from File --> New Project --> Azure Portal --> Azure Portal Extension. Name this project LocalExtension so that the extension itself is named LocalExtension, which is what many of the tests expect. Then hit CTRL+F5 to host the extension in IIS Express.
-
The Can Find Grid Row and the Can Choose A Spec tests require special configuration described in the tests themselves.
-
Many of the tests currently rely on the CloudService extension. We are working to remove this dependency.
To run the tests
Open a command prompt in this directory and run:
npm install --no-optional
npm test
Authoring documents
-
When adding a document create a new *.md file in /docs e.g /docs/foo.md
-
Author the document using markdown syntax
-
Inject content from your documents into the master template in /docs/TEMPLATE.md using gitdown syntax E.g
{"gitdown": "include", "file": "./foo.md"}
-
To ensure all code samples remain up to date we extended gitdown syntax to support code injection. To reference source code in your document directly from a *.ts file use the include-section extension E.g
{"gitdown": "include-section", "file": "../test/BrowseResourceBladeTests.ts", "section": "tutorial-browse-context-menu#step2"}
this will find all content in ../test/BrowseResourceBladeTests.ts that is wrapped in comments //tutorial-browse-context-menu#step2 and will inject them directly into the document. see /docs/tutorial-browse-context-menu.md for a working example
Generating the docs
You can generate the documentation in one of two ways
-
As part of pack the
docs
script from package.json is run to ensure that all docs are up to datenpm pack
-
Or, While you are writing docs you may want to check that your composition or jsdoc for API ref is generating as expected to do this you can execute run the following
npm run docs
the output of the composed TEMPLATE.md will be written to ./README.md and the generated API reference from your jsdocs will be written to /docs/apiref.md
To submit your contribution
Submit a pull request to the repo http://aka.ms/msportalfx-test
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Questions?
Send an email to ibizadiscuss@microsoft.com
API Reference
Generated on 2020-05-06