Getting Started

Atata Framework - C#/.NET web test automation full-featured framework based on Selenium WebDriver. It uses a fluent page object pattern; has a built-in logging system; contains a unique triggers functionality; has a set of ready-to-use components. One of the key ideas of the framework is to provide a simple and intuitive syntax for defining and using page objects. A page object implementation requires as less code as possible. You can describe a page object class without any methods and only have a set of properties marked with attributes representing page components.

The framework is completely open source and hosted on GitHub as Atata Framework organization under the Apache License 2.0. All framework libraries are published and available as NuGet packages.

The framework basically consists of the following concepts:

AtataContext
- Configuration - use fluent builder and/or JSON config.
Components
- Controls
- Page objects
- Control list
Attributes
- Attributes of control search - basically, element locators, like [FindById], [FindByName], [FindByXPath], etc.
- Trigger attributes - a functionality that is automatically executed in response to certain events on a particular component. For example, when a click on button occurs it may be defined that a wait should be executed.
- Behavior attributes - change the way how particular actions are executed. For example, specify the click behavior for a specific button by adding [ClickUsingScript] to perform the click using JavaScript, instead of default IWebElement.Click() way.
- Settings attributes - set settings for control finding, culture, value format, etc.
Verification functionality
- .Should.* - an assertion. For example: UserName.Should.Be("John").
- .ExpectTo.* - an expectation, which produces a warning.
- .WaitTo.* - a waiting for a certain condition.

Atata Framework consists of a set of NuGet packages.

Main Packages

Atata (GitHub | NuGet) - is a main package, which provides base and main functionality for web UI testing.
Atata.Configuration.Json (GitHub | NuGet) - provides configuration through JSON files.
Atata.WebDriverSetup (GitHub | NuGet) - sets up browser drivers, e.g. chromedriver, geckodriver, etc. Basically, it provides functionality similar to Java WebDriverManager.
Atata.HtmlValidation (GitHub | NuGet) - adds HTML page validation to Atata using html-validate NPM package.
Atata.Bootstrap (GitHub | NuGet) - contains a set of Atata components for Bootstrap Framework.
Atata.KendoUI (GitHub | NuGet) - contains a set of Atata components for Kendo UI HTML Framework.

Additional Packages

Atata.WebDriverExtras (GitHub | NuGet) - contains extension methods and other extra classes for Selenium WebDriver. Used by Atata.
Atata.Cli (GitHub | NuGet) - provides an API for CLI.
Atata.Cli.Npm (GitHub | NuGet) - provides an API for CLI of NPM.
Atata.Cli.HtmlValidate (GitHub | NuGet) - provides an API for CLI of html-validate NPM package.

There are 2 options to create a project in Visual Studio for automated testing using Atata Framework.

Install via Atata Templates

To get started, install Atata Templates Visual Studio extension.

The extension provides the following templates:

Project templates:
- Atata NUnit Basic Test Project (.NET 6)
- Atata NUnit Basic Test Project (.NET 8)
- Atata NUnit Advanced Test Project (.NET 6)
- Atata NUnit Advanced Test Project (.NET 8)
Item templates:
- Atata Page Object
- Atata Base Page Object
- Atata Control
- Atata Trigger
- Atata NUnit Test Fixture
- Atata NUnit Base Test Fixture

Create Project

When extension is installed, you can create a project of one of Atata project types. In Visual Studio:

Go to File/New/Project… or File/Add/New Project… (to add to existing solution).
Type Atata into search box or choose Atata in “project types” drop-down.
Choose template, e.g., Atata NUnit Advanced Test Project (.NET 8), and specify project name and location.

Atata Templates project

Project References

The project is created with NuGet package references:

Atata
Atata.WebDriverSetup
Microsoft.NET.Test.Sdk
NUnit
NUnit3TestAdapter
Atata.Configuration.Json (for advanced project)
NLog (for advanced project)

Configuration

You don’t need to configure specific browser driver packages, as a project is by default configured to automatically download appropriate driver, by use of Atata.WebDriverSetup package.

In the created project you can specify your testing site base URL and appropriate driver in SetUpFixture.cs or Atata.local.json class, depending on type of project (basic or advanced).

AtataContext.GlobalConfiguration
    .UseChrome()
        .WithArguments("start-maximized")
    .UseBaseUrl("https://atata.io/")
    //...

{
  "baseUrl": "https://atata.io/"
  // Other environment specific configuration properties can be added here.
}

Just replace "https://atata.io/" string with your URL.

Test Fixtures

The created project also contains ready to use SampleTests.cs fixture, which can be either modified or removed:

namespace AtataUITests1;

public class SampleTests : UITestFixture
{
    [Test]
    public void SampleTest() =>
        Go.To<OrdinaryPage>()
            .PageTitle.Should.Contain("Atata");
}

Further test fixture classes are recommended to inherit from UITestFixture, or just choose “Atata NUnit Test Fixture” item template in “Add New Item Window”.

Create Project Targeting Other .NET Version

Create a project using one of the project templates: “Atata NUnit Basic Test Project (.NET 6)”, “Atata NUnit Advanced Test Project (.NET 6)”.
Open project .csproj file.

Change the value of <TargetFramework> tag from net6.0 to the needed version.

<Project Sdk="Microsoft.NET.Sdk">
   
  <PropertyGroup>
    <TargetFramework>NET_VERSION</TargetFramework>
    <!-- ... -->
  </PropertyGroup>
   
  <!-- ... -->
   
</Project>

Install via NuGet

It is a more custom approach to create Atata testing project. To get started just add Atata NuGet package to the project of Class Library (.NET Framework, .NET Core or .NET 5+) type in Visual Studio.

PM> Install-Package Atata

The Atata package depends on the following packages, which are added automatically:

You might also need to install Atata.WebDriverSetup package for auto-setup of browser drivers, e.g. chromedriver, geckodriver, etc. This is a recommended option. Alternatively, you can install a driver package for specific browser: Selenium.WebDriver.ChromeDriver, Selenium.WebDriver.IEDriver, etc. But be aware to keep version synchronization of browser and driver.

You are also free to select any test engine framework: NUnit, Xunit, MSTest, SpecFlow, etc.

For .NET Core and .NET 5+ projects it is required also to add Microsoft.NET.Test.Sdk package to the project that contains tests (no matter NUnit, xUnit, MSTest, etc.).

NUnit Project Configuration

In addition to Atata NuGet package, add the following packages:

Then add 2 C# class files.

The first SetUpFixture class sets the global Atata configuration, like which browser driver to use, basic URL, etc. Then it sets up an appropriate driver executable for the browser to use.

SetUpFixture.cs

using Atata;
using NUnit.Framework;

namespace SampleApp.UITests;

[SetUpFixture]
public class SetUpFixture
{
    [OneTimeSetUp]
    public void GlobalSetUp()
    {
        AtataContext.GlobalConfiguration
            .UseChrome()
                .WithArguments("start-maximized")
            .UseBaseUrl("https://atata.io/")
            .UseCulture("en-US")
            .UseAllNUnitFeatures();

        AtataContext.GlobalConfiguration.AutoSetUpDriverToUse();
    }
}

The second UITestFixture class is the base class for all test fixture classes that have UI tests. It just starts an Atata session before the test run and closes it after the test is finished.

SetUpFixture.cs

using Atata;
using NUnit.Framework;

namespace SampleApp.UITests;

[TestFixture]
[Parallelizable(ParallelScope.Self)]
public class UITestFixture
{
    [SetUp]
    public void SetUp() =>
        AtataContext.Configure().Build();

    [TearDown]
    public void TearDown() ==>
        AtataContext.Current?.Dispose();
}

Lat’s create a simple test automation project example with a test for Sign In page.

Create Project

In Visual Studio create a project using Installation instructions.

Set Atata base URL to "https://demo.atata.io/" either in SetUpFixture.cs or Atata.local.json file.

Define Page Object Class

SignInPage.cs

namespace AtataDemo.UITests;

using _ = SignInPage;

[Url("signin")]
public class SignInPage : Page<_>
{
    public TextInput<_> Email { get; private set; }

    public PasswordInput<_> Password { get; private set; }

    public Button<_> SignIn { get; private set; }
}

The aspects of the created page object:

[Url("signin")] - sets the relative URL of the page to be navigated to. Good for pages with static URLs.
Default search of Email and Password controls is performed by label. Can be changed/configured.
Default search of SignIn button is performed by its text.

Implement Test

SignInTests.cs

namespace AtataDemo.UITests;

[TestFixture]
public class SignInTests : UITestFixture
{
    [Test]
    public void SignIn() =>
        Go.To<SignInPage>()
            .Email.Type("admin@mail.com")
            .Password.Type("abc123")
            .SignIn.Click();
}

View Log

The above sample SignIn test generates the following log to NUnit output:

2023-10-19 12:16:24.1153  INFO Starting test: AtataDemo.UITests.SignInTests.SignIn
2023-10-19 12:16:24.1247 TRACE > Initialize AtataContext
2023-10-19 12:16:24.1264 TRACE - Set: BaseUrl=https://demo.atata.io/
2023-10-19 12:16:24.1275 TRACE - Set: ElementFindTimeout=5s; ElementFindRetryInterval=0.5s
2023-10-19 12:16:24.1277 TRACE - Set: WaitingTimeout=5s; WaitingRetryInterval=0.5s
2023-10-19 12:16:24.1278 TRACE - Set: VerificationTimeout=5s; VerificationRetryInterval=0.5s
2023-10-19 12:16:24.1281 TRACE - Set: Culture=en-US
2023-10-19 12:16:24.1285 TRACE - Set: Artifacts=D:\dev\AtataDemo.UITests\AtataDemo.UITests\bin\Debug\net7.0\artifacts\20231019T121624\SignInTests\SignIn
2023-10-19 12:16:24.1293 TRACE - > Initialize Driver
2023-10-19 12:16:24.1331 TRACE - - Created ChromeDriverService { Port=56112, ExecutablePath=D:\dev\AtataDemo.UITests\AtataDemo.UITests\bin\Debug\net7.0\drivers\chrome\118.0.5993.70\chromedriver.exe }
2023-10-19 12:16:24.8457 TRACE - - Created ChromeDriver { Alias=chrome, SessionId=40696ddb9dbb756cbcfb0de8ab0e8412 }
2023-10-19 12:16:24.8521 TRACE - < Initialize Driver (0.718s)
2023-10-19 12:16:24.8531 TRACE < Initialize AtataContext (0.728s)
2023-10-19 12:16:24.9119  INFO > Go to "Sign In" page by URL https://demo.atata.io/signin
2023-10-19 12:16:24.9130 TRACE - > Navigate to URL https://demo.atata.io/signin
2023-10-19 12:16:25.3187 TRACE - < Navigate to URL https://demo.atata.io/signin (0.405s)
2023-10-19 12:16:25.3566  INFO < Go to "Sign In" page by URL https://demo.atata.io/signin (0.444s)
2023-10-19 12:16:25.3692  INFO > Type "admin@mail.com" in "Email" text input
2023-10-19 12:16:25.3727 TRACE - > Execute behavior TypesTextUsingSendKeysAttribute against "Email" text input
2023-10-19 12:16:25.3960 TRACE - - > Find element by XPath "(.//*[@id = //label[normalize-space(.) = 'Email']/@for]/descendant-or-self::input[@type='text' or not(@type)] | .//label[normalize-space(.) = 'Email']/descendant-or-self::input[@type='text' or not(@type)])" in ChromeDriver
2023-10-19 12:16:25.4187 TRACE - - < Find element by XPath "(.//*[@id = //label[normalize-space(.) = 'Email']/@for]/descendant-or-self::input[@type='text' or not(@type)] | .//label[normalize-space(.) = 'Email']/descendant-or-self::input[@type='text' or not(@type)])" in ChromeDriver (0.021s) >> Element { Id=899920EE3DDF8CF5FDC58EB63A55E6A0_element_5 }
2023-10-19 12:16:25.4200 TRACE - - > Send keys "admin@mail.com" to element { Id=899920EE3DDF8CF5FDC58EB63A55E6A0_element_5 }
2023-10-19 12:16:25.4948 TRACE - - < Send keys "admin@mail.com" to element { Id=899920EE3DDF8CF5FDC58EB63A55E6A0_element_5 } (0.074s)
2023-10-19 12:16:25.4953 TRACE - < Execute behavior TypesTextUsingSendKeysAttribute against "Email" text input (0.122s)
2023-10-19 12:16:25.4954  INFO < Type "admin@mail.com" in "Email" text input (0.126s)
2023-10-19 12:16:25.4956  INFO > Type "abc123" in "Password" password input
2023-10-19 12:16:25.4959 TRACE - > Execute behavior TypesTextUsingSendKeysAttribute against "Password" password input
2023-10-19 12:16:25.4967 TRACE - - > Find element by XPath "(.//*[@id = //label[normalize-space(.) = 'Password']/@for]/descendant-or-self::input[@type='password'] | .//label[normalize-space(.) = 'Password']/descendant-or-self::input[@type='password'])" in ChromeDriver
2023-10-19 12:16:25.5115 TRACE - - < Find element by XPath "(.//*[@id = //label[normalize-space(.) = 'Password']/@for]/descendant-or-self::input[@type='password'] | .//label[normalize-space(.) = 'Password']/descendant-or-self::input[@type='password'])" in ChromeDriver (0.014s) >> Element { Id=899920EE3DDF8CF5FDC58EB63A55E6A0_element_6 }
2023-10-19 12:16:25.5120 TRACE - - > Send keys "abc123" to element { Id=899920EE3DDF8CF5FDC58EB63A55E6A0_element_6 }
2023-10-19 12:16:25.5612 TRACE - - < Send keys "abc123" to element { Id=899920EE3DDF8CF5FDC58EB63A55E6A0_element_6 } (0.049s)
2023-10-19 12:16:25.5620 TRACE - < Execute behavior TypesTextUsingSendKeysAttribute against "Password" password input (0.066s)
2023-10-19 12:16:25.5623  INFO < Type "abc123" in "Password" password input (0.066s)
2023-10-19 12:16:25.5628  INFO > Click "Sign In" button
2023-10-19 12:16:25.5637 TRACE - > Execute behavior ClicksUsingClickMethodAttribute against "Sign In" button
2023-10-19 12:16:25.5650 TRACE - - > Find element by XPath ".//*[self::input[@type='button' or @type='submit' or @type='reset'] or self::button][normalize-space(.) = 'Sign In' or normalize-space(@value) = 'Sign In']" in ChromeDriver
2023-10-19 12:16:25.5823 TRACE - - < Find element by XPath ".//*[self::input[@type='button' or @type='submit' or @type='reset'] or self::button][normalize-space(.) = 'Sign In' or normalize-space(@value) = 'Sign In']" in ChromeDriver (0.017s) >> Element { Id=899920EE3DDF8CF5FDC58EB63A55E6A0_element_10 }
2023-10-19 12:16:25.5830 TRACE - - > Click element { Id=899920EE3DDF8CF5FDC58EB63A55E6A0_element_10 }
2023-10-19 12:16:25.6589 TRACE - - < Click element { Id=899920EE3DDF8CF5FDC58EB63A55E6A0_element_10 } (0.075s)
2023-10-19 12:16:25.6596 TRACE - < Execute behavior ClicksUsingClickMethodAttribute against "Sign In" button (0.095s)
2023-10-19 12:16:25.6601  INFO < Click "Sign In" button (0.097s)
2023-10-19 12:16:25.6614 TRACE > Deinitialize AtataContext
2023-10-19 12:16:25.8006 TRACE < Deinitialize AtataContext (0.139s)
2023-10-19 12:16:25.8046  INFO Finished test
      Total time: 1.754s
  Initialization: 0.806s | 46.0 %
       Test body: 0.807s | 46.1 %
Deinitialization: 0.139s |  8.0 %

Demo atata-framework/atata-sample-app-tests UI tests application demonstrates different testing approaches and features of Atata Framework. It uses Atata Sample App (repository) as a testing website and NUnit 3 as a test engine.

Features

Atata configuration and settings set-up.
Page navigation.
Controls finding.
Data input and verification.
Validation messages verification.
Usage of triggers.
Interaction with pop-ups (Bootstrap modal) and alerts.
Work with tables.
Logging, screenshots and snapshots.
Page HTML validation.

Sample Test

public class UserTests : UITestFixture
{
    [Test]
    public void Create() =>
        Login()
            .New()
                .ModalTitle.Should.Be("New User")
                .General.FirstName.SetRandom(out string firstName)
                .General.LastName.SetRandom(out string lastName)
                .General.Email.SetRandom(out string email)
                .General.Office.SetRandom(out Office office)
                .General.Gender.SetRandom(out Gender gender)
                .Save()
            .GetUserRow(email).View()
                .AggregateAssert(x => x
                    .Header.Should.Be($"{firstName} {lastName}")
                    .Email.Should.Be(email)
                    .Office.Should.Be(office)
                    .Gender.Should.Be(gender)
                    .Birthday.Should.Not.BeVisible()
                    .Notes.Should.Not.BeVisible());

    //...
}

In SetUp method just invoke AtataContext.Configure() method that returns AtataContextBuilder instance, then invoke configuration methods and finally invoke Build() method:

[SetUp]
public void SetUp()
{
    AtataContext.Configure()
        // TODO: Use configuration methods.
        .Build();
}

To clean up the AtataContext, call its Dispose method in the TearDown method:

[TearDown]
public void TearDown()
{
    AtataContext.Current?.Dispose();
}

The Dispose method also, by default, closes a web driver instance as well as a browser.

Also, it is recommended to extract a global setup/configuration to the global setup method:

[SetUpFixture]
public class SetUpFixture
{
    [OneTimeSetUp]
    public void GlobalSetUp()
    {
        AtataContext.GlobalConfiguration
            // TODO: Use configuration methods.
            .AutoSetUpDriverToUse();
    }
}

Consider taking a look at Atata.Configuration.Json for configuration through JSON files.

Driver

The list of driver configuration methods of AtataContextBuilder:

public ChromeAtataContextBuilder

UseChrome()

Creates and returns a new builder for ChromeDriver with default DriverAliases.Chrome alias. Sets this builder as a one to use for a driver creation.

public FirefoxAtataContextBuilder

UseFirefox()

Creates and returns a new builder for FirefoxDriver with default DriverAliases.Firefox alias. Sets this builder as a one to use for a driver creation.

public InternetExplorerAtataContextBuilder

UseInternetExplorer()

Creates and returns a new builder for InternetExplorerDriver with default DriverAliases.InternetExplorer alias. Sets this builder as a one to use for a driver creation.

public EdgeAtataContextBuilder

UseEdge()

Creates and returns a new builder for EdgeDriver with default DriverAliases.Edge alias. Sets this builder as a one to use for a driver creation.

public SafariAtataContextBuilder

UseSafari()

Creates and returns a new builder for SafariDriver with default DriverAliases.Safari alias. Sets this builder as a one to use for a driver creation.

public RemoteDriverAtataContextBuilder

UseRemoteDriver()

Creates and returns a new builder for RemoteWebDriver with default DriverAliases.Remote alias. Sets this builder as a one to use for a driver creation.

public CustomDriverAtataContextBuilder

UseDriver(IWebDriver driver)

Use the specified driver instance.

public CustomDriverAtataContextBuilder

UseDriver(Func<IWebDriver> driverFactory)

Use the custom driver factory method.

public TDriverBuilder

UseDriver<TDriverBuilder>(TDriverBuilder driverBuilder)

Use the driver builder.

public AtataContextBuilder

UseDriver(string alias)

Sets the alias of the driver to use.

public ChromeAtataContextBuilder

ConfigureChrome(string alias = DriverAliases.Chrome)

Returns an existing or creates a new builder for ChromeDriver by the specified alias.

public FirefoxAtataContextBuilder

ConfigureFirefox(string alias = DriverAliases.Firefox)

Returns an existing or creates a new builder for FirefoxDriver by the specified alias.

public InternetExplorerAtataContextBuilder

ConfigureInternetExplorer(string alias = DriverAliases.InternetExplorer)

Returns an existing or creates a new builder for InternetExplorerDriver by the specified alias.

public EdgeAtataContextBuilder

ConfigureEdge(string alias = DriverAliases.Edge)

Returns an existing or creates a new builder for EdgeDriver by the specified alias.

public SafariAtataContextBuilder

ConfigureSafari(string alias = DriverAliases.Safari)

Returns an existing or creates a new builder for SafariDriver by the specified alias.

public RemoteDriverAtataContextBuilder

ConfigureRemoteDriver(string alias = DriverAliases.Remote)

Returns an existing or creates a new builder for RemoteWebDriver by the specified alias.

public TDriverBuilder

ConfigureDriver<TDriverBuilder>(string alias, Func<TDriverBuilder> driverBuilderCreator)

Returns an existing or creates a new builder for TDriverBuilder by the specified alias.

public AtataContextBuilder

UseDisposeDriver(bool disposeDriver)

Sets a value indicating whether to dispose the AtataContext.Driver when AtataContext.Dispose method is invoked. The default value is true.

public AtataContextBuilder

UseDriverInitializationStage(AtataContextDriverInitializationStage stage)

Sets the driver initialization stage. The default value is AtataContextDriverInitializationStage.Build.

public void

AutoSetUpDriverToUse()

public async Task

AutoSetUpDriverToUseAsync()

Sets up driver with auto version detection for the local browser to use. Gets the name of the local browser to use from AtataBuildingContext.LocalBrowserToUseName property. Then invokes Atata.WebDriverSetup.DriverSetup.AutoSetUpSafely(...) static method from Atata.WebDriverSetup package.

public void

AutoSetUpConfiguredDrivers()

public async Task

AutoSetUpConfiguredDriversAsync()

Sets up drivers with auto version detection for the local configured browsers. Gets the names of configured local browsers from AtataBuildingContext.ConfiguredLocalBrowserNames property. Then invokes Atata.WebDriverSetup.DriverSetup.AutoSetUpSafely(...) static method from Atata.WebDriverSetup package.

Driver Configuration

It is possible to configure the driver using the following methods of driver builders. The amount of methods vary dependently of the driver builder type, for example Chrome and Edge builders support the most amount.