Tutorials

Tutorials

Behavior-Style Workflows with GPAL.Gherkin

GPAL.Gherkin lets you write the same kind of workflow as tut-simple-scraper as a Given/When/And/Then scenario - each step is a plain method, no special syntax or test framework required. This tutorial rewrites the eBay search as a behavior spec and shows how steps with parameters work.

Complete Program

Here's the whole workflow, start to finish. Each piece is broken down and explained below.

using System;

using System.Diagnostics;

using GenerallyPositive;

using GenerallyPositive.Browser;

using static GenerallyPositive.Enums;

GPAL

.WithPublishToConsole()

.WithAutoUpdateWebDriver()

.WithDriverLocation(@"c:drivers");

IBrowser browser;

IGPALGrid<string> resultGrid;

Selector inputSearchSelector = "#gh-ac";

Selector searchButton = "#gh-search-btn";

Selector descriptionColumn = @"//span[contains(@class, 'su-styled-text primary default')]";

Selector priceColumn = @"//span[contains(@class, 'su-styled-text primary bold large-1 s-card__price')]";

inputSearchSelector.WithSelectorName("SearchInput");

searchButton.WithSelectorName("SearchButton").MatchText("Search");

descriptionColumn.WithSelectorName("Description");

priceColumn.WithSelectorName("Price");

GPAL.Gherkin

.Given(BrowserIsOnEbay)

.When(UserSearchesFor, "Dog Treats")

.And(FirstResultIsCollected)

.Then(ResultIsPrinted)

.And(BrowserCloses);

void BrowserIsOnEbay()

{

browser = GPAL.Browser

.WithBrowserType(BrowserType.Chrome)

.WithUseAutomationEngine(AutomationEngine.PuppeteerPort)

.WithWaitOnDocumentReady(30_000)

.ToGPALObject();

browser.GoTo("https://www.ebay.com/");

}

void UserSearchesFor(string searchTerm)

{

browser

.WaitFor(2_000)

.WithSelector(inputSearchSelector)

.FillInFrom(searchTerm)

.LeftClick(searchButton);

}

void FirstResultIsCollected()

{

browser

.WaitFor(2_000)

.WithSelector(descriptionColumn)

.WithSelector(priceColumn)

.WithAllThatMatch(1)

.GetGrid(out resultGrid);

}

void ResultIsPrinted()

{

string description = resultGrid[0][0];

string price = resultGrid[0][1];

Console.WriteLine($"First result: {description} - {price}");

}

void BrowserCloses()

{

browser.Close(true);

}

A Scenario Is Just Method Names

GPAL.Gherkin.Given/When/And/Then accept a plain method group plus, optionally, the arguments that method needs. There's no Delegate wrapper, no params object[], and no new Action<>(...) noise - the compiler checks each step's signature against the arguments you pass, the same as calling any other method. Reading top to bottom, the scenario is the workflow.

GPAL.Gherkin

.Given(BrowserIsOnEbay)

.When(UserSearchesFor, "Dog Treats")

.And(FirstResultIsCollected)

.Then(ResultIsPrinted)

.And(BrowserCloses);

TIP

There's no separate "execute the scenario" call. As soon as Given/When/And/Then is added to the chain, that step's method body runs. The chain reads like a script because it executes like one, top to bottom, in order.

Given: Set the Scene

The Given step launches the browser and navigates to eBay - exactly the same GPAL.Browser factory chain from tut-simple-scraper. Nothing about Gherkin changes how you build a browser; it just gives the step a name that documents its role in the scenario.

void BrowserIsOnEbay()

{

browser = GPAL.Browser

.WithBrowserType(BrowserType.Chrome)

.WithUseAutomationEngine(AutomationEngine.PuppeteerPort)

.WithWaitOnDocumentReady(30_000)

.ToGPALObject();

browser.GoTo("https://www.ebay.com/");

}

When/And: Steps That Take Arguments

UserSearchesFor takes a string parameter, so the call site passes it right after the method group: .When(UserSearchesFor, "Dog Treats"). GPAL.Gherkin has overloads for steps that take zero, one, two, or three arguments of any type - whatever UserSearchesFor's signature declares is what you must supply. FirstResultIsCollected takes no arguments and reads the same selectors-then-grid pattern from tut-simple-scraper.

void UserSearchesFor(string searchTerm)

{

browser

.WaitFor(2_000)

.WithSelector(inputSearchSelector)

.FillInFrom(searchTerm)

.LeftClick(searchButton);

}

void FirstResultIsCollected()

{

browser

.WaitFor(2_000)

.WithSelector(descriptionColumn)

.WithSelector(priceColumn)

.WithAllThatMatch(1)

.GetGrid(out resultGrid);

}

Then/And: Verify and Clean Up

ResultIsPrinted reads the grid populated by the previous step and writes the result to the console - this is where you'd normally put an assertion if this scenario were part of a test suite. BrowserCloses shuts everything down. Because each step is just a method, you can reuse BrowserIsOnEbay, UserSearchesFor, and friends across multiple scenarios in the same file.

void ResultIsPrinted()

{

string description = resultGrid[0][0];

string price = resultGrid[0][1];

Console.WriteLine($"First result: {description} - {price}");

}

void BrowserCloses()

{

browser.Close(true);

}

WARNING

Just like in tut-simple-scraper, passing true to Close kills the running web driver process. Use true when the scenario is the last thing using that browser.

On this page

Tutorials
Behavior-Style Workflows with GPAL.Gherkin
  • Complete Program
  • A Scenario Is Just Method Names
  • Given: Set the Scene
  • When/And: Steps That Take Arguments
  • Then/And: Verify and Clean Up