pixel-designer-*.zip - is a wpf based application and provides the design environment where you create your test cases. Pixel designer is intended to be used only on windows OS.
pixel-runner-*.zip - is a .net core cli based application that you will use to execute your test cases on dedicated machines. Binaries for both windows and linux OS are available.
pixel-persistence-*.zip - is an asp.net core based service to store the project data and test execution results. It also provides a blazor basesd UI to view various reports from test execution. Binaries for both windows and linux OS are available.

Additionally, you will also need mongodb which is required by pixel-persistence service to store all it’s data.

you must unblock the zip files by right click -> properties -> check unblock -> apply before extracting the files.

1.1 - pixel-deigner

Installation and configuration of pixel-designer

pixel-designer is a wpf based application built on top of .net core framework. It provides the design environment for creating automation test cases. It is intended to be used on windows OS. However, it should be possible to execute the test cases designed in pixel-designer on a linux machine as well given pixel-runner can execute on both windows and linux OS. If you plan to run your test cases on linux using pixel-runner, the plugins used in a test case must be supported on linux OS.

Extract the files to any location after unblocking the zip files.
Launch pixel-design.exe and application will be started in offline mode.
Admin rights are not required to execute the application.
pixel-designer can work in online or offline mode. Offline mode is a quick way to try out the software before going through all the required setup.

Settings

Settings window can be opened by clicking the wheel icon on top right. There are three sections :

General
- Persistence Service : Url of the persistence service if you want to run application in online mode.
- Work Offline : Indicates if application should work in online or offline mode.
Fixture
- Delay Before : Amount of delay in milli seconds before executing each step of the automation workflow.
- Delay After : Amount of delay in milli seconds after executing each step of the automation workflow.
- Delay Factor : Delay Before and Delay After are scaled using Delay Factor before using those values. Delay Factor can be overridden by individual fixture and test cases.
Theme
- Theme : Theme of the application. It can be light or dark.
- Accent : Accent applied to the application. Multiple color options are available for accent.

1.2 - pixel-persistence

Installation and configuration of pixel-persistence

pixel-persistence is an asp.net core based web service used by pixel-designer and pixel-runner to store and retrieve data. It also comes up with a blazor based UI for showing various reports for test execution results. pixel-persistence requires mongodb to store automation process and test execution data.

see docker-compose-. files in project repository if you are intrested in hosting on docker. An official docker image is planned for upcoming release.

Make sure that an instance of mongodb is up and running
Extract the files to any location after unblocking the zip file.
Ensure that DOTNET_ENVIRONMENT OR ASPNETCORE_ENVIRONMENT variable is set to production. See ENVIRONMENTS in asp.net
Edit the appsettings.json file to set the MongoDbSettings->ConnectionString. Example connectionString “mongodb://localhost:27017”. This will vary based on your mongodb configuration.
Launch pixel-persistence.exe
Navigate to dashboard - https://localhost:5001/persistence and swagger ui - https://localhost:5001/swagger/index.html) to verify service is up and running. Base Url can be different depending on your setup.

While the pixel-persistence service can be exposed directly (with Kestrel), it is recommended to use it behind a reverse proxy with SSL termination. See guidance on when to use Kestrel with a reverse proxy. You will need to provide HTTPS certificate in either case. Checkout mkcert if you are working locally to generate self-signed certificates.

pixel-persistence doesn’t support authentication and authorization out of the box. You would ideally want to host it behind a reverse proxy like yarp and authenticate and authorize requests before they are proxied. Please see Authentication and Authorization with yarp. You can use any reverse proxy of your choice.

1.3 - pixel-runner

Installation and configuration of pixel-runner

pixel-runner is a .net core cli based application that can be used to execute test cases designed in pixel-designer. It is suitable for use on your machines dedicated for execution of test cases. while pixel-runner can run both on windows and linux OS, you need to ensure plugin compatibility with OS while designing your test cases using pixel-designer on windows.

Extract the files to any location after unblocking the zip files.
Edit the appsettings.json and set “persistenceServiceUri” to the url of persistence-service.
Launch command prompt and change working directory to the folder contaning pixel-run.exe
Run pixel-run –help from the command prompt to see help menu.

Admin rights are not required to execute the application

2 - Getting Started

Step by step tutorial to create your first test automtion.

What will be covered ?

Add a new application and configure it in pixel-designer
Capture the controls for application that needs to be automated in pixel-designer
Create a new automation project in pixel-designer
Configure how application will be launched and closed as part of environment setup and tear down in pixel-designer
Add new test fixtures and test cases in pixel-designer
Execute test cases in pixel-designer
Publish the project version from pixel-designer
*Create a template in pixel-runner
*Execute test case in pixel-runner using template
*See details of test case execution on web portal
To follow along with steps marked with *, pixel-designer should be running in online mode

Prerequisites

You should have a working setup as described in Installation section. If you want to quickly try out pixel-designer only, you don’t need to setup pixel-persistence service and can use pixel-designer in offline mode.

2.1 - Add new application

Add and configure new application for which we need to create automation test cases in pixel-designer

In this tutorial, we will add and configure “calculator” application that come with the windows. Launch the pixel-designer and let’s get started.

Click the Add (+) button in the “Applications Repository” pane at the bottom.
Click “Windows App” from the popup menu.
An application icon appears with name “1”.
Select this application icon, right click -> rename. Rename apaplication to “Calculator” and press enter. The new name should start showing up now as shown below.
Select this application icon again, right click - > Edit.
Application details are in edit mode in property grid pane on right side.
Set the value of “ExecutablePath” to “calc” and click on save icon on top right of property grid pane.

Some tutorials toward the end require that pixel-persistence service is up and running and pixel-designer is running in online mode. You can continue in offline mode for the most part if you want to quickly get a feel of pixel-designer without investing time in all necessary setup.

2.2 - Capture controls

Capture and configure controls to automate for the calculator application in pixel-designer

In this tutorial, we will capture and configure the controls belonging to calculator application that need to be automated in pixel-designer

Double click the “Calculator” application icon to activate “Control Explorer” inside the Application repoitory.
Launch calculator application by hitting win+r and then type calc followed by enter.
In pixel-designer, click Screen Scrappers -> UIA Scrapper from top level menu. At this point, if you hover over any control on applications that support UIA, they will get highlighted with an orange rectangle as shown below.
Hold left ctrl and click any of the buttons on calculator to capture it. If successfully capture, highlight rectangle will turn green.
Let’s capture button 0, 1, 2, 3, add, subtract, multiply, divide, equals, clear and result.
Once all controls are captured, you can go back to Screen scrappers -> UIA Scrapper and click it again to exit capture mode.
All the captured controls will appear in control explorer view now. You can now rename these controls by selecting them and right click -> rename or you can inspect and modify captured details by right click -> Configure.
Control explorer should look as shown below at this point assuming you have also renamed the controls.

2.3 - Create new project

Create a new automation project for holding test cases for calculator

In this tutorial, we will create a new automation project. Automation project can contain test fixtures and test cases for our application.

Click on the Add (+) icon left of “Projects” on the Home tab.
This will open the dialog to create new automation project.
Set the name as “Calculator Demo” and click “Create”.
The project will be created and opened now in designer in a new tab.

2.4 - Setup and Teardown

Having created a new automation project, We will configure how the application to be tested is launched and closed.

In this tutorial, we will configure the automation process so that we can launch Calculator application as part of environment setup and close Calculator application as part of environment teardown.

At this point, “Calculator Demo” should be the active tab in pixel-designer.
Double click on the “Automation Process” component to expand it. Your designer should look shown below :
Navigate to application view by clicking the back button from control explorer view and drag drop the Calculator application on “Application Pool” component. This will add a “Calculator” application component and a “UIA Control Locator” child component of the “Calcultor” component. Select the “UIA Control Locator” component and change “MatchProcessId” property to false.
There are two window associated with Calculator. The child window has a different process Id.Hence, we need to configure to not match ProcessId while looking for controls.
Drag drop the application on “Environment Setup” and “Environment Teardown” components. However, this time a “Sequence : Calculator” component is added.
When you drag drop an application on any of the component except “Application Pool”, a new component with name “Sequence:ApplicationName” is created. Application sequence components create a scope for the application. All components inside an application scope act on the target application e.g. launch component will launch application identified by the current application scope.
Tip : If you are in control explorer view for a given application, you can also drag drop the empty rectangle icon from top left.
Open the script editor for project initialization script by clicking Project -> Edit Script from top level menu. Declare a variable calculatorWindow of type ApplicationWindow as shown and save the script. Also, add required namespace for type ApplicationWindow.
pixel-designer comes integrated with a C# code editor with rich features like intellisense and code highlighting e.g. if you hover over ApplicationWindow , you will see a yellow light bulb. You can click it and see available options that can help you to automatically add missing namespace without typing it manually.
Add below four components to “Environemtn Setup -> Sequence : Calculator” component from the Components pane on left. You can search for component name to filter.
- Launch : This is required to launch the application. No configuration required.
- Delay : This is required to add a delay between execution of next step. Select this component and set the value of “Delay Amount” to 3 in property grid.
- Find Desktop Window : This is used to find an ApplicationWindow using different criteria e.g. title of window to find. Select this component after adding and set “Match Criteria” to “Equals”, “Window Title” to “Calculator” and “TargetWindow” to “calculatorWindow” variable from dropdown that we declared earlier in property grid.
- Attach : This is required to attach to an existing application. Select this component and set the value of “Attach mode” to “Attach to Window” and value of “Attach To” to “calculatorWindow” variable from dropdown
Normally Launch will be the only component required in case of other applications like notepad. However, calc.exe spawns few other processes. Hence, we need to find the Calculator window and attach to it manually. Although, this makes tutorial a bit complicated, it also gives an idea on the flexibility offered by pixel-deigner to handle custom scenarios and a glimpse of scripting capabilities it has to offer.
Add Close component to “Environemtn Teardown -> Sequence : Calculator”. Close component will exit the Calculator application that we attached to earlier during environment setup.
Your screen should look as shown below at this step.
Save the process from File -> Save.
Ensure that Calculator application is not already running.
Activate the “Test Explorer” pane on left and click on the Setup icon button.
Calculator application should be launched now.
Teardown icon button on “Test Explorer” toolbar should be enabled now. Click on it to close the application.

2.5 - Add fixtures

Add few fixtures to the automation process

In this tutorial, we will add few fixtures to the automation process.

Activate the “Test Explorer” pane.
Click on “Add new fixture” icon button on the toolbar
This will open the new popup dialog to add new test fixture.
Leave the default values and click on save button to create fixture.
Repeat the process twice to create two more fixture with default value.
At this step, you should have three fixtures and your screen should look as shown below.

2.6 - Add test cases

Add few test cases to the automation process

In this tutorial, we will add a test case to each fixture we created earlier.

Creating new test cases

Activate the “Test Explorer” pane.
Right click “Fixture#1” and select “Add Test”.
This will open popup window to add a new test case.
Change the name to “Add Numbers” and click save.
Similarly, add a new test case named “Multiply Numbers” to Fixture#2 and “Simulate Error” to Fixture#3.
Activate the “Test Data Repository” pane at the bottom and drag drop “EmptyDataSource” on each test case.
Test cases require that a data source should be assigned to them before they become active and can be worked with. Your test case will execute once for each data record returned by the data source. Test data source can be coded or mapped to csv files. EmptyDataSource returns only one data record and can be used with any test case that doesn’t depend on any data. It is created by default for each new automation project. It is also posssible to override the data source at runtime using prefixes to run your test cases with different sets of data dynamically.
After above steps, your screen should look as shown below.

Configure steps for test case “Fixture#1 -> Add Numbers”

Right click test case “Add Numbers” and click open.
Test case “Add Numbers” should be open on designer canvas now.
Drag drop the calculator application from application explorer on to “Add Numbers” component.
Drag drop controls 1, add, 2 and equals from Control explorer to the “Sequence : Calculator” component added in previous step.
After above steps, your screen should look as shown below.
Drag drop component “UIA -> Invoke” from component pane to controls 1, 2, add and equals.
Right click “Add Numbers” test case in test explorer and click “Save” or click save all icon on test explorer toolbar.
Ensure Calculator application is not alredy running.
Setup environment from the test explorer.
Select the test case “Add Numbers” and then click “Run Selected” button from the test explorer toolbar to execute the test case.
Tear down environment to close the calculator application.

Configure steps for test case “Fixture#2 -> Multiply Numbers”

Right click test case “Multiply Numbers” and click open.
Test case “Multiply Numbers” should be open on designer canvas now.
Drag drop the calculator application from application explorer on to “Setup” component
Drag drop control clear from control explorer to the to the “Sequence : Calculator” component added in previous step and add “UIA -> Invoke” component to clear control component. This is required to clear the results from previous test case before executing the test case.
Drag drop the calculator application from application explorer on to “Multiply Numbers” component
Drag drop controls 1, multiply, 2 and equals from Control explorer to the “Sequence : Calculator” component added in previous step .
Instead of “UIA -> Invoke” component which automates the control using API, we will simulate mouse click using “Input Device -> Mouse -> Click” component. Add “Input Device -> Mouse -> Click” component to all the controls.
Simulation using mouse and keyboard requiress application to have focus. We can ensure that by setting “Requires Focus” property to true on the application sequence component added to test case.
Right click “Multiply Numbers” test case in test explorer and click “Save” or click save all icon on test explorer toolbar.
After above steps, your screen should look as shown below.
Ensure Calculator application is not alredy running.
Setup environment from the test explorer.
Select the test case “Multiply Numbers” and then click “Run Selected” button from the test explorer toolbar to execute the test case.
Tear down environment to close the calculator application.

Configure steps for test case “Fixture#3 -> Simulate error”

Right click test case “Simulate error” and click open.
Drag drop the calculator application from application explorer on to “Simulate Error” component.
Add “Scripting -> Script [Inline]” component to the application sequence.
Set the content as shown below
Right click “Simulate error” test case in test explorer and click “Save” or click save all icon on test explorer toolbar.
Ensure Calculator application is not alredy running.
Setup environment from the test explorer.
Select the test case “Simulate error” and then click “Run Selected” button from the test explorer toolbar to execute the test case.
Execution of test case will fail.
Tear down environment to close the calculator application.

Run all the test cases simultaneously

Ensure Calculator application is not alredy running.
Setup environment from the test explorer.
Click “Run All” from the test explorer.
Tear down environment once all test cases are executed.

2.7 - Publish project

Publish a given version of project.

In this tutorial, we will look at how can we publish a specific version of project.

Let’s assume you have a software with current version 8.x in production and next upcoming version is 9.x. As the development team is working on 9.x feature, QA team will be adding automation test cases simultaneously. Eventually, 9.x version will be frozen and work will start on next version 10.x. The QA team maintaining the automation project in pixel-designer has active version 1.x ( for 9.x of software under test). The QA team can now publish version 1.x when they think they are done with all the automation test cases for version 9.x of software. Publishing 1.x will create a cloned version 2.x. 1.x can’t be opened anymore in pixel-designer. The QA team now starts working with version 2.x of automation project to add new automation test cases for changes coming in version 10.0 of software.

Close the automation project by clicking x on the “Calculator Demo” tab.
Home tab should be active now.
Hover over the project name to show hidden icons and click on the settings button next to the project name to open the version manager screen.
Click publish next to version 1.0.0.0 to publish this version and create a new incremented version 2.0.0.0. Version 2.0.0.0 will start as an exact clone of 1.0.0.0.
You can close the version manager screen now and can open the new version 2.0.0.0 to edit.

2.8 - Execute test cases

Create templates in pixel-runner and use them to execute your test cases.

This tutorial requires that all the previous steps in pixel-designer were done in online mode.

In this tutorial, we will create templates in pixel-runner and use these templates to execute test cases in pixel-runner. Templates capture the details of which test cases should be executed for a given version of automation project.

Creating templates in pixel-runner

Launch command prompt and change directory to where pixel-run.exe is located. See setup guide for pixel-runner if required.
Run pixel-run template --help to see help for templates
Run pixel-run template new to create a new template and follow instructions to provide required value. This template will execute all test cases
Repeat step 3 to create another template as shown below. This template will execute only test cases belonging to Fixture#1 for project “Calculator Demo”

Test selectors are C# scripts which can be used to filter if a test case belonging to a given fixture can be executed.

Executing test cases in pixel-runner using templates

Run pixel-run run template calculator-all 1.0.0.0 to run template calculator-all for version 1.0.0.0 of automation project.
Run pixel-run run template calculator-f1 2.0.0.0 to run template calculator-f1 for version 2.0.0.0 of automation project.

2.9 - View Test Results

View test results on the dashboard.

In this tutorial, we will see how to view the reports for test case execution on the web dashboard.

Navigate to (https://localhost:5001/persistence)[https://localhost:5001/persistence] on your browser of choice.
Depending on your deployment of pixel-persistence service, base url can be different.
Click on sessions tab to see all the sessions you have executed from pixel-runner
Click “Show Details” on any session to see the details for that session.
Click “View Stats” for any of the test case to see details for that test case.

3 - Contribution Guidelines

How to contribute to the docs

These basic sample guidelines assume that your Docsy site is deployed using Netlify and your files are stored in GitHub. You can use the guidelines “as is” or adapt them with your own instructions: for example, other deployment options, information about your doc project’s file structure, project-specific review guidelines, versioning guidelines, or any other information your users might find useful when updating your site. Kubeflow has a great example.

Don’t forget to link to your own doc repo rather than our example site! Also make sure users can find these guidelines from your doc repo README: either add them there and link to them from this page, add them here and link to them from the README, or include them in both locations.

We use Hugo to format and generate our website, the Docsy theme for styling and site structure, and Netlify to manage the deployment of the site. Hugo is an open-source static site generator that provides us with templates, content organisation in a standard directory structure, and a website generation engine. You write the pages in Markdown (or HTML if you want), and Hugo wraps them up into a website.

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Quick start with Netlify

Here’s a quick guide to updating the docs. It assumes you’re familiar with the GitHub workflow and you’re happy to use the automated preview of your doc updates:

Fork the Goldydocs repo on GitHub.
Make your changes and send a pull request (PR).
If you’re not yet ready for a review, add “WIP” to the PR name to indicate it’s a work in progress. (Don’t add the Hugo property “draft = true” to the page front matter, because that prevents the auto-deployment of the content preview described in the next point.)
Wait for the automated PR workflow to do some checks. When it’s ready, you should see a comment like this: deploy/netlify — Deploy preview ready!
Click Details to the right of “Deploy preview ready” to see a preview of your updates.
Continue updating your doc and pushing your changes until you’re happy with the content.
When you’re ready for a review, add a comment to the PR, and remove any “WIP” markers.

Updating a single page

If you’ve just spotted something you’d like to change while using the docs, Docsy has a shortcut for you:

Click Edit this page in the top right hand corner of the page.
If you don’t already have an up to date fork of the project repo, you are prompted to get one - click Fork this repository and propose changes or Update your Fork to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.
Follow the rest of the Quick start with Netlify process above to make, preview, and propose your changes.

Previewing your changes locally

If you want to run your own local Hugo server to preview your changes as you work:

Follow the instructions in Getting started to install Hugo and any other tools you need. You’ll need at least Hugo version 0.45 (we recommend using the most recent available version), and it must be the extended version, which supports SCSS.
Fork the Goldydocs repo repo into your own project, then create a local copy using git clone. Don’t forget to use --recurse-submodules or you won’t pull down some of the code you need to generate a working site.
```
git clone --recurse-submodules --depth 1 https://github.com/google/docsy-example.git
```
Run hugo server in the site root directory. By default your site will be available at http://localhost:1313/. Now that you’re serving your site locally, Hugo will watch for changes to the content and automatically refresh your site.
Continue with the usual GitHub workflow to edit files, commit them, push the changes up to your fork, and create a pull request.

Creating an issue

If you’ve found a problem in the docs, but you’re not sure how to fix it yourself, please create an issue in the Goldydocs repo. You can also create an issue about a specific page by clicking the Create Issue button in the top right hand corner of the page.

Useful resources

Docsy user guide: All about Docsy, including how it manages navigation, look and feel, and multi-language support.
Hugo documentation: Comprehensive reference for Hugo.
Github Hello World!: A basic introduction to GitHub concepts and workflow.