This guide provides instructions on how to build the repo and implement improvements.
Additional reading:
Install latest VS2019 (16.1 or later) from here: http://visualstudio.com/downloads
While WinUI is designed to work against many versions of Windows, you will need a fairly recent SDK in order to build WinUI. It's required that you install the 17763 and 18362 SDKs. You can download these via Visual Studio (check all the boxes when prompted), or you can manually download them from here: https://developer.microsoft.com/en-US/windows/downloads/windows-10-sdk
Generally you will want to set your configuration to Debug, x64, and select MUXControlsTestApp as your startup project in Visual Studio.
More information will be coming on this soon
More information will be coming on this soon
The WinUI solution project has a test app that is useful for validating common scenarios affected by the presence of the WinUI package. Set MUXControlsTestApp as your startup project in Visual Studio and you can F5 to start debugging that app and validate your changes.
MUXControlsTestApp is a no frills test app built for on demand developer scenarios and also to be automation friendly. As such it's perhaps not as friendly to navigate as something similarly control-centric like the Xaml Controls Gallery. That's a great potential area for future improvement, although MUXControlsTestApp must continue to function as an automation test target.
In the end developers will consume WinUI as a NuGet package in their own apps. So it's important to keep in mind that scenario when validating changes.
To enable automated NuGet package testing there is a separate solution at test\MUXControlsReleaseTest\MUXControlsReleaseTest.sln, which contains MUXControls.ReleaseTest, NugetPackageTestApp (C#) and NugetPackageTestAppCX (C++).
Test classes for this are in MUXControls.ReleaseTest, and they share test infrastructure with MUX so you can write tests in the same way as in MUX. The only difference is you’ll have to specify the TestType in ClassInitialize and TestCleanup (TestType.Nuget for NugetPackageTestApp and TestType.NugetCX for NugetPackageTestAppCX).
public static void ClassInitialize(TestContext testContext)
{
TestEnvironment.Initialize(testContext, TestType.Nuget);
}
public void TestCleanup()
{
TestEnvironment.AssemblyCleanup(TestType.Nuget);
}
The test apps are using released versions of MUX NuGet package locally. In CI, the test pipeline will generate a NuGet package for each build, and there’s a separate pipeline configured to consume the generated package from latest build and run MUXControl.ReleaseTest.
One of the core values of WinUI is the way that it brings controls to a wide variety of versions of Windows, handling version compatibility differences so that developers using WinUI don't have to. As such, testing WinUI changes on different versions is sometimes necessary. To accomplish this you will need to at times set up older versions of Windows for testing. To get these earlier versions you can make use of a Visual Studio subscription as described here.
You can run the test suite from within Visual Studio by using the Test top level menu. For targeting indivual tests you can use Test Explorer (found under the Test->Windows sub menu).
This same suite of tests will be run as part of your Pull Request validation check.
For your test to be discovered it needs to be a method tagged as [TestMethod] on a class tagged with as [TestClass]. With that metadata in place your new test method will be picked up by Test Explorer.
There are two types of tests you can use to validate your scenarios:
- API Tests: Run in the context of an app and validate the behaviors of our APIs.
- Interaction Tests: Drive the UI on an external app and validate the results using UI Automation.
Keep in mind that your test will be executed on many different versions of Windows, not just the most recent version. Your tests may need version or IsApiPresent checks in order to pass on all versions.
Visual tree dumps are stored here and we use them as the baseline (master) for visual tree verifications. If you make UI changes, visual tree verification tests may fail since the new dump no longer matches with masters. The master files need to be updated to include your latest changes. Visual verification test automatically captures the new visual tree and uploads the dump to test pipeline artifacts. Here are the steps to replace existing masters with the new ones.
-
Find your test run.
-
Download new masters.
-
Diff & replace
Diff the old and new masters, make sure the changes are intended, replace the files and commit your changes.
-
Write new test
Write a new test using VisualTreeTestHelper. Quick example here.
-
Run the test locally
Run the test locally and make sure everything looks right. The test will fail, which is expected since the test is new and there's no master to compare against. A new master file should be generated in your Pictures folder (The test app doesn't have write access to other arbitrary folders ☹).
-
Queue a test run in pipeline
Local test run only gives you the visual tree dump for your host OS version. Some controls have different visual behaviors on different versions. To get master files for all supported OS versions, you'll need to start a test run in test pipeline.
Go to the build page and select
WinUI-Public-MUX-PRpipeline. Click theQueuebutton on top right corner, updateBranch/tagTextBlock to be your working branch then click onRun.Outside contributors may not have permission to do this, just open a PR and one of our team members will queue a test run for you.
-
Get the new master files.
The new masters will be uploaded to pipeline artifacts folder when test finishes. Continue the steps in
Update visual tree masterssection above to download and commit the new files.
This project collects usage data and sends it to Microsoft to help improve our products and services. Note however that no data collection is performed when using your private builds.