Configuration Guide

How to Configure a Testware Automation SDK Project

Introduction

This document will describe how to configure a new Testware Automation SDK project within a Visual Studio solution. The custom application 'Rojabo' is used as an example throughout this guide and may easily be replaced with another custom application name.

Creating the Configuration

In the constructor of the RojaboSpider class apply following custom configuration. Create the following code regions - Environment, Settings, Behaviors - as a skeleton in the configuration class.

RojaboSpider.cs

public RojaboSpider()
{
    #region Environment
    #endregion

    #region Settings
    #endregion

    #region Behaviors
    #endregion
}

Setup the Environment Region

In the Environment region of the RojaboSpider class add the custom specific project settings. The properties Solution Path, Project Name, Application Path, Browser, Login and Password must be specified in this section. By using the SetupDefaultEnvironmentPaths() method all the environment paths will be defaulted equivalent to a standard Testware Automation SDK installation. The credentials for Login and Password are scrambled in this example - Ask for valid credentials.

RojaboSpider.cs

public RojaboSpider()
{
    #region Environment

    // Definition of Current Solution Path...
    string solutionPath = System.AppDomain.CurrentDomain.BaseDirectory.Replace("\\Rojabo.Web.Spider\\bin\\Debug\\", "");

    // Definition of General Project Properties...
    spiderConfiguration.ProjectName = "Rojabo";
    spiderConfiguration.ApplicationPath = "http://www.rojabo.com";
    spiderConfiguration.Browser = "*chrome";
    spiderConfiguration.Login = "john.doe@testware.dk";
    spiderConfiguration.Password = "123456";

    // Definition of Default Environment Paths...
    spiderConfiguration.SetupDefaultEnvironmentPaths(solutionPath);

    #endregion
}

Setup the Settings Region

The application Pane Controls represents the configuration of the website layout areas required for generating page objects. The Pane Controls configuration will be used both by the crawler and the enroller functionality. A page object may consist of several Pane Controls with different types and behavior. The configuration operates with four different types named as following...

• Menu
• Compound
• Content
• Ignored

The locators for the pane controls must be defined as an XPath and may be found manually by using the browser debugger. The picture below visualizes an example of a website with three application panes.

• The yellow and orange area represents a menu pane control - an area containing navigation links common for all web pages.
• The red area represents a content pane control - an area containing controls specific for each web page.

Add following customization for the Pane Controls Configuration in the Settings region.

RojaboSpider.cs

public RojaboSpider()
{
    #region Settings

    // Definition of Pane Controls... 
    spiderConfiguration.AddPaneControl(new SpiderConfigurationPaneControl() { Name = "TopMenuPage", Locator = "//ul[@id='topmenu']", Type = (int)SpiderPaneControlType.Menu });
    spiderConfiguration.AddPaneControl(new SpiderConfigurationPaneControl() { Name = "MainMenuPage", Locator = "//ul[@id='mainmenu']", Type = (int)SpiderPaneControlType.Menu });
    spiderConfiguration.AddPaneControl(new SpiderConfigurationPaneControl() { Name = "ContentPage", Locator = "//div[@id='content']", Type = (int)SpiderPaneControlType.Page });

    #endregion
}

Setup the Page Identifiers

The Page Identifier Locator settings specifies the properties that uniquely identifies the locators for a Page Object. The Page Identifiers are used both during crawling and enrollment. These settings may require a quick investigation of the website prior to configuration setup.

• IncludeIdentifierTitle - Enabling title-based locators in the DynamicPageIdentifier - Default value is false
• IncludeIdentifierLocator - Enabling URL based locators in the DynamicPageIdentifier - Default value is true
• IncludeIdentifierContext - Enabling Context based locators in the DynamicPageIdentifier - Default value is false

If the IncludeIdentifierContext option is used the IdentifierContextLocator descriptor must be specified.

public RojaboSpider()
{
    #region Settings

    // Definition of Page Identifiers...
    spiderConfiguration.IncludeIdentifierTitle = false;
    spiderConfiguration.IncludeIdentifierLocator = true;
    spiderConfiguration.IncludeIdentifierContext = true;
    spiderConfiguration.IdentifierContextLocator = ".//h1";

    #endregion
}

Setup the Crawler Controls

The crawler is controlled by one or several Crawler Controls specifying the navigation through the website. By using the default Crawler Control WebCrawlerLinkByHref the crawler will navigate through the website by URLs and is limited to operate within the current domain.

In a more advanced configuration setup, we may use additional Crawler Controls e.g. navigating by specific buttons in the website. During execution of the crawler any possible hazardous behavior like endless loops or unwanted logout is undesirable. The configuration may need to be enriched with additional configuration to provide a correct or better result. In this case we have found that the logout link makes it impossible for the crawler to procced into all web pages. We would therefore like to exclude the logout link in the configuration.

public RojaboSpider()
{
    #region Settings

    // Definition of Crawler Controls...
    spiderConfiguration.AddCrawlerControl(new SpiderConfigurationCrawlerControl() { Name = "WebCrawlerLinkByHref" });

    // Definition of Restricted Crawler Links...
    spiderConfiguration.AddRestrictedLink("http://members.rojabo.com/logout");

    #endregion
}

Setup the Web Controls

The application Web Controls represents descriptors for website controls required for generating page objects. The Web Controls configuration will be used by the enroller functionality only. A page object may consist of several Web Controls with different types and behavior. The configuration operates with predefined types with following names being standard...

• WebTextBox
• WebButton
• WebRadioButton
• WebCheckBox
• WebComboBox
• WebLink
• WebFileBox

In a more advanced configuration setup we may use additional Web Controls types for handling special custom controls in the website. The locators must be defined as one or more patterns of an XPath and may be found by using the browser debugger.

The required Web Control property Attribute will be defined as an optional serie of semicolon separated ids - The enroller will find the first unique id in the ordered list. The Attribute locator ids may be combined by use a comma separated list of ids. The picture below visualizes an example of a website with different Web Controls.

Add following customization to the Settings region. This Settings configuration below will be considered as a default setup but may be additional modified or adapted to this specific project may later.

RojaboSpider.cs

public RojaboSpider()
{
    #region Settings

    // Definition of Enroller Controls...
    spiderConfiguration.AddWebControl(new SpiderConfigurationWebControl() { Type = "WebTextBox", XPath = ".//input[not(@type)] | .//input[@type='text'] | .//input[@type='password'] | .//input[@type='textarea'] | .//textarea", Attribute = "id;name" });
    spiderConfiguration.AddWebControl(new SpiderConfigurationWebControl() { Type = "WebButton", XPath = ".//input[@type='button'] | .//input[@type='submit'] | .//input[@type='reset'] | .//button", Attribute = "id;name;value" });
    spiderConfiguration.AddWebControl(new SpiderConfigurationWebControl() { Type = "WebRadioButton", XPath = ".//input[@type='radio']", Attribute = "id;name,value" });
    spiderConfiguration.AddWebControl(new SpiderConfigurationWebControl() { Type = "WebCheckBox", XPath = ".//input[@type='checkbox']", Attribute = "id;name" });
    spiderConfiguration.AddWebControl(new SpiderConfigurationWebControl() { Type = "WebComboBox", XPath = ".//select", Attribute = "id;name" });
    spiderConfiguration.AddWebControl(new SpiderConfigurationWebControl() { Type = "WebLink", XPath = ".//a", Attribute = "linktext;href" });

    #endregion
}

Setup the Behaviours Region

In the Behaviors region of the RojaboSpider class add the custom behavior configuration. For a start we only enable the crawler and enroller functionality to fine tune the configuration. Later we will be working through the configuration enabling the remaining behaviors features step-by-step.

RojaboSpider.cs

public RojaboSpider()
{
    #region Behaviors

    // Definition of Spider Behavior...
    spiderConfiguration.EnablePreload = false;
    spiderConfiguration.EnableCrawler = true;
    spiderConfiguration.EnableEnroller = true;
    spiderConfiguration.EnableObjectRepositoryReport = true;
    spiderConfiguration.EnableCodeGenerator = false;
    spiderConfiguration.EnableTestGenerator = false;

    // Definition of Code Generators Behavior...
    spiderConfiguration.IncludeMenus = true;
    spiderConfiguration.IncludePages = true;
    spiderConfiguration.IncludeModels = true;
    spiderConfiguration.IncludeFactories = false;
    spiderConfiguration.IncludeLoginTests = false;
    spiderConfiguration.IncludeMenuTests = false;
    spiderConfiguration.IncludeContentTests = false;

    #endregion
}

Initializing the Crawler

For most web applications it will be required to define some of initializing steps for the Selenium WebDriver before the crawler can be executed successfully. Normally a login session needs to be handled - But additional there might also be steps before and after a handled login session.

Add following customization to the Initialize method in the RojaboSpider class.

RojaboSpider.cs

protected override void Initialize(IWebDriver driver)
{
    driver.FindElement(By.Id("email")).Clear();
    driver.FindElement(By.Id("email")).SendKeys(spiderConfiguration.Login);
    driver.FindElement(By.Id("password")).Clear();
    driver.FindElement(By.Id("password")).SendKeys(spiderConfiguration.Password);
    driver.FindElement(By.Name("commit")).Click();
}

Validating the Configuration

Finally review the RojaboSpider configuration and rebuild the solution. The Automation SDK project is now ready for execution.

Executing the Crawler

Run the application by executing the RojaboSpider console program. The Automation SDK will launch a browser, process the login session and crawl through the website according to the configuration. During execution web pages and the elapse time will be reported in the console window.

The Object Repository

During executing the RojaboSpider the application will enroll website page into an XML based Object Repository. The Object Repository may be considered as a database representing the website pages required for generating page objects and tests for later on in the process. Add the ObjectRepository.xml file to the solution and examine the generated output. Additional modification to the configuration may be provided for repeatable adjustment to the outcome.

The Object Repository Report

By enabling the Object Repository Report functionality, the application will produce a HTML based document with an overview of the enrolled web pages. This report will contain a simple analysis of the contents of the object repository and is aimed for assisting the operator in validating the crawler and enrollment configuration. May also be useful later when writing business test scripts or during test management.

The Webtable Controls

During our investigation of the website we have found that several WebTable objects has to be defined too. The WebTable objects are not standard HTML web elements and needs to be found manually by using the browser debugger. The picture below visualizes an example of a WebTable object inside the website.

RojaboSpider.cs

#region Settings

// Definition of Additional Web Controls...
spiderConfiguration.AddWebControl(new SpiderConfigurationWebControl() { Type = "WebTable", XPath = ".//table[@class and child::thead]", Attribute = "class" });

#endregion

The Enroller Customization

The generic enroller class contains many virtual methods that may be overridden if needed. In the RojaboEnroller class following code snippets may be added for extended behavior of the enrollment process.

RojaboEnroller.cs

public RojaboEnroller(WebObjectRepository _webObjectRepository, EnrollerConfiguration _configuration)
    : base(_webObjectRepository, _configuration)
{
    AddControlNameAlias("GoalName", "EventName");
    AddControlNameAlias("GoalDate1i", "EventYear");
    AddControlNameAlias("GoalDate2i", "EventMonth");
    AddControlNameAlias("GoalDate3i", "EventDay");
    AddControlNameAlias("GoalGoalType", "EventType");
}

RojaboEnroller.cs

public override string GetMenuMethodLocation(string url, string html, HtmlNode node, WebObjectRepositoryMenu repositoryMenu)
{
    string location = base.GetMenuMethodLocation(url, html, node, repositoryMenu);
    if (location != null)
        if (location.Contains("logout"))
            return null;

    return location;
}

RojaboEnroller.cs

public override string GetPageClass(string url, string html, HtmlNode node)
{
    url = GetUniformResourceLocator(url);
    url = EnrollerUtilities.RemoveFileNameExtension(url);

    if (url == "/member/tests")
    {
        url = url.Replace("/member", " ");
    }
    else
    {
        url = url.Replace("/member", " ");
        url = url.Replace("/tests", " ");
        url = url.Replace("/goals", " events ");
    }

    return EnrollerUtilities.CamelCase(url) + "Page";
}

After adaption in the Spider configuration - rebuild your spider solution and execute the Spider application once again.

Executing the Code Generators

After validating the object repository, we should have a solid foundation for code generation. Based on the existing object repository we will now enable both the Code Generator and the Test Generator following by execution of the automation SDK application. Afterwards all generated source code files must be included in projects. Its good practices to enable tests in small portions to be able to overview possible problems.

RojaboSpider.cs

#region Behaviors

    // Definition of Spider Behavior...
    spiderConfiguration.EnablePreload = true;
    spiderConfiguration.EnableCrawler = false;
    spiderConfiguration.EnableEnroller = false;
    spiderConfiguration.EnableObjectRepository = false;
    spiderConfiguration.EnableCodeGenerator = true;
    spiderConfiguration.EnableTestGenerator = true;

#endregion

Include all generated files in the projects

• Rojabo.Web.API * ./Models/.cs * ./Pages/.cs * ./*cs

• Rojabo.Web.API.Tests * ./Factories/.cs
  * ./LoginTests /.cs * ./MenuTests /.cs * ./ContentTests/.cs * ./FillFormTests/.cs * ./.cs

The Generated Login Page may be manually modified to be aligned to the Initialize method previous defined in the configuration.

LoginPage.cs

namespace Rojabo.Web.API
{
    public class LoginPage : BasePage
    {
        static Castle.Core.Logging.ILogger logger = Configuration.CoreAppXmlConfiguration.Instance.LoggerFactory.Create(typeof(LoginPage));
        private static readonly PageIdentifier DefaultIdentifier = new PageIdentifier(null, null, null);

        public LoginPage(IWebDriver driver)
            : base(driver, DefaultIdentifier) { }

        protected virtual WebTextBox txtEmail { get { return new WebTextBox(this.Driver, By.Name("email")); } }
        protected virtual WebTextBox txtPassword { get { return new WebTextBox(this.Driver, By.Name("password")); } }
        protected virtual WebButton btnSubmit { get { return new WebButton(this.Driver, By.Name("commit")); } }
        protected virtual WebCheckBox chkRememberMe { get { return new WebCheckBox(this.Driver, By.Name("remember_me")); } }

        public TrainingPlanPage Login(string userId, string password)
        {
            logger.InfoFormat("Login: {0}, {1}", "*****", "*****");

            this.txtEmail.Enter(userId);
            this.txtPassword.Enter(password);
            this.btnSubmit.Click();

            return new TrainingPlanPage(this.Driver);
        }
    }
}

Executing the Generated Tests

The Automation SDK application has now created a full API containing pages, methods and corresponding low-level tests. To validate the API simply execute all tests. Afterwards small adaptions to the tests and methods will be required - Failed and ignored test needs to be corrected.