Merge pull request #180 from MADE-Apps/feature/docs

📝 Overhaul of Legerity documentation

docs/articles/archive/features/android.md

@@ -0,0 +1,23 @@
+---
+uid: android-element-wrappers
+title: Using the Android element wrappers
+---
+
+# Using the Android element wrappers
+
+The goal of the platform element wrappers is to provide an easy set of elements that surface up properties and actions of the actual controls within the UI to make it easier for you to write tests that interact with them.
+
+These Android element wrappers are designed to be used with applications built for the Android platform using out-of-the-box SDK control.
+
+## Available element wrappers
+
+- [Button](xref:Legerity.Android.Elements.Core.Button)
+- [CheckBox](xref:Legerity.Android.Elements.Core.CheckBox)
+- [DatePicker](xref:Legerity.Android.Elements.Core.DatePicker)
+- [EditText](xref:Legerity.Android.Elements.Core.EditText)
+- [RadioButton](xref:Legerity.Android.Elements.Core.RadioButton)
+- [Spinner](xref:Legerity.Android.Elements.Core.Spinner)
+- [Switch](xref:Legerity.Android.Elements.Core.Switch)
+- [TextView](xref:Legerity.Android.Elements.Core.TextView)
+- [ToggleButton](xref:Legerity.Android.Elements.Core.ToggleButton)
+- [View](xref:Legerity.Android.Elements.Core.View)

docs/articles/features/made-windows.md → docs/articles/archive/features/made-windows.md

@@ -11,5 +11,5 @@ These Windows element wrappers are designed to be used with applications built w
 
 ## Available element wrappers
 
-- [DropDownList](https://github.com/MADE-Apps/legerity/blob/main/src/Legerity.MADE/DropDownList.cs)
-- [InputValidator](https://github.com/MADE-Apps/legerity/blob/main/src/Legerity.MADE/InputValidator.cs)
+- [DropDownList](xref:Legerity.Windows.Elements.MADE.DropDownList)
+- [InputValidator](xref:Legerity.Windows.Elements.MADE.InputValidator)

docs/articles/features/telerik-for-uwp.md → docs/articles/archive/features/telerik-for-uwp.md

@@ -11,7 +11,7 @@ These Windows element wrappers are designed to be used with applications built w
 
 ## Available element wrappers
 
-- [RadAutoCompleteBox](https://github.com/MADE-Apps/legerity/blob/main/src/Legerity.Telerik.Uwp/RadAutoCompleteBox.cs)
-- [RadBulletGraph](https://github.com/MADE-Apps/legerity/blob/main/src/Legerity.Telerik.Uwp/RadBulletGraph.cs)
-- [RadBusyIndicator](https://github.com/MADE-Apps/legerity/blob/main/src/Legerity.Telerik.Uwp/RadBusyIndicator.cs)
-- [RadNumericBox](https://github.com/MADE-Apps/legerity/blob/main/src/Legerity.Telerik.Uwp/RadNumericBox.cs)
+- [RadAutoCompleteBox](xref:Legerity.Windows.Elements.Telerik.RadAutoCompleteBox)
+- [RadBulletGraph](xref:Legerity.Windows.Elements.Telerik.RadBulletGraph)
+- [RadBusyIndicator](xref:Legerity.Windows.Elements.Telerik.RadBusyIndicator)
+- [RadNumericBox](xref:Legerity.Windows.Elements.Telerik.RadNumericBox)

docs/articles/getting-started.md

@@ -0,0 +1,36 @@
+---
+uid: getting-started
+title: Getting Started
+---
+
+# Getting started
+
+Getting started with Legerity is quick and easy! Legerity is distributed via NuGet.org, allowing you to install via a package manager.
+
+## Supported platforms
+
+Legerity packages target [.NET Standard 2.0](https://learn.microsoft.com/en-us/dotnet/standard/net-standard?tabs=net-standard-2-0#select-net-standard-version). This means that you can create UI tests with [.NET](https://learn.microsoft.com/en-us/dotnet/fundamentals/implementations#net-5-and-later-versions), .NET Core, [.NET Framework](https://learn.microsoft.com/en-us/dotnet/fundamentals/implementations#net-framework), and [Mono](https://learn.microsoft.com/en-us/dotnet/fundamentals/implementations#mono)!
+
+## Installing
+
+Releases of Legerity are published to [NuGet.org](https://www.nuget.org/packages?q=legerity) and can be installed via your preferred package manager.
+
+To quickly get started with a specific platform, select one of the following quick starts:
+
+- **[Windows](xref:quick_starts_windows)**: Create UI tests for Windows apps using [WinAppDriver](https://github.com/microsoft/WinAppDriver)
+- **[Android](xref:quick_starts_android)**: Take advantage of the [Appium](https://appium.io/) ecosystem to create UI tests for Android apps
+- **[iOS](xref:quick_starts_ios)**: Build UI tests for iOS apps with the power of [Appium](https://appium.io/)
+- **[Web](xref:quick_starts_web)**: Use your favourite browser to create UI tests for web apps using web drivers
+- **[Cross-platform](xref:quick_starts_cross_platform)**: Create easy-to-maintain UI tests across multiple platforms with a single test
+
+## Note on terminology
+
+Throughout the documentation, you may see terms that are specific to Legerity.
+
+A _page_ or _[page object](xref:using_legerity_page_objects)_ is a class that represents a single page in your app. This is typically a class that inherits from `BasePage` in Legerity and is used to interact with the UI elements on that page.
+
+An _[element wrapper](xref:using_legerity_element_wrappers)_ is a class that represents a single UI element, e.g. an input control. It is a wrapper around the `IWebElement` interface from Selenium, allowing Legerity to provide bespoke interaction methods for the represented UI element. This is typically a class that implements the `IElementWrapper` interface in Legerity and is used to interact with the UI element.
+
+## Let's get started
+
+If you're not sure which platform to start with, we recommend starting with the [Web](xref:quick_starts_web) quick start. This will give you a great overview of Legerity, how to create UI tests, and how to run them.

docs/articles/getting-started/quick-starts.md

@@ -0,0 +1,17 @@
+---
+uid: getting_started_quick_starts
+title: Quick Starts
+---
+
+# Quick starts
+
+These quick starts provide very minimal examples for getting your first test running on specific platforms to help you get started with using Legerity.
+
+> [!NOTE]
+> If you'd like to dive into the details, explore our articles on [using Legerity](xref:using_legerity).
+
+- [Windows](xref:quick_starts_windows)
+- [Android](xref:quick_starts_android)
+- [iOS](xref:quick_starts_ios)
+- [Web](xref:quick_starts_web)
+- [Cross-platform](xref:quick_starts_cross_platform)

docs/articles/getting-started/quick-starts/android.md

@@ -0,0 +1,71 @@
+---
+uid: quick_starts_android
+title: Android Quick Start
+---
+
+# Android
+
+> This quick start will get you up and running with writing UI tests for an Android application using [Appium](https://appium.io/) and Legerity.
+
+## Prerequisites
+
+This quick start requires the following:
+
+- An understanding of Selenium and working with the [WebDriver](https://www.selenium.dev/documentation/webdriver/) APIs in .NET
+- An understanding of Appium and [working with the capabilities for Android](https://appium.io/docs/en/drivers/android-uiautomator2/)
+- A functioning installation of the [.NET runtime and SDK](https://dotnet.microsoft.com/en-us/download)
+
+## Install Legerity templates
+
+Legerity includes project templates to simplify the creation of new UI test projects. To install the templates, run the following command:
+
+```powershell
+dotnet new -i Legerity.Templates
+```
+
+When creating a project, the template will automatically add to an existing solution file if it can locate one, otherwise you will have to add it manually.
+
+## Create a new Android UI test project with NUnit
+
+To create a new Android UI test project with NUnit in your existing repository, created a new project folder and from within it, run the following command:
+
+```powershell
+dotnet new legerity-android
+```
+
+This will create a new Android UI test project with the following structure:
+
+```text
+MyProject
+├── Elements
+├── Pages
+│   └── SamplePage.cs
+├── Tests
+│   └── SampleTests.cs
+├── BaseTestClass.cs
+├── GlobalUsing.cs
+├── MyProject.csproj
+```
+
+The project will include dependencies for NUnit, Appium, and Legerity for Android.
+
+The `BaseTestClass` class is a simple abstraction used for all of your test classes, based on the Legerity `LegerityTestClass`. The [base test class](xref:using_legerity_test_classes#the-base-test-class) is a great way to centralize common logic for your tests, to abstract the boilerplate code away from your tests, such as managing the application drivers.
+
+> [!NOTE]
+> The `BaseTestClass` in this template shows how to configure the application to launch and the activity you want to launch to. This should be updated to launch your own application via the `AndroidApplication` and `AndroidApplicationActivity` constants.
+
+The `SamplePage` and `SampleTests` classes are used to show the basic structure of a [page object](xref:using_legerity_page_objects) and [test class](xref:using_legerity_test_classes). In this template, they highlight finding a button by ID and verifying it is shown.
+
+> [!NOTE]
+> The `SamplePage` and `SampleTests` classes are intended to be used as a guide for structuring tests. These should be removed and replaced with your own tests and page objects.
+
+## Dive into more
+
+Now that you have your test project up, you can dive deeper into:
+
+- [Using the base test class](xref:using_legerity_base_test_class)
+- [Creating page objects](xref:using_legerity_page_objects)
+- [Creating test classes](xref:using_legerity_test_classes)
+- [Locating elements with Legerity by locators](xref:using_legerity_by_locators)
+- [Using and creating element wrappers](xref:using_legerity_element_wrappers)
+- [Using custom conditions to wait for elements](xref:using_legerity_wait_conditions)

docs/articles/getting-started/quick-starts/cross-platform.md

@@ -0,0 +1,85 @@
+---
+uid: quick_starts_cross_platform
+title: Cross Platform Quick Start
+---
+
+# Cross Platform
+
+> This quick start will get you up and running with writing cross-platform UI tests for Android, iOS, Windows, and Web using Legerity. The approach is cross-platform framework agnostic, so whether you've built your app with Xamarin, Flutter, React Native, or any other cross-platform framework, you can use Legerity to write cross-platform UI tests for it.
+
+## Prerequisites
+
+This quick start requires the following:
+
+- An understanding of Selenium and working with the [WebDriver](https://www.selenium.dev/documentation/webdriver/) APIs in .NET
+- An understanding of [Appium](https://appium.io/)
+- A functioning installation of the [.NET runtime and SDK](https://dotnet.microsoft.com/en-us/download)
+- For iOS, a functioning installation of [Xcode](https://developer.apple.com/xcode/) on macOS with simulators installed
+- For Windows, a Windows 10 or Windows 11 device with the [WinAppDriver](https://github.com/microsoft/WinAppDriver) installed
+
+## Install Legerity templates
+
+Legerity includes project templates to simplify the creation of new UI test projects. To install the templates, run the following command:
+
+```powershell
+dotnet new -i Legerity.Templates
+```
+
+When creating a project, the template will automatically add to an existing solution file if it can locate one, otherwise you will have to add it manually.
+
+## Create a new cross-platform UI test project with NUnit
+
+To create a new cross-platform UI test project with NUnit in your existing repository, created a new project folder and from within it, run the following command:
+
+```powershell
+dotnet new legerity-xplat
+```
+
+This will create a new cross-platform UI test project with the following structure:
+
+```text
+MyProject
+├── Elements
+├── Pages
+│   └── SamplePage.cs
+├── Tests
+│   └── SampleTests.cs
+├── BaseTestClass.cs
+├── GlobalUsing.cs
+├── MyProject.csproj
+```
+
+The project will include dependencies for NUnit, Appium, and Legerity for Windows (including WinUI), Android, iOS, and Web.
+
+> [!NOTE]
+> The ChromeDriver is used to demonstrate the use of the Web driver. You can run your UI tests on as many browsers as you like by installing the relevant driver NuGet package into the project and providing additional `PlatformOptions` to your `BaseTestClass`.
+> Legerity supports Chrome, Firefox, Opera, Safari, Edge, and Internet Explorer.
+
+The `BaseTestClass` class is a simple abstraction used for all of your test classes, based on the Legerity `LegerityTestClass`. The [base test class](xref:using_legerity_test_classes#the-base-test-class) is a great way to centralize common logic for your tests, to abstract the boilerplate code away from your tests, such as managing the application drivers.
+
+The `PlatformOptions` property is used to configure all the various cross-platform drivers for the applications you want to test. You configure as many, or as few, platforms as you desire.
+
+> [!NOTE]
+> In this template, the `PlatformOptions` property is configured to launch cross-platform UI tests for Android, iOS, Windows, and Web.
+
+The `SamplePage` and `SampleTests` classes are used to show the basic structure of a [page object](xref:using_legerity_page_objects) and [test class](xref:using_legerity_test_classes).
+
+In this template, they highlight how to use the `App` property of the `BasePage` configured during instantiation to find a UI element specific to a platform.
+
+This approach works well for applications that have a similar user experience across each platform.
+
+This same approach can be used on the [element wrappers](xref:using_legerity_element_wrappers) to abstract the platform-specific logic away from your tests, ensuring an easier interface when using them in your page objects and tests.
+
+> [!NOTE]
+> The `SamplePage` and `SampleTests` classes are intended to be used as a guide for structuring tests. These should be removed and replaced with your own tests and page objects.
+
+## Dive into more
+
+Now that you have your test project up and running, you can dive deeper into:
+
+- [Using the base test class](xref:using_legerity_base_test_class)
+- [Creating page objects](xref:using_legerity_page_objects)
+- [Creating test classes](xref:using_legerity_test_classes)
+- [Locating elements with Legerity by locators](xref:using_legerity_by_locators)
+- [Using and creating element wrappers](xref:using_legerity_element_wrappers)
+- [Using custom conditions to wait for elements](xref:using_legerity_wait_conditions)

docs/articles/getting-started/quick-starts/ios.md

@@ -0,0 +1,75 @@
+---
+uid: quick_starts_ios
+title: iOS Quick Start
+---
+
+# iOS
+
+> This quick start will get you up and running with writing UI tests for an iOS application using [Appium](https://appium.io/) and Legerity.
+
+> [!NOTE]
+> It is recommended that a macOS device is used for this quick start.
+
+## Prerequisites
+
+This quick start requires the following:
+
+- An understanding of Selenium and working with the [WebDriver](https://www.selenium.dev/documentation/webdriver/) APIs in .NET
+- An understanding of Appium and [working with the capabilities for iOS](https://appium.io/docs/en/drivers/ios-xcuitest/index.html)
+- A functioning installation of the [.NET runtime and SDK](https://dotnet.microsoft.com/en-us/download)
+- A functioning installation of [Xcode](https://developer.apple.com/xcode/) on macOS with simulators installed
+
+## Install Legerity templates
+
+Legerity includes project templates to simplify the creation of new UI test projects. To install the templates, run the following command:
+
+```powershell
+dotnet new -i Legerity.Templates
+```
+
+When creating a project, the template will automatically add to an existing solution file if it can locate one, otherwise you will have to add it manually.
+
+## Create a new iOS UI test project with NUnit
+
+To create a new iOS UI test project with NUnit in your existing repository, created a new project folder and from within it, run the following command:
+
+```powershell
+dotnet new legerity-ios
+```
+
+This will create a new iOS UI test project with the following structure:
+
+```text
+MyProject
+├── Elements
+├── Pages
+│   └── SamplePage.cs
+├── Tests
+│   └── SampleTests.cs
+├── BaseTestClass.cs
+├── GlobalUsing.cs
+├── MyProject.csproj
+```
+
+The project will include dependencies for NUnit, Appium, and Legerity for iOS.
+
+The `BaseTestClass` class is a simple abstraction used for all of your test classes, based on the Legerity `LegerityTestClass`. The [base test class](xref:using_legerity_test_classes#the-base-test-class) is a great way to centralize common logic for your tests, to abstract the boilerplate code away from your tests, such as managing the application drivers.
+
+> [!NOTE]
+> The `BaseTestClass` in this template shows how to configure the application to launch on an iPhone SE (3rd generation) Simulator. This should be updated to launch your own application via the `IOSApplication` constant and the device configuration in the `PlatformOptions`.
+
+The `SamplePage` and `SampleTests` classes are used to show the basic structure of a [page object](xref:using_legerity_page_objects) and [test class](xref:using_legerity_test_classes). In this template, they highlight finding a button by name and verifying it is shown.
+
+> [!NOTE]
+> The `SamplePage` and `SampleTests` classes are intended to be used as a guide for structuring tests. These should be removed and replaced with your own tests and page objects.
+
+## Dive into more
+
+Now that you have your test project up, you can dive deeper into:
+
+- [Using the base test class](xref:using_legerity_base_test_class)
+- [Creating page objects](xref:using_legerity_page_objects)
+- [Creating test classes](xref:using_legerity_test_classes)
+- [Locating elements with Legerity by locators](xref:using_legerity_by_locators)
+- [Using and creating element wrappers](xref:using_legerity_element_wrappers)
+- [Using custom conditions to wait for elements](xref:using_legerity_wait_conditions)