Nutstone.Selenium.Core 1.0.102

Introduction

Hi. this package is written out of boredom with havng to run UI tests manually whilst developing .net core (5) full-stack applications.

It provides a fluent interface for writing selenium based unit TESTS, but could be used to create full functioning selenium applications.

it is not complete , but is basically functional (hence the readme)

David.

Installation

Install-Package Nutstone.Selenium.Core

install the selenium package of your choice.

This package ONLY (currently) supports ChromeDriver , but can be extended be implementing by implementing ISeleniumWebDriver.

note this package makes extensive use of the excellent Scrutor package so ALL supported interfaces will be loaded at startup , you do not have to register them yourself

for example:-

using Nutstone.Selenium.Core.Browser.Drivers;
using Nutstone.Selenium.Core.Configuration;
using OpenQA.Selenium;
using OpenQA.Selenium.Edge;
using System.IO;

namespace test_nutstone_selenium.Drivers
{
    public class SeleniumEdgeDriver : ISeleniumWebDriver
    {
        public string BrowserType => DriverConstants.Edge;
        public IWebDriver GetDriver(DriverConfiguration driverConfiguration)
        {
            var edgeOptions = new EdgeOptions
            {
                LeaveBrowserRunning = driverConfiguration.LeaveBrowserRunning,
                BinaryLocation = Path.Combine(driverConfiguration.DriverPath, "msedgedriver.exe")
            };
            return new EdgeDriver(edgeOptions);
        }

        public string GetDriverExecutable()
        {
            return "msedgedriver";
        }
    }
}

Getting Started

Define your page models

using Nutstone.Selenium.Core.Attributes;

namespace test_nutstone_selenium.Tests
{
    public class TestModel
    {
        [SeleniumModel(SelectorType.Xpath, "//*[@id='simpletests']")]
        public bool SimpleTestsButton { get; set; } = false;

        [SeleniumModel(SelectorType.Xpath, "//*[@id='firstname']")]
        public string FirstName { get; set; }

        [SeleniumModel(SelectorType.Xpath, "//*[@id='surname']")]
        public string Surname { get; set; }

        [SeleniumModel(SelectorType.Xpath, "//*[@id='amount']")]
        public decimal? Amount { get; set; } = null;

        [SeleniumModel(SelectorType.Xpath, "//*[@id='amountText']")]
        public string AmountText { get; set; } = null;

        [SeleniumModel(SelectorType.Xpath, "//*[@id='sex']")]
        public string Sex { get; set; } = null;

        [SeleniumModel(SelectorType.Xpath, "//*[@id='email']")]
        public string Email { get; set; } = null;

        public DateTime DateOfBirth { get; set; } 
    }
}

Define your page processor

using Nutstone.Selenium.Core.Custom.Page;
using Nutstone.Selenium.Core.Test.Service;
using Nutstone.Selenium.Core.Webdriver.Extensions;

namespace test_nutstone_selenium.Tests
{
    public class TestPage : CustomSeleniumPage<TestModel>
    {
        public TestPage(IWebDriverProxy webDriverProxy, IWebTestService webTestService) : base(webDriverProxy, webTestService)
        {
        }

        public override IWebTestService Run()
        {
            this
                .WithClick(x => x.SimpleTestsButton)    // click on a page
                .WithUrl("/simplepage")                 // wait or this url to contain  
                .WithInput(x => x.FirstName)            // populate firstname  
                .WithInput(x => x.Surname)
                .WithInput(x => x.Amount)
                .WithSelect(x => x.Sex)
                .WithInput(x => x.Email)
                .Assert();                              // run any assertions
            return this.webTestService;
        }
    }
}

Run your test

using NUnit.Framework;
using Nutstone.Selenium.Core.Configuration;
using Nutstone.Selenium.Core.Loggers.LoggerFile;
using Nutstone.Selenium.Core.Testing;

namespace test_nutstone_selenium.Tests
{
    public class NutstoneCoreTests : SeleniumTestIntergrationFixture
    {
        
        public NutstoneCoreTests()
        {
            this.Initialise((logBuilder) => 
            {
                logBuilder.AddFileLogger(@"The-full-filename-of-the-log-file");  
            }, () => 
            {
                return DriverConfiguration.WithChrome()
                                      .SetDriverPathFromLocation(@"The-Fullpath-of-the-seleniumdriver")
                                      .SetLeaveBrowserRunng(true)
                                      .SetFullscreen(true)
                                      .SetTakeScreenShots(true)
                                      .SetClearScreenShots(true)
                                      .SetScreenShotDirectoryPath(@"Wherever-You-Want-TheScreenShots-directory");
            });
        }

        [Test]
        public void Can_Run_A_Selenium_Test()
        {
            this.RunWebTest(() =>
            {
                var basicModel = new TestModel();

                this.webTestService.OpenUrl("http://localhost:4200")
                    .WithCustomPage(basicModel)
                       .SetValue(x => x.SimpleTestsButton, true)
                       .SetValue(x => x.FirstName, "Tess")
                       .SetValue(x => x.Surname, "nutstone")
                       .SetValue(x => x.Amount, 200.34M)
                       .WithAssertion(x => x.FirstName).IsEqualTo(basicModel.FirstName)
                       .WithAssertion(x => x.AmountText).IsMonetaryEqualTo(200.34M)
                    .Run();
            });
        } 
    
    }
}

Extending your page functionality

Each custom page has access to the underlying WebDriverProxy interface and the underlying IWebdriver interface (via webDriverProxy.Driver).

so you can extend the functionaly o your page relatvely easily. In this case we are going to populate a date of birth element that has 3 html input elements:-

using Nutstone.Selenium.Core.Custom.Page;
using Nutstone.Selenium.Core.Test.Service;
using Nutstone.Selenium.Core.Webdriver.Extensions;
using OpenQA.Selenium;

namespace test_nutstone_selenium.Tests
{
    public class TestPage : CustomSeleniumPage<TestModel>
    {
        public TestPage(IWebDriverProxy webDriverProxy, IWebTestService webTestService) : base(webDriverProxy, webTestService)
        {
        }

        private TestPage WithDate()
        {
            var dobAsStringArray = this.Model.DateOfBirth.ToShortDateString()
                .Split("/");
            this.webDriverProxy
                .WithInput(By.XPath("//*[@id='dob-dd']"), dobAsStringArray[0], true)
                .WithInput(By.XPath("//*[@id='dob-mm']"), dobAsStringArray[1], true)
                .WithInput(By.XPath("//*[@id='dob-yy']"), dobAsStringArray[2], true);
            return this;
        } 

        public override IWebTestService Run()
        {
            this
                .WithClick(x => x.SimpleTestsButton)    // click on a page
                .WithUrl("/simplepage")                 // wait or this url to contain  
                .WithInput(x => x.FirstName)            // populate firstname  
                .WithInput(x => x.Surname)
                .WithInput(x => x.Amount)
                .WithSelect(x => x.Sex);
            this.WithDate();    
            this
                .WithInput(x => x.Email)
                .Assert();                              // run any assertions
            return this.webTestService;
        }
    }
}

Extending your page functionality using an injected service

You can define your own transient service to supply extra functionality to your page(s).

define an interface that implements the pseudo interface ICustomWebProxyDriver

using Nutstone.Selenium.Core.Webdriver.Extensions;
using System;

namespace test_nutstone_selenium.Tests
{
    public interface ITestCustomWebProxyDriver : ICustomWebDriverProxy
    {
        void WithDate(DateTime date);
    }
}

Implement the interface

using Nutstone.Selenium.Core.Loggers.Extended.Logger;
using Nutstone.Selenium.Core.Webdriver.Extensions;
using OpenQA.Selenium;
using System;

namespace test_nutstone_selenium.Tests
{
    public class TestCustomWebProxyDriver : ITestCustomWebProxyDriver
    {
        private readonly IExtendedLogger log;

        private readonly IWebDriverProxy webDriverProxy;


        public TestCustomWebProxyDriver(IExtendedLogger extendedLogger, 
                                        IWebDriverProxy webDriverProxy)
        {
            this.log = extendedLogger;
            this.webDriverProxy = webDriverProxy;
        }

        public void WithDate(DateTime date)
        {
            var dobAsStringArray = date.ToShortDateString()
                .Split("/");
            this.webDriverProxy
                .WithInput(By.XPath("//*[@id='dob-dd']"), dobAsStringArray[0], true)
                .WithInput(By.XPath("//*[@id='dob-mm']"), dobAsStringArray[1], true)
                .WithInput(By.XPath("//*[@id='dob-yy']"), dobAsStringArray[2], true);
        }
    }
}

inject the interface into your page

using Nutstone.Selenium.Core.Custom.Page;
using Nutstone.Selenium.Core.Test.Service;
using Nutstone.Selenium.Core.Webdriver.Extensions;

namespace test_nutstone_selenium.Tests
{
    public class TestPage : CustomSeleniumPage<TestModel>
    {
        private readonly ITestCustomWebProxyDriver testCustomWebProxyDriver;


        public TestPage(ITestCustomWebProxyDriver testCustomWebProxyDriver, IWebDriverProxy webDriverProxy, IWebTestService webTestService) : base(webDriverProxy, webTestService)
        {
            this.testCustomWebProxyDriver = testCustomWebProxyDriver;
        }

        public override IWebTestService Run()
        {
            this
                .WithClick(x => x.SimpleTestsButton)    // click on a page
                .WithUrl("/simplepage")                 // wait or this url to contain  
                .WithInput(x => x.FirstName)            // populate firstname  
                .WithInput(x => x.Surname)
                .WithInput(x => x.Amount)
                .WithSelect(x => x.Sex);
            this.testCustomWebProxyDriver.WithDate(this.Model.DateOfBirth);   
            this
                .WithInput(x => x.Email)
                .Assert();                              // run any assertions
            return this.webTestService;
        }
    }
}

Defining an Application to Chain Pages

To create an application that will chain pages together in a predefinied order first create a custom application model that contains all the properties from the various pages you want to include in the application. The property names and types should EXACTLY match the names/types of the target pages:-

    public class BasicTestSeleniumApplication
    {
        public string FirstName { get; set; }

        public string Surname { get; set; }

        public decimal? Amount { get; set; }

        public string Sex { get; set; }

        public string Email { get; set; }

        public string MatInput { get; set; }

    }

Then create your application.

    public class BasicCustomApplication : CustomSeleniumApplication<BasicTestSeleniumApplication>
    {
        public BasicCustomApplication(IWebTestService webTestService, IExtendedLogger logger)
        : base(webTestService, logger)
        {
        }

        /// <summary>
        /// Register all the pages we are going to use in our application
        /// </summary>
        public override void RegisterPages()
        {
            this
                .RegisterPage(new BasicTestSeleniumModel())
                .RegisterPage(new BasicMaterialSeleniumModel());
        }

        public override IWebTestService Run()
        {
            this.MapByConvention(); // map our model to the pages we have registered

            // Run that application pages in the order we want
            return this.webTestService
                .WithCustomPage<BasicTestSeleniumModel>()
                   .SetValue(x => x.SimpleTestsButton, true)
                .Run() // assertions are run as part of the model run
                .WithCustomPage<BasicMaterialSeleniumModel>()
                   .SetValue(x => x.MaterialTestsButton, true)
                .Run();
        }
    }

You must register the pages you are going to use. call MapByConvetion method of the base class if you want it to automatically map (using reflection) the values in your application model to the associated properties in the page models (that you have registered)

Run the test!

note to run assertions in your application test you must reference the assertion of the page model directly.

        [Test]
        public void Can_RunSimple_Application_With_Assertions()
        {
            this.RunWebTest(() =>
            {
                this.webTestService
                    .OpenUrl(baseUrl)
                    .WithApplication(new BasicTestSeleniumApplication()
                    {
                        Amount = 20012.43M,
                        FirstName = "Tess",
                        Surname = "Nuttall",
                        Sex = "Female",
                        Email = "Tess@somewhere.com",
                        MatInput = "This is a mat input"
                    })
                    .WithPage<BasicTestSeleniumModel>((page) => 
                    {
                        page
                        .WithAssertion(x => x.FirstName).IsEqualTo("Tess");
                    })
                    .Run();
            });
        }

Contact

nutstone.selenium@gmail.com