Class Browser
Browser object that contains the fluent methods to create your Browser workflow.
Instatiated using GPAL.Browser
Inheritance
System.Object
Browser
Inherited Members
System.Object.ToString()
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
Assembly: GPAL.dll
Syntax
public class Browser : IBrowser, IAllowWithPagesAndGridActions, IAllowWithHeaderOrFileActions, IAllowWithHeader, IAllowFileActions, IAllowBrowserActionOrAnySelector, IAllowAfterAnySelectorExceptWithAll, IAllowAfterWaitForAndSizeControl, IAllowAfterWaitFor, IAllowWaitForWindow, IAllowAllBrowserAndAllSelector, IAllowBrowserAction, IAllowClose, IAllowTabActions, IAllowWindowScrollBy, IAllowPageControl, IAllowExecuteJavaScript, IAllowAfterAnySelector, IAllowWithNextPageButtonOrGetGrid, IAllowWithNextPageButton, IAllowWithInfiniteScroll, IAllowWithPages, IAllowAnySelector, IAllowWithSelector, IAllowInSelector, IAllowWithAllThatMatch, IAllowWithHardware, IAllowWithJavaScript, IAllowWaitFor, IAllowCallBack, IAllowBrowserSettingsOrGoTo, IAllowBrowserSettingsOrSelectorAction, IAllowBrowserSettings, IAllowSizeControl, IAllowPersistentCallBack, IAllowWithPersistentSelector, IAllowNewTab, IAllowNetworkIdleSettings, IAllowDebugPort, IAllowSelectorAction, IAllowClicks, IAllowFocus, IAllowHover, IAllowMoveTo, IAllowScrolling, IAllowDragAndDrop, IAllowPrintDomElement, IAllowGetGridAndFillInFrom, IAllowGetGrid, IAllowFillInFrom, IAllowStartWorkflow, IAllowWithGridToSave, IAllowBrowserTypeOrGoto, IAllowBrowserType, IAllowGoToOrGet, IAllowGoTo, IAllowGet, IAllowWorkflowExecution, IAllowWorkflow, IAllowRunMode, IAllowRun, IAllowToGPALObject<IBrowser>
Examples
Selector inputSearchSelector = (Selector)GPAL.Selector
.WithName("SearchInput")
.WithCSS("#gh-ac")
.WithXPath("//*[@id=\"gh-ac\"]")
.MatchPlaceholder("Search for anything");
Browser myBrowser = (Browser)GPAL.Browser
.WithBrowserType(BrowserType.Chrome)
.WithDriverLocation(@"c:\drivers")
.GoTo("https://www.ebay.com/")
.WithWaitOnDocumentReady(true)
.WithSelector(inputSearchSelector)
.FillInFrom("Find me");
Properties
Back
Declaration
public IAllowBrowserActionOrAnySelector Back { get; }
Property Value
BrowserDriver
The browser driver controlling the current Browser.
Only available after the first .GoTo
NOTE: Only for extended Selenium control access. Be careful.
Declaration
public IWebDriver BrowserDriver { get; }
Property Value
| Type |
Description |
| OpenQA.Selenium.IWebDriver |
|
BrowserType
Return the current browser type.
Declaration
public Enums.BrowserType BrowserType { get; }
Property Value
BrowserVersion
Declaration
public string BrowserVersion { get; }
Property Value
| Type |
Description |
| System.String |
|
CurrentTab
Declaration
public int CurrentTab { get; }
Property Value
| Type |
Description |
| System.Int32 |
|
FileDownloaded
Declaration
public bool FileDownloaded { get; set; }
Property Value
| Type |
Description |
| System.Boolean |
|
Forward
Navigate forward one page
Declaration
public IAllowBrowserActionOrAnySelector Forward { get; }
Property Value
FullScreen
Declaration
public IAllowAllBrowserAndAllSelector FullScreen { get; }
Property Value
JavaScriptResultObj
Declaration
public object JavaScriptResultObj { get; }
Property Value
| Type |
Description |
| System.Object |
|
JavaScriptResultStr
Declaration
public string JavaScriptResultStr { get; }
Property Value
| Type |
Description |
| System.String |
|
Maximize
Maximize the browser to full-screen
Declaration
public IAllowAllBrowserAndAllSelector Maximize { get; }
Property Value
Minimize
Minimize the browser to the taskbar
Declaration
public IAllowAllBrowserAndAllSelector Minimize { get; }
Property Value
PageDown
Scroll the current tab window down one page
Declaration
public IAllowBrowserActionOrAnySelector PageDown { get; }
Property Value
PageEnd
Declaration
public IAllowBrowserActionOrAnySelector PageEnd { get; }
Property Value
PageTop
Declaration
public IAllowBrowserActionOrAnySelector PageTop { get; }
Property Value
PageUp
Scroll the current tab window up one page
Declaration
public IAllowBrowserActionOrAnySelector PageUp { get; }
Property Value
Refresh
Declaration
public IAllowBrowserActionOrAnySelector Refresh { get; }
Property Value
Restore
Restore the browser to window state, unminimize
Declaration
public IAllowAllBrowserAndAllSelector Restore { get; }
Property Value
WithHardware
Specifies to use hardware emulation when interacting with the Selector just defined with .WithSelector. Use this to override what is defined on the Selector.
Selenium is the default method to interact with elements, but sometimes hardware emulation is the only way that works.
You can also specify to execute javascript on the page to interact with elements.
Declaration
public IAllowAfterAnySelector WithHardware { get; }
Property Value
Indicates the current page does not have a Next Page button, but an infinite scroll.
GPAL pagination then consists of moving to the bottom and waiting for the DocumentReady before paging again.
Declaration
public IAllowWithPagesAndGridActions WithInfiniteScroll { get; }
Property Value
WithJavaScript
Specifies to execute javascript on the page to interact with the Selector just defined with .WithSelector. Use this to override what is defined on the Selector.
This is different than Selenium interaction.
Selenium is the default method to interact with elements, but sometimes that doesn't work as expected.
You can also specify to use hardware emulation to interact with elements.
Declaration
public IAllowAfterAnySelector WithJavaScript { get; }
Property Value
Methods
AppendFrom(GPALDatabase)
Append data from the database to the end of any input Selectors defined in the UOW
One token (one column in the current row) per input. Inputs are filled by tokens in the order they are both declared.
If .WithAllThatMatch is defined on the current UOW, then the token is entered into {num} inputs that matches the corresponding Selector in the current UOW.
If CallAfterFillIn callback is defined, it will be called after each row is consumed and the text is input.
Declaration
public IAllowBrowserActionOrAnySelector AppendFrom(GPALDatabase inputDatabase)
Parameters
| Type |
Name |
Description |
| GPALDatabase |
inputDatabase |
The GPAL Database definitoin
|
Returns
AppendFrom(IGPALFile)
Append the data from the input file to the end of any input Selectors defined in the UOW
One token (one string [between commas] from the current row) per input. Inputs are filled by tokens in the order they are both declared.
If .WithAllThatMatch is defined on the current UOW, then the token is entered into {num} inputs that matches the corresponding Selector in the current UOW.
If CallAfterFillIn callback is defined, it will be called after each row is consumed and the text is input.
Declaration
public IAllowBrowserActionOrAnySelector AppendFrom(IGPALFile inputFile)
Parameters
| Type |
Name |
Description |
| IGPALFile |
inputFile |
The GPAL File definition
|
Returns
AppendFrom(IGPALGrid<String>)
Append the data from the input grid to the end of any input Selectors defined in the UOW
One token (one string from the current row) per input. Inputs are filled by tokens in the order they are both declared.
If .WithAllThatMatch is defined on the current UOW, then this token is entered into {num} inputs that matches the corresponding Selector in the current UOW.
If CallAfterFillIn callback is defined, it will be called after each row is consumed and the text is input.
Declaration
public IAllowBrowserActionOrAnySelector AppendFrom(IGPALGrid<string> inputGrid)
Parameters
| Type |
Name |
Description |
| IGPALGrid<System.String> |
inputGrid |
The input grid of tokens
|
Returns
AppendFrom(String)
Append the given text to the first input in the UOW. Should probably only be used with one selector at a time.
If .WithAllThatMatch is defined on the current UOW, then this text is entered into {num} inputs that matches the Selector(s) in the current UOW.
Declaration
public IAllowBrowserActionOrAnySelector AppendFrom(string text)
Parameters
| Type |
Name |
Description |
| System.String |
text |
|
Returns
AppendToCSV(IGPALFile)
Append as CSV text the current UOW return grid to the file specified.
Can be used directly after declaring Selectors for a UOW, or you can generate your own GPALGrid<string%gt; and save those results by using .WithGridToSave
Declaration
public IAllowBrowserActionOrAnySelector AppendToCSV(IGPALFile gPALFile)
Parameters
Returns
Examples
...
.WithSelector(descriptionColumn)
.WithSelector(priceColumn)
.WithSelector(linkColumn)
.WithSelector(imageColumn)
.WithAllThatMatch()
.WithNextPageButton(nextPageButton)
.WithPages(3) // get three pages of results
.AppendToCSV(@"c:\ebay.retrieved.columns.csv"); // save to file
AppendToExcel(IGPALFile)
TODO: Implement
Append to an Excel spreadsheet [fisrt tab] current UOW return grid to the file specified.
Can be used directly after declaring Selectors for a UOW, or you can generate your own GPALGrid<string%gt; and save those results by using .WithGridToSave
Declaration
public IAllowBrowserActionOrAnySelector AppendToExcel(IGPALFile filename)
Parameters
| Type |
Name |
Description |
| IGPALFile |
filename |
[Path]Name of file to save
|
Returns
Examples
...
.WithSelector(descriptionColumn)
.WithSelector(priceColumn)
.WithSelector(linkColumn)
.WithSelector(imageColumn)
.WithAllThatMatch()
.WithNextPageButton(nextPageButton)
.WithPages(3) // get three pages of results
.AppendToExcel(@"c:\ebay.retrieved.columns.xlsx"); // save to file
AppendToFile(IGPALFile)
Append as text (no separators) the current UOW return grid to the file specified.
Can be used directly after declaring Selectors for a UOW, or you can generate your own GPALGrid<string%gt; and save those results by using .WithGridToSave
Declaration
public IAllowBrowserActionOrAnySelector AppendToFile(IGPALFile gPALFile)
Parameters
| Type |
Name |
Description |
| IGPALFile |
gPALFile |
[Path]Name of file to save
|
Returns
Examples
...
.WithSelector(descriptionColumn)
.WithAllThatMatch()
.WithNextPageButton(nextPageButton)
.WithPages(3) // get three pages of results
.AppendToFile(@"c:\description.column.txt"); // save to file
AppendToTabbedText(IGPALFile)
Append as tab delimited text the current UOW return grid to the file specified.
Can be used directly after declaring Selectors for a UOW, or you can generate your own GPALGrid<string%gt; and save those results by using .WithGridToSave
Declaration
public IAllowBrowserActionOrAnySelector AppendToTabbedText(IGPALFile gPALFile)
Parameters
Returns
Examples
...
.WithSelector(descriptionColumn)
.WithSelector(priceColumn)
.WithSelector(linkColumn)
.WithSelector(imageColumn)
.WithAllThatMatch()
.WithNextPageButton(nextPageButton)
.WithPages(3) // get three pages of results
.AppendToCSV(@"c:\ebay.retrieved.columns.txt"); // save to file
CallAfterFillIn(Browser.CallAfterFillInDelegate)
Add a handler to call after a row of tokens is consumed and after all inputs are filled in with data.
Only one CallAfterFillIn handler exists.
Use FillInFrom[Database|File|GPALGrid] to loop thru data in your main workflow and then perform next workflow steps in the CallAfter handler.
Declaration
public IAllowAfterAnySelector CallAfterFillIn(Browser.CallAfterFillInDelegate callAfterFillIn)
Parameters
Returns
CallIfFound(Browser.CallIfDelegate)
Add a Unit of Work level CallIfFound handler to be called if any defined selectors find/match elements.
This method will be called for every found selector in the current UOW.
CallIf handlers can remove themselves by calling myBrowser.RemoveCallIfHandlerEverywhere(handler)
Selectors may remove themselves from a UOW by using selector.Remove()
More than one callback may be defined and will cascade thru the list depending upon the callback return value.
See: CallIfDelegate
Declaration
public IAllowAfterAnySelector CallIfFound(Browser.CallIfDelegate callIfFoundDelegate)
Parameters
Returns
CallIfNotFound(Browser.CallIfDelegate)
Add a Unit of Work level CallIfNotFound handler to be called if any defined selectors DO NOT find/match elements.
This method will be called for every NOT FOUND selector in the current UOW.
CallIf handlers can remove themselve by calling myBrowser.RemoveCallIfHandlerEverywhere(handler)
Selectors may remove themselves from a UOW by using selector.Remove()
More than one callback may be defined and will cascade thru the list depending upon the callback return value.
See: CallIfDelegate
Declaration
public IAllowAfterAnySelector CallIfNotFound(Browser.CallIfDelegate callIfNotFound)
Parameters
Returns
Close(Boolean)
Close/terminate the browser.
This terminates the fluent interface and nothing can be chained to this command.
NOTE: If you are ending your application, pass in true to kill all running web drivers [windows will be left open].
Declaration
public void Close(bool killWebDrivers = false)
Parameters
| Type |
Name |
Description |
| System.Boolean |
killWebDrivers |
True to kill all web drivers
False [default] to only close the browser.
|
CloseTab(String)
Close the current in focus, active tab.
Declaration
public IAllowBrowserActionOrAnySelector CloseTab(string URLorTabId = null)
Parameters
| Type |
Name |
Description |
| System.String |
URLorTabId |
|
Returns
DragAndDrop(Enums.ModifierKeys)
Left click the element found for Selector(s) defined in the UOW
One left click for the first element found for each selector.
If .WithAllThatMatch is defined on the current UOW, then a left click is performed on {num} elements that matches the corresponding Selector in the current UOW.
Declaration
public IAllowBrowserActionOrAnySelector DragAndDrop(Enums.ModifierKeys modifierKeys = Enums.ModifierKeys.None)
Parameters
Returns
DragAndDrop(Selector)
Declaration
public IAllowBrowserActionOrAnySelector DragAndDrop(Selector selector = null)
Parameters
Returns
ExecuteJavaScriptObj(String)
Declaration
public IAllowBrowserActionOrAnySelector ExecuteJavaScriptObj(string javascript)
Parameters
| Type |
Name |
Description |
| System.String |
javascript |
|
Returns
ExecuteJavaScriptStr(String)
Declaration
public IAllowBrowserActionOrAnySelector ExecuteJavaScriptStr(string javascript)
Parameters
| Type |
Name |
Description |
| System.String |
javascript |
|
Returns
FillInFrom(GPALDatabase)
FillIn data from the database overwriting text in the input Selector(s) defined in the UOW
One token (one column in the current row) per input/element found. Inputs are filled by tokens in the order they are both declared.
If .WithAllThatMatch is defined on the current UOW, then the token is entered into {num} inputs that matches the corresponding Selector in the current UOW.
If CallAfterFillIn callback is defined, it will be called after each row is consumed and the text is input.
Declaration
public IAllowBrowserActionOrAnySelector FillInFrom(GPALDatabase inputDatabase)
Parameters
| Type |
Name |
Description |
| GPALDatabase |
inputDatabase |
The GPAL Database definitoin
|
Returns
FillInFrom(IGPALFile)
FillIn data from the file overwriting text in the input Selector(s) defined in the UOW
One token (one string [between commas] from the current row) per input. Inputs are filled by tokens in the order they are both declared.
If .WithAllThatMatch is defined on the current UOW, then the token is entered into {num} inputs that matches the corresponding Selector in the current UOW.
If CallAfterFillIn callback is defined, it will be called after each row is consumed and the text is input.
Declaration
public IAllowBrowserActionOrAnySelector FillInFrom(IGPALFile inputFile)
Parameters
| Type |
Name |
Description |
| IGPALFile |
inputFile |
The GPAL File definition
|
Returns
FillInFrom(IGPALGrid<String>)
FillIn data from the grid overwriting text in the input Selector(s) defined in the UOW
One token (one string from the current row) per input. Inputs are filled by tokens in the order they are both declared.
If .WithAllThatMatch is defined on the current UOW, then this token is entered into {num} inputs that matches the corresponding Selector in the current UOW.
If CallAfterFillIn callback is defined, it will be called after each row is consumed and the text is input.
Declaration
public IAllowBrowserActionOrAnySelector FillInFrom(IGPALGrid<string> inputGrid)
Parameters
| Type |
Name |
Description |
| IGPALGrid<System.String> |
inputGrid |
The input grid of tokens
|
Returns
FillInFrom(String)
Overwrite all text in the first input in the UOW. Should probably only be used with one selector at a time.
If .WithAllThatMatch is defined on the current UOW, then this text is entered into {num} inputs that matches the Selector(s) in the current UOW.
Declaration
public IAllowBrowserActionOrAnySelector FillInFrom(string text)
Parameters
| Type |
Name |
Description |
| System.String |
text |
|
Returns
Focus(Selector)
Focus the current element found via the Selector. Only the first element per Selector found will be focused.
IF using hardwre emulation (.WithHardware) for this selector, for text inputs, focus is a click in the control. Otherwise, hardware emulation hovers the mouse over the control.
If .WithAllThatMatch is defined on the current UOW, then focus will interate over {num} elements that matches the Selector(s) in the current UOW.
Declaration
public IAllowBrowserActionOrAnySelector Focus(Selector selector)
Parameters
Returns
Get(String)
Navigate to the URL specified in headless mode.
If no headless browser is open, one will be launched.
If using an already open browser, navigate in the current tab.
Use .WithNewTab before .Get to navigate on a new tab.
Declaration
public IAllowBrowserActionOrAnySelector Get(string URL)
Parameters
| Type |
Name |
Description |
| System.String |
URL |
|
Returns
GetGrid(out IGPALGrid<String>)
Retrieve the current UOW selectors data into a <string%gt; of columns and rows to use with GPAL or however you want.
using GenerallyPositive.Common;
Declaration
public IAllowWithHeaderOrFileActions GetGrid(out IGPALGrid<string> returnGrid)
Parameters
| Type |
Name |
Description |
| IGPALGrid<System.String> |
returnGrid |
Output GPALGrid
|
Returns
Examples
...
.WithSelector(descriptionColumn)
.WithSelector(priceColumn)
.WithSelector(linkColumn)
.WithSelector(imageColumn)
.WithAllThatMatch()
.WithNextPageButton(nextPageButton)
.WithPages(3) // get three pages of results
.GetGrid(out retGrid); // get grid for us
myBrowser
.WithGridToSave(retGrid)
.WithHeader("Description")
.WithHeader("Price")
.WithHeader("Link")
.WithHeader("Image URL")
.SaveToTabbedText(@"c:\ebay.retrieved.columns.txt"); // save to file
GoTo(String)
Navigate to the URL specified.
If no browser is open, one will be launched.
If using an already open browser, navigate in the current tab.
Use .WithNewTab before .GoTo to navigate on a new tab.
Declaration
public IAllowBrowserActionOrAnySelector GoTo(string URL)
Parameters
| Type |
Name |
Description |
| System.String |
URL |
|
Returns
GoToTab(Object)
Goto the tab with the specified URL
If using OttoMagic, you can use the tabid from browser.BrowserSettings.TabIds[tabid] search for matching URL
Declaration
public IAllowBrowserActionOrAnySelector GoToTab(dynamic URLorTabId = null)
Parameters
| Type |
Name |
Description |
| System.Object |
URLorTabId |
|
Returns
Hover(Selector)
Hover the mouse over the current element found via the Selector. Only the first element per Selector found will be focused.
Using UIAutomation, setFocus is first called on the item, then the mouse moved to hover over the element.
IF using hardwre emulation (.WithHardware) for this selector, for text inputs, focus is a click in the control. Otherwise, hardware emulation hovers the mouse over the control.
If .WithAllThatMatch is defined on the current UOW, then focus will interate over {num} elements that matches the Selector(s) in the current UOW.
Declaration
public IAllowBrowserActionOrAnySelector Hover(Selector selector = null)
Parameters
Returns
InIFrame(Selector)
Specify that the following .WithSelector(s) are contained in an iFrame specified by the Selector.
Use .InMainDom() to get back to working with the main document.
Declaration
public IAllowAfterAnySelector InIFrame(Selector iFrameSelector)
Parameters
| Type |
Name |
Description |
| Selector |
iFrameSelector |
iFrame element Selector
|
Returns
Examples
static Selector captchaIframe = (Selector)GPAL.Selector
.WithCSS(@"#s0-69-captcha-ui > iframe");
static Selector captchaCheck = (Selector)GPAL.Selector
.WithXPath(@"//*[@id=""checkbox""]")
.WithHardware;
Browser myBrowser = (Browser)GPAL.Browser
.WithBrowserType(BrowserType.FireFox)
.WithDriverLocation(@"c:\drivers")
.WithWaitOnDocumentReady(true)
.GoTo(@"https://www.ebay.com/splashui/captcha")
.InIFrame(captchaIframe)
.WithSelector(captchaCheck)
.LeftClick();
InMainDom()
Specify that GPAL is no longer working in an iFram or shadow dom and reset back to the main document.
Declaration
public IAllowAfterAnySelector InMainDom()
Returns
InParallelIframe(Selector)
Declaration
public IAllowAfterAnySelector InParallelIframe(Selector iFrameSelector)
Parameters
| Type |
Name |
Description |
| Selector |
iFrameSelector |
|
Returns
InParallelShadowDom(Selector)
Declaration
public IAllowAfterAnySelector InParallelShadowDom(Selector shadowDomSelector)
Parameters
| Type |
Name |
Description |
| Selector |
shadowDomSelector |
|
Returns
InsertFrom(GPALDatabase)
Insert the text from the database at the beginning of the input Selector(s) defined in the UOW
One token (one column in the current row) per input/element found. Inputs are filled by tokens in the order they are both declared.
If .WithAllThatMatch is defined on the current UOW, then the token is entered into {num} inputs that matches the corresponding Selector in the current UOW.
If CallAfterFillIn callback is defined, it will be called after each row is consumed and the text is input.
Declaration
public IAllowBrowserActionOrAnySelector InsertFrom(GPALDatabase inputDatabase)
Parameters
| Type |
Name |
Description |
| GPALDatabase |
inputDatabase |
The GPAL Database definitoin
|
Returns
InsertFrom(IGPALFile)
Insert the data from the file at the beginning of the text in the input Selector(s) defined in the UOW
One token (one string [between commas] from the current row) per input. Inputs are filled by tokens in the order they are both declared.
If .WithAllThatMatch is defined on the current UOW, then the token is entered into {num} inputs that matches the corresponding Selector in the current UOW.
If CallAfterFillIn callback is defined, it will be called after each row is consumed and the text is input.
Declaration
public IAllowBrowserActionOrAnySelector InsertFrom(IGPALFile inputFile)
Parameters
| Type |
Name |
Description |
| IGPALFile |
inputFile |
The GPAL File definition
|
Returns
InsertFrom(IGPALGrid<String>)
Insert the data from the grid at the beginning of the text in the input Selector(s) defined in the UOW
One token (one string from the current row) per input. Inputs are filled by tokens in the order they are both declared.
If .WithAllThatMatch is defined on the current UOW, then this token is entered into {num} inputs that matches the corresponding Selector in the current UOW.
If CallAfterFillIn callback is defined, it will be called after each row is consumed and the text is input.
Declaration
public IAllowBrowserActionOrAnySelector InsertFrom(IGPALGrid<string> inputGrid)
Parameters
| Type |
Name |
Description |
| IGPALGrid<System.String> |
inputGrid |
The input grid of tokens
|
Returns
InsertFrom(String)
Insert text at the beginning of the first input in the UOW. Should probably only be used with one selector at a time.
Example: If three inputs are defined and three 'InsertFrom' are defined, then the text is assigned to the same ordinal input element found via the Selector(s)
If .WithAllThatMatch is defined on the current UOW, then this text is entered into {num} inputs that matches the corresponding Selector(s) in the current UOW.
Declaration
public IAllowBrowserActionOrAnySelector InsertFrom(string textToUse)
Parameters
| Type |
Name |
Description |
| System.String |
textToUse |
The input text to use
|
Returns
InShadowDom(Selector)
Specify that the following .WithSelectors are contained in an a shadow dom specified by the Selector.
Use .InMainDom() to get back to working with the main document.
NOTE: can only use CSS selectors in shadow dom
Declaration
public IAllowAfterAnySelector InShadowDom(Selector shadowDomSelector)
Parameters
| Type |
Name |
Description |
| Selector |
shadowDomSelector |
Shadow dom element Selector
|
Returns
Examples
static Selector shadowRoot = (Selector)GPAL.Selector
.WithXPath(@"/html/body/article/p[3]")
.WithHardware
.WithSimulateMouse(true);
static Selector shadowSpan = (Selector)GPAL.Selector
.WithCSS(@"span")
.WithHardware
.WithSimulateMouse(true);
Browser myBrowser = (Browser)GPAL.Browser
.WithBrowserType(BrowserType.Chrome)
.WithDriverLocation(@"c:\drivers")
.WithWaitOnDocumentReady(true)
.GoTo(@"https://mdn.github.io/web-components-examples/word-count-web-component/")
.InShadowDom(shadowRoot)
.WithSelector(shadowSpan)
.Hover()
.WaitFor(5000);
LeftClick(Enums.ModifierKeys)
Left click the element found for Selector(s) defined in the UOW
One left click for the first element found for each selector.
If .WithAllThatMatch is defined on the current UOW, then a left click is performed on {num} elements that matches the corresponding Selector in the current UOW.
Declaration
public IAllowBrowserActionOrAnySelector LeftClick(Enums.ModifierKeys modifierKeys = Enums.ModifierKeys.None)
Parameters
Returns
LeftClick(Selector)
Left click the element found for Selector parameter, creates a UOW of 1 element
One left click w/ no modiofiers pressed for the element found for the selector.
If .WithAllThatMatch is defined on the current UOW, then a left click is performed on {num} elements that matches the corresponding Selector in the current UOW.
Declaration
public IAllowBrowserActionOrAnySelector LeftClick(Selector selector)
Parameters
Returns
LeftClickAndDownload(IGPALFile)
Left click the element found for Selector(s) defined in the UOW, wait for the SAVE AS dialog, enter the filename and save the file.
The saved filename is then added to the end of the filename list.
Useful if files are not overwritten.
One left click for the first element found for each selector. Should probably be used with only one Selector in the UOW.
If .WithAllThatMatch is defined on the current UOW, then a left click is performed on {num} elements that matches the corresponding Selector in the current UOW.
Declaration
public IAllowBrowserActionOrAnySelector LeftClickAndDownload(IGPALFile gPalFile)
Parameters
Returns
LeftDoubleClick()
Left double click the element found for Selector(s) defined in the UOW
One left click for the first element found for each selector. Should probably be used with only one Selector in the UOW.
If .WithAllThatMatch is defined on the current UOW, then a left click is performed on {num} elements that matches the corresponding Selector in the current UOW.
Declaration
public IAllowBrowserActionOrAnySelector LeftDoubleClick()
Returns
MoveTo(Selector)
Move the mouse to the current element found via the Selector. Only the first element per Selector found will be 'moved to'.
IF using hardwre emulation (.WithHardware) for this selector, the mouse is moved to hover over the control.
If .WithAllThatMatch is defined on the current UOW, then MoveTo will move the mouse over {num} elements that matches the Selector(s) in the current UOW.
How and where on the page an element is moved to differs depending upon the technique: Hardware, JavaScript, Selenium
Declaration
public IAllowBrowserActionOrAnySelector MoveTo(Selector selector = null)
Parameters
Returns
NextTab()
Navigate to the next tab. If at the last tab nothing will happen.
NOTE: New window is just another tab. So, if a window is opened, should be able to still use .NextTab
Declaration
public IAllowBrowserActionOrAnySelector NextTab()
Returns
PersistentCallIfFound(Browser.CallIfDelegate)
Add a persistent CallIfFound handler to be called if any defined persistent selectors find/match elements.
Persistent selectors are always looked for before every action cross-cutting your workflow.
Persistent handlers can remove themselves in the CallIfHandler by calling myApplication.RemoveCallIfHandlerEverywhere(handler)
More than one callback may be defined and will cascade thru the list depending upon the callback return value.
See: CallIfDelegate
Declaration
public IAllowBrowserSettingsOrGoTo PersistentCallIfFound(Browser.CallIfDelegate persistentCallIfFound)
Parameters
Returns
PersistentCallIfNotFound(Browser.CallIfDelegate)
Add a persistent CallIfNotFound handler to be called if any defined persistent selectors DO NOT find/match elements.
Persistent selectors are always looked for before every action cross-cutting your workflow.
Persistent handlers can remove themselves in the CallIfHandler by calling myApplication.RemoveCallIfHandlerEverywhere(handler)
More than one callback may be defined and will cascade thru the list depending upon the callback return value.
See: CallIfDelegate
Declaration
public IAllowBrowserSettingsOrGoTo PersistentCallIfNotFound(Browser.CallIfDelegate persistentCallIfNotFound)
Parameters
Returns
PressModifierKey(Enums.ModifierKeys)
Press the specified modifer keys (can be ORd)
NOTE: If you SendString a mixed case string, the SHIFT key will be released if it is pressed.
Declaration
public IAllowBrowserActionOrAnySelector PressModifierKey(Enums.ModifierKeys modifierKeys)
Parameters
| Type |
Name |
Description |
| Enums.ModifierKeys |
modifierKeys |
Enumeration ModifierKeys, can be ORd togther
|
Returns
Examples
// send CTRL-HOME
...
myBrowser
.PressModifierKey(ModifierKeys.Control)
.SendKey(GPAL.VK_HOME);
.WaitFor(150)
.ReleaseModifierKey(ModifierKeys.Control)
PreviousTab()
Navigate to the previous tab. If at the first tab nothing will happen.
Declaration
public IAllowBrowserActionOrAnySelector PreviousTab()
Returns
PrintToPDF(IGPALFile)
Declaration
public IAllowAfterWaitForAndSizeControl PrintToPDF(IGPALFile gpalFile)
Parameters
Returns
ReleaseModifierKey(Enums.ModifierKeys)
Release the specified modifer keys (can be ORd)
NOTE: If you SendString a mixed case string, the SHIFT key will be released if it is pressed.
Declaration
public IAllowBrowserActionOrAnySelector ReleaseModifierKey(Enums.ModifierKeys modifierKeys)
Parameters
| Type |
Name |
Description |
| Enums.ModifierKeys |
modifierKeys |
Enumeration ModifierKeys, can be ORd togther
|
Returns
Examples
// send CTRL-HOME
...
myBrowser
.PressModifierKey(ModifierKeys.Control)
.SendKey(GPAL.VK_HOME);
.WaitFor(150)
.ReleaseModifierKey(ModifierKeys.Control)
RemoveCallIfHandlerEverywhere(Browser.CallIfDelegate)
Helper method for GPAL applications to remove a handler from all UOWs. Envisioned to be used in a persistent handler, but can be used anyway imagined. This is not fluent.
Declaration
public void RemoveCallIfHandlerEverywhere(Browser.CallIfDelegate func)
Parameters
Examples
public static int FoundAllCookies(Browser browser, List<GPALElement> foundElements, List<GPALElement> matchedElements, Selector selector)
{
int retVal = 0;
foreach (GPALElement webElement in foundElements)
{
if (true == webElement.Text.ToLower().Contains("accept")) // "Accept all cookies"
{
webElement.Click();
selector.Browser.RemoveCallIfHandlerEverywhere(FoundAllCookies);
selector.Remove();
retVal = 1;
}
}
return retVal;
}
ReturnToIframe(Selector)
Declaration
public IAllowAfterAnySelector ReturnToIframe(Selector iFrameSelector)
Parameters
| Type |
Name |
Description |
| Selector |
iFrameSelector |
|
Returns
ReturnToShadowDom(Selector)
Declaration
public IAllowAfterAnySelector ReturnToShadowDom(Selector shadowDomSelector)
Parameters
| Type |
Name |
Description |
| Selector |
shadowDomSelector |
|
Returns
RightClick(Selector)
Right click the element found for Selector(s) defined in the UOW
One right click for the first element found for each selector. Should probably be used with only one Selector in the UOW.
If .WithAllThatMatch is defined on the current UOW, then a left click is performed on {num} elements that matches the corresponding Selector in the current UOW.
Declaration
public IAllowBrowserActionOrAnySelector RightClick(Selector selector = null)
Parameters
Returns
RightClickAndDownload(IGPALFile)
Right click the element(s) found for Selector(s) defined in the UOW, select 'Save as...', wait for the SAVE AS dialog, enter the filename and save the file.
The saved filename is then added to the end of the filename list.
Useful if files are not overwritten.
One right click for the first element found for each selector. Should probably be used with only one Selector in the UOW.
If .WithAllThatMatch is defined on the current UOW, then a right click is performed on {num} elements that matches the corresponding Selector in the current UOW.
Declaration
public IAllowBrowserActionOrAnySelector RightClickAndDownload(IGPALFile gPalFiles)
Parameters
Returns
RightClickAndPrintToPDF(String)
Declaration
public IAllowBrowserActionOrAnySelector RightClickAndPrintToPDF(string filename)
Parameters
| Type |
Name |
Description |
| System.String |
filename |
|
Returns
Run(Int32)
Declaration
public IAllowBrowserActionOrAnySelector Run(int maxParallel = 1)
Parameters
| Type |
Name |
Description |
| System.Int32 |
maxParallel |
|
Returns
SaveToCSV(IGPALFile)
Save as CSV text the current UOW return grid to the file specified.
Can be used directly after declaring Selectors for a UOW, or you can generate your own GPALGrid<string%gt; and save those results by using .WithGridToSave
Declaration
public IAllowBrowserActionOrAnySelector SaveToCSV(IGPALFile gPALFile)
Parameters
Returns
Examples
...
.WithSelector(descriptionColumn)
.WithSelector(priceColumn)
.WithSelector(linkColumn)
.WithSelector(imageColumn)
.WithAllThatMatch()
.WithNextPageButton(nextPageButton)
.WithPages(3) // get three pages of results
.WithHeader("Description")
.WithHeader("Price")
.WithHeader("Link")
.WithHeader("Image URL")
.SaveToCSV(@"c:\ebay.retrieved.columns.csv"); // save to file
SaveToExcel(IGPALFile)
TODO: Implement
Save to an Excel spreadsheet [firt tab] current UOW return grid to the file specified.
Can be used directly after declaring Selectors for a UOW, or you can generate your own GPALGrid<string%gt; and save those results by using .WithGridToSave
Declaration
public IAllowBrowserActionOrAnySelector SaveToExcel(IGPALFile filename)
Parameters
| Type |
Name |
Description |
| IGPALFile |
filename |
[Path]Name of file to save
|
Returns
Examples
...
.WithSelector(descriptionColumn)
.WithSelector(priceColumn)
.WithSelector(linkColumn)
.WithSelector(imageColumn)
.WithAllThatMatch()
.WithNextPageButton(nextPageButton)
.WithPages(3) // get three pages of results
.AppendToExcel(@"c:\ebay.retrieved.columns.xlsx"); // save to file
SaveToFile(IGPALFile)
Save as text (using the separator defined for file) the current UOW return grid to the file specified.
Can be used directly after declaring Selectors for a UOW, or you can generate your own GPALGrid<string%gt; and save those results by using .WithGridToSave
Declaration
public IAllowBrowserActionOrAnySelector SaveToFile(IGPALFile gPALFile)
Parameters
Returns
Examples
File saveFile = GPAL.File.WithFileName("saveFile.txt").WithColumn("Name").WithColumn("Description").WithColumn("Price").WithDelimiter("^").ToGPALObject();
...
.WithSelector(nameColumn)
.WithSelector(descriptionColumn)
.WithSelector(priceColumn)
.WithAllThatMatch()
.WithNextPageButton(nextPageButton)
.WithPages(3) // get three pages of results
.SaveToFile(saveFile);
SaveToTabbedText(IGPALFile)
Save as tab delimited text the current UOW return grid to the file specified.
Can be used directly after declaring Selectors for a UOW, or you can generate your own GPALGrid<string%gt; and save those results by using .WithGridToSave
Declaration
public IAllowBrowserActionOrAnySelector SaveToTabbedText(IGPALFile gPalFile)
Parameters
Returns
Examples
...
.WithSelector(descriptionColumn)
.WithSelector(priceColumn)
.WithSelector(linkColumn)
.WithSelector(imageColumn)
.WithAllThatMatch()
.WithNextPageButton(nextPageButton)
.WithPages(3) // get three pages of results
.WithHeader("Description")
.WithHeader("Price")
.WithHeader("Link")
.WithHeader("Image URL")
.SaveToTabbedText(@"c:\ebay.retrieved.columns.txt"); // save to file
Scroll the element horizontally by number of pixels.
Negative numbers scroll left. JavaScript only
Declaration
public IAllowBrowserActionOrAnySelector ScrollHorizontalByPixels(int scrollAmount)
Parameters
| Type |
Name |
Description |
| System.Int32 |
scrollAmount |
Positive integer scrolls right.
Negative integer scolls left.
|
Returns
Scroll the element vertically by number of pixels.
Negative numbers scroll up. JavaScript only
Declaration
public IAllowBrowserActionOrAnySelector ScrollVerticalByPixels(int scrollAmount)
Parameters
| Type |
Name |
Description |
| System.Int32 |
scrollAmount |
Positive integer scrolls down.
Negative integer scolls down.
|
Returns
Scroll the browser window horizontally the number of pixels.
Negative numbers scroll left. JavaScript only
Declaration
public IAllowBrowserActionOrAnySelector ScrollWindowByHorizontal(int scrollAmountInPixels)
Parameters
| Type |
Name |
Description |
| System.Int32 |
scrollAmountInPixels |
|
Returns
Scroll the browser window horizontally the number of pixels.
Negative numbers scroll up. JavaScript only
Declaration
public IAllowBrowserActionOrAnySelector ScrollWindowByVertical(int scrollAmountInPixels)
Parameters
| Type |
Name |
Description |
| System.Int32 |
scrollAmountInPixels |
|
Returns
SelectClick(Enums.SelectClickType)
Declaration
public IAllowBrowserActionOrAnySelector SelectClick(Enums.SelectClickType selectClickType)
Parameters
Returns
SendKey(Byte)
Declaration
public IAllowBrowserActionOrAnySelector SendKey(byte VKCode)
Parameters
| Type |
Name |
Description |
| System.Byte |
VKCode |
Virtual Keycode
|
Returns
Examples
// send CTRL-HOME
...
myBrowser
.PressModifierKey(ModifierKeys.Control)
.SendKey(GPAL.VK_HOME);
.WaitFor(150)
.ReleaseModifierKey(ModifierKeys.Control)
SendString(String)
Type in the literal string provided.
NOTE: If you press SHIFT then SendString a mixed-case string, SHIFT will be released.
To send ALL CAPS, press SHIFT then send an all lowercase string.
Declaration
public IAllowBrowserActionOrAnySelector SendString(string textToSend)
Parameters
| Type |
Name |
Description |
| System.String |
textToSend |
Text to type
|
Returns
StartWorkflow()
Start a workflow to invoke CallIf handlers (if no other action is being used in the workflow)
A LeftClick, Hover, GetGrid, SaveTo. FillIn and other actions will all start the workflow.
Sometimes your Unit of Work (UOW) consists of finding one repeating element, then chaining to a CallIfFound handler.
StartWorkflow will kick off looking for your UOW selectors.
NOTE: Only call this if you have not called another action. Any prior action will start the workflow and this will be ignored if used.
But if you have not called an action, you can use .StartWorkflow to kick off the workflow which will invoke your CallIf handlers.
Declaration
public IAllowBrowserActionOrAnySelector StartWorkflow()
Returns
StealthLeftClick(Selector)
Stealth (Runtime.disable before) Left click the element found for Selector parameter, creates a UOW of 1 element
One left click w/ no modiofiers pressed for the element found for the selector.
If .WithAllThatMatch is defined on the current UOW, then a left click is performed on {num} elements that matches the corresponding Selector in the current UOW.
Declaration
public IAllowBrowserActionOrAnySelector StealthLeftClick(Selector selector)
Parameters
Returns
ToGPALObject()
Return a GPAL.Browser object so that GPAL.Browser does not have to be cast.
Declaration
public IBrowser ToGPALObject()
Returns
| Type |
Description |
| IBrowser |
A GPAL.Browser object
|
Examples
Browser browser = GPAL.Browser
.WithBrowserType(BrowserType.FireFox)
.WithWaitOnDocumentReady(true)
.WithLoadImages(true)
.WithOverwriteExistingFile(false)
.GoTo("https://www.ebay.com/")
.ToGPALObject();
TryDecodeNumberToIpAddress(String, out String)
Declaration
public bool TryDecodeNumberToIpAddress(string number, out string ipAddress)
Parameters
| Type |
Name |
Description |
| System.String |
number |
|
| System.String |
ipAddress |
|
Returns
| Type |
Description |
| System.Boolean |
|
Until(Selector)
Declaration
public IAllowBrowserActionOrAnySelector Until(Selector selector)
Parameters
Returns
Until(Func<Browser, Boolean>)
Declaration
public IAllowBrowserActionOrAnySelector Until(Func<Browser, bool> predicate)
Parameters
| Type |
Name |
Description |
| System.Func<Browser, System.Boolean> |
predicate |
|
Returns
WaitFor(Selector)
Declaration
public IAllowAfterWaitFor WaitFor(Selector waitForSelector)
Parameters
| Type |
Name |
Description |
| Selector |
waitForSelector |
|
Returns
WaitFor(Int32)
Either wait the amount of time specified or wait UP TO the amount of time specified waiting for elements to be found for the Selector(s) in the current UOW.
If an action has already been called, then this is interpretted as a sleep for the specified miliseconds.
If only selectors have been defined in the current UOW, then this is a delay waiting for the selectors to be present before continuing with the workflow.
Waiting for elements does not guarantee they will be present when the workflow continues. If they are not present, the CallIfNotFound handler will be invoked so you can deal with that.
NOTE: WaitFor is not considered an action, if defines a time to wait for elements to be present before trying to perform actions.
Declaration
public IAllowAfterWaitFor WaitFor(int waitForTimeInTicks)
Parameters
| Type |
Name |
Description |
| System.Int32 |
waitForTimeInTicks |
|
Returns
WaitForWindow(String)
Wait for a Windows window with title to appear on the desktop.
Used in conjunction with .WithWaitForWindowTimeout to set the wait duration in seconds.
Declaration
public IAllowAfterWaitForAndSizeControl WaitForWindow(string waitForTitle)
Parameters
| Type |
Name |
Description |
| System.String |
waitForTitle |
|
Returns
WaitForWindowRegex(String)
Wait for a Windows window with title that matches the regex pattern to appear on the desktop.
Used in conjunction with .WithWaitForWindowTimeout to set the wait duration in seconds.
Declaration
public IAllowAfterWaitForAndSizeControl WaitForWindowRegex(string waitForTitleRegex)
Parameters
| Type |
Name |
Description |
| System.String |
waitForTitleRegex |
|
Returns
While(Func<Browser, Boolean>)
Declaration
public IAllowBrowserActionOrAnySelector While(Func<Browser, bool> predicate)
Parameters
| Type |
Name |
Description |
| System.Func<Browser, System.Boolean> |
predicate |
|
Returns
WhileLoopMaxIterations(Int32)
Declaration
public IAllowWorkflowExecution WhileLoopMaxIterations(int maxIterations)
Parameters
| Type |
Name |
Description |
| System.Int32 |
maxIterations |
|
Returns
WhileLoopTimeout(Int32)
Declaration
public IAllowWorkflowExecution WhileLoopTimeout(int timeoutMs)
Parameters
| Type |
Name |
Description |
| System.Int32 |
timeoutMs |
|
Returns
WithAllThatMatch(Int32)
Indicates the Selectors refer to/match repeating, multiple elements on the page.
Use after all your .WithSelector statements. Used two ways.
For scraping: This is used to retrieve multiple rows of data from the webpage, up to rowCount.
For input tokens/strings: This will repeat the same input into multiple elements, up to rowCount of lines.
Declaration
public IAllowAfterAnySelectorExceptWithAll WithAllThatMatch(int rowCount = -1)
Parameters
| Type |
Name |
Description |
| System.Int32 |
rowCount |
Set total number of entries to retrieve (if this is longer than a page size).
If less than the page size, retrieve the 'top rowCount' rows on each page for the number of pages specified using .WithPages(pageCount)
|
Returns
Specifies whether to block popups in the browser.
Declaration
public IAllowBrowserSettingsOrGoTo WithBlockPopUps(bool blockPopUp)
Parameters
| Type |
Name |
Description |
| System.Boolean |
blockPopUp |
True [default] to block popups.
False allows popups.
|
Returns
Browser myBrowser = (Browser)GPAL.Browser
.WithBrowserType(BrowserType.Chrome)
.WithDriverLocation(@"c:\drivers")
.WithBlockPopUps(false)
.GoTo("https://www.ebay.com/")
WithBrowserType(Enums.BrowserType)
Specify which browser to run the workflow in.
NOTE: Chrome and Edge act mostly the same, Firefox has some behavioral differences.
For all browsers, GPAL handles any differences for you.
Of particular note is topping the browser window with Firefox requires a hardware click.
Declaration
public IAllowBrowserSettingsOrGoTo WithBrowserType(Enums.BrowserType browserType)
Parameters
| Type |
Name |
Description |
| Enums.BrowserType |
browserType |
Enumeration BrowserType of Chrome [default], Edge or Firefox.
|
Returns
Examples
Browser myBrowser = (Browser)GPAL.Browser
.WithBrowserType(BrowserType.Chrome)
.WithDriverLocation(@"c:\drivers")
.GoTo("https://www.ebay.com/")
WithDebugPort(Int32)
Specifies the TCP port number to connect to this browser session from a completely different GPAL workflow.
Only use this if another workflow will connect to an existing session using .WithExistingBrowser
Declaration
public IAllowBrowserSettingsOrGoTo WithDebugPort(int port = 57005)
Parameters
| Type |
Name |
Description |
| System.Int32 |
port |
The TCP port number to connect with to control the browser
|
Returns
Examples
// open a browser using debug port 6565
Browser browser1 = (Browser)GPAL.Browser
.WithBrowserType(browserType)
.WithDriverLocation(gPALInput.Text)
.WithDebugPort(6565)
.WithWaitOnDocumentReady(true)
.GoTo("https://studio.youtube.com");
// create an entirely new session connecting to the browser1 session
Browser browser2 = (Browser)GPAL.Browser
.WithExistingBrowser(6565)
.WithWaitOnDocumentReady(true)
.WithSelector(detailsTab).LeftClick();
browser1.Close(true); // no need to close 2, it's the same
WithDownloadLocation(String)
Specifies the download location for this browser sessions, overrides the default
Declaration
public IAllowBrowserSettingsOrGoTo WithDownloadLocation(string directory)
Parameters
| Type |
Name |
Description |
| System.String |
directory |
The full path to the download folder.
|
Returns
WithDriverLocation(String)
Specifies the location where the browser driver executable is loaded from.
Default location is the directory with the GPAL executable.
Declaration
public IAllowBrowserSettingsOrGoTo WithDriverLocation(string directory)
Parameters
| Type |
Name |
Description |
| System.String |
directory |
Directory containing the driver
|
Returns
Examples
Browser myBrowser = (Browser)GPAL.Browser
.WithBrowserType(BrowserType.Chrome)
.WithDriverLocation(@"c:\drivers")
.GoTo("https://www.ebay.com/")
WithExistingBrowser(Int32)
Specifies the port to use to connect to an existing session from another workflow started with .WithDebugPort
MUST be the same port as used when calling .WithDebugPort()
Declaration
public IAllowBrowserActionOrAnySelector WithExistingBrowser(int port)
Parameters
| Type |
Name |
Description |
| System.Int32 |
port |
The TCP port number to connect with to control the browser
|
Returns
Examples
// open a browser using debug port 6565
Browser browser1 = (Browser)GPAL.Browser
.WithBrowserType(browserType)
.WithDriverLocation(gPALInput.Text)
.WithDebugPort(6565)
.WithWaitOnDocumentReady(true)
.GoTo("https://studio.youtube.com");
// create an entirely new session connecting to the browser1 session
Browser browser2 = (Browser)GPAL.Browser
.WithExistingBrowser(6565)
.WithWaitOnDocumentReady(true)
.WithSelector(detailsTab).LeftClick();
browser1.Close(true); // no need to close 2, it's the same
WithGridToSave(IGPALGrid<String>)
Specifies a GPALGrid<string%gt; that will be subsequently saved to disk.
Headers can be specified inline using .WithHeader or, if not specified, will use the Selector name as the column header.
If using the Selector name as the header, the names and order of the headers are from the current UOW and the order the Selectors are defined.
NOTE: Scraping data occurs when .GetGrid(optionalOutGrid) is called. An internal grid is then created in the currentUOW.
This internal grid will be used in any subsequent .SaveTo[CSV|TabbedText|Text] method calls.
In this case, you do not need to specify an input grid using WithGridToSave.
Declaration
public IAllowWithHeaderOrFileActions WithGridToSave(IGPALGrid<string> inputGrid)
Parameters
| Type |
Name |
Description |
| IGPALGrid<System.String> |
inputGrid |
The GPALGrid<string%gt; of data to save
|
Returns
Examples
using GenerallyPositive.Common; // acess to GPALGrid
public static GPALGrid<string%gt; retGrid;
... code to fill in the grid ...
myBrowser
.WithGridToSave(retGrid)
.WithHeader("Description")
.WithHeader("Seller")
.WithHeader("Feedback")
.SaveToTabbedText(@"C:\ebay.retrieved.columns.txt");
Specify a column header for output. Headers are output in order defined.
Declaration
public IAllowWithHeaderOrFileActions WithHeader(string header)
Parameters
| Type |
Name |
Description |
| System.String |
header |
Header text
|
Returns
WithLoadImages(Boolean)
Determine whether to show images on a webpage.
Declaration
public IAllowBrowserSettingsOrGoTo WithLoadImages(bool loadImages)
Parameters
| Type |
Name |
Description |
| System.Boolean |
loadImages |
True to load/render images.
False [default] to NOT load/render images.
|
Returns
Examples
Browser myBrowser = (Browser)GPAL.Browser
.WithBrowserType(BrowserType.Chrome)
.WithDriverLocation(@"c:\drivers")
.WithLoadImages(false)
.GoTo("https://www.ebay.com/")
WithNetworkIdleMaxConnections(Int32)
Specifies the maximum duration to keep network stats before pruning old data
Declaration
public IAllowNetworkIdleSettings WithNetworkIdleMaxConnections(int maxConnections = 0)
Parameters
| Type |
Name |
Description |
| System.Int32 |
maxConnections |
|
Returns
Examples
Browser myBrowser = (Browser)GPAL.Browser
.WithBrowserType(BrowserType.Chrome)
.WithDriverLocation(@"c:\drivers")
.GoTo("https://www.ebay.com/")
.WithNetworkIdleTimeoutMs(500) // already the default value
.WithNetworkIdlePruneMs(10_000) // already the default value
.WithNetworkIdleMaxConnections(0) // already the default value
.WithWaitOnNetworkIdle(0)
.WithSelector(inputSearchSelector)
.FillInFrom("Find me");
WithNetworkIdlePruneMs(Int32)
Specifies the maximum duration to keep network stats before pruning old data
Declaration
public IAllowNetworkIdleSettings WithNetworkIdlePruneMs(int networkIdlePruneMs = 500)
Parameters
| Type |
Name |
Description |
| System.Int32 |
networkIdlePruneMs |
|
Returns
Examples
Browser myBrowser = (Browser)GPAL.Browser
.WithBrowserType(BrowserType.Chrome)
.WithDriverLocation(@"c:\drivers")
.GoTo("https://www.ebay.com/")
.WithNetworkIdleTimeoutMs(500) // already the default value
.WithNetworkIdlePruneMs(10_000) // already the default value
.WithNetworkIdleMaxConnections(0) // already the default value
.WithWaitOnNetworkIdle(0)
.WithSelector(inputSearchSelector)
.FillInFrom("Find me");
WithNetworkIdleTimeoutMs(Int32)
Specifies max time in milliseconds to wait for the network idle before returning false
Declaration
public IAllowNetworkIdleSettings WithNetworkIdleTimeoutMs(int networkIdleTimeoutMs = 500)
Parameters
| Type |
Name |
Description |
| System.Int32 |
networkIdleTimeoutMs |
|
Returns
Examples
Browser myBrowser = (Browser)GPAL.Browser
.WithBrowserType(BrowserType.Chrome)
.WithDriverLocation(@"c:\drivers")
.GoTo("https://www.ebay.com/")
.WithNetworkIdleTimeoutMs(500) // already the default value
.WithNetworkIdlePruneMs(10_000) // already the default value
.WithNetworkIdleMaxConnections(0) // already the default value
.WithWaitOnNetworkIdle(0)
.WithSelector(inputSearchSelector)
.FillInFrom("Find me");
WithNewTab(String)
Used to specify the next GoTo command should open in a new tab. The new tab is then the active tab.
Use .NextTab and .PreviousTab to navigate tabs.
NOTE: Applies only once. Use .WithNewTab before each .GoTo to open in a new tab.
Declaration
public IAllowBrowserAction WithNewTab(string url = null)
Parameters
| Type |
Name |
Description |
| System.String |
url |
|
Returns
Examples
myBrowser
.WithNewTab("http://www.google.com");
// open a new tab in headless mode, then navigate in the new tab
myBrowser
.WithNewTab()
.Get("http://www.google.com");
WithNextPageButton(Selector)
Specifies the Next Page button used to retrieve multiple pages of data.
Use with .GetPages(numOfPages) to specify how to get those next pages.
.GetGrid or any .SaveTo[CSV|Excel|File] will treat the current UOW as output Selectors from which to retrieve data.
Retrieving data will retrieve only the current page if nothing is specified.
Also useful with .WithAllThatMatch to retrieve repeating results (like on eBay)
See also .WithInfiniteScroll
Declaration
public IAllowWithPagesAndGridActions WithNextPageButton(Selector nextPageButtonselector)
Parameters
| Type |
Name |
Description |
| Selector |
nextPageButtonselector |
Next Page Button selector
|
Returns
WithOpenPDFExternally(Boolean)
Specifies whether the browser will render PDFs or launch an external program.
Declaration
public IAllowBrowserSettingsOrGoTo WithOpenPDFExternally(bool openPDFExternally)
Parameters
| Type |
Name |
Description |
| System.Boolean |
openPDFExternally |
True [default] to open PDFs external to the browser.
False to render in the browser.
|
Returns
WithOverwriteExistingFile(Boolean)
Overwrite the destination file locally when downloading.
If set to false, filenames will have a date timestamp appended to make each filename unique.
Used with .LeftClickAndDownload(filename) and .RightClickAndDownload(filename)
Declaration
public IAllowBrowserSettingsOrGoTo WithOverwriteExistingFile(bool overwriteFile)
Parameters
| Type |
Name |
Description |
| System.Boolean |
overwriteFile |
True to overwrite destination file.
False [default] to rename file on save.
|
Returns
Examples
myBrowser
.WithOverwriteExistingFile(true)
.RightClickAndDownload(fileList); // NOTE: filename used on save is added to the end of filelist
WithPageOrientation(Enums.PageOrientation)
Declaration
public IAllowAfterWaitForAndSizeControl WithPageOrientation(Enums.PageOrientation pageOrientation)
Parameters
Returns
WithPages(Int32)
Specified the number of pages to retrieve when using GetGrid or any .SaveTo[CSV|Excel|File]
Must also specify the Next Page button [.WithNextPageButton(selector)] or Infinite scroll [.WithInfiniteScroll] to tell GPAL how to retrieve next pages.
Declaration
public IAllowGetGridAndFillInFrom WithPages(int pageCount)
Parameters
| Type |
Name |
Description |
| System.Int32 |
pageCount |
Number of pages to retrieve.
|
Returns
WithPersistentSelector(Selector)
Add a persistent selector to the persistent UOW. Persistent selectors are always looked for whenever you perform an action on a UOW, like LeftClick, Hover, Focus, etc.
Use in conjunction with the PersistentCallIf handlers to create workflows to deal with the persistent selector(s).
Selectors may remove themselves from a UOW by using selector.Remove()
Only one persistent Unit of Work exists. All selectors are evaluated in the order they are defined.
Example: For browser, a persistent selector could look for a popup panel like 'Accept all cookies' that displays on all pages and may block processing..
Declaration
public IAllowBrowserSettingsOrGoTo WithPersistentSelector(Selector selector)
Parameters
| Type |
Name |
Description |
| Selector |
selector |
The GPAL Selector for the persistent element
|
Returns
WithProfileDataDirectory(String)
Specify the profile directory to use for this browser automation session
NOTE: if both Profile User Name and Profile Directory are defined, the specific directory will be used
Declaration
public IAllowBrowserSettingsOrGoTo WithProfileDataDirectory(string profileDataDirectory)
Parameters
| Type |
Name |
Description |
| System.String |
profileDataDirectory |
|
Returns
Examples
Browser myBrowser = (Browser)GPAL.Browser
.WithBrowserType(BrowserType.Chrome)
.WithProfileDataDirectory(@"c:\profileDataDirectory")
.WithDriverLocation(@"c:\drivers")
.GoTo("https://www.ebay.com/")
.WithWaitOnDocumentReady(true)
.WithSelector(inputSearchSelector)
.FillInFrom("Find me");
WithProfileName(String)
Specify the profile name to use under the data directory for this browser automation session
NOTE: use this if a data directory contains multiple profile directories and you do not want to use the default profile
Declaration
public IAllowBrowserSettingsOrGoTo WithProfileName(string profileName)
Parameters
| Type |
Name |
Description |
| System.String |
profileName |
Name of the browser profile to use
|
Returns
Examples
Browser myBrowser = (Browser)GPAL.Browser
.WithBrowserType(BrowserType.Chrome)
.WithProfileName(profileName)
.WithDriverLocation(@"c:\drivers")
.GoTo("https://www.ebay.com/")
.WithWaitOnDocumentReady(true)
.WithSelector(inputSearchSelector)
.FillInFrom("Find me");
WithProfileUserName(String)
Specify the operating system login username to find the profile directory to use for this browser automation session
NOTE: if both Profile User Name and Profile Directory are defined, the specific directory will be used
Declaration
public IAllowBrowserSettingsOrGoTo WithProfileUserName(string profileUserName)
Parameters
| Type |
Name |
Description |
| System.String |
profileUserName |
|
Returns
Examples
Browser myBrowser = (Browser)GPAL.Browser
.WithBrowserType(BrowserType.Chrome)
.WithProfileUserName(@"Ottomatic")
.WithDriverLocation(@"c:\drivers")
.GoTo("https://www.ebay.com/")
.WithWaitOnDocumentReady(true)
.WithSelector(inputSearchSelector)
.FillInFrom("Find me");
WithPromptForDownload(Boolean)
Set to true to always display the SAVE AS dialog box when downloading a file.
Very useful with LeftClickAndDownload(filename).
When set, every download will prompt you with the SAVE AS dialog, forcing you to fill in the filename.
For maximum ease You can use .LeftClickAndDownload(filename) or write GPAL code like this (example)
.LeftClick().WaitForWindowRegex("([sSaAvVeE])\w+*).SendString(filename).SendKey(GPAL.VK_ENTER)
Declaration
public IAllowBrowserSettingsOrGoTo WithPromptForDownload(bool promptForDownload)
Parameters
| Type |
Name |
Description |
| System.Boolean |
promptForDownload |
True to prompt for download save location.
False [default] to save downloads to the default save location.
|
Returns
Examples
myBrowser
.WithPromptForDownload(true)
.LeftClickAndDownload(fileList); // NOTE: filename used on save is added to the end of filelist
WithRunMode(Enums.RunMode)
Declaration
public IAllowWorkflowExecution WithRunMode(Enums.RunMode runMode)
Parameters
Returns
WithSelector(Selector)
Add a selector to the current UOW. Selectors make up a Unit of Work (UOW) to perform actions upon.
A UOW is: All selectors defined between actions like GoTo, LeftClick, Hover, Focus, etc.
Use in conjunction with the CallIf handlers to create workflows to deal with found/not found selector(s).
Selectors may remove themselves from a UOW by using selector.Remove()
Declaration
public IAllowAfterAnySelector WithSelector(Selector selector)
Parameters
| Type |
Name |
Description |
| Selector |
selector |
The GPAL Selector for the persistent element
|
Returns
Examples
Selector inputSearchSelector = (Selector)GPAL.Selector
.WithName("SearchInput")
.WithCSS("#gh-ac")
.WithXPath("//*[@id=\"gh-ac\"]")
.MatchPlaceholder("Search for anything");
Browser myBrowser = (Browser)GPAL.Browser
.WithBrowserType(BrowserType.Chrome)
.WithDriverLocation(@"c:\drivers")
.GoTo("https://www.ebay.com/")
.WithWaitOnDocumentReady(true)
.WithSelector(inputSearchSelector)
.FillInFrom("Find me");
WithUseDirectDownload(Boolean)
For use with .RightClickAndDownload, use websockets to directly download what the webelement references
Declaration
public IAllowBrowserSettingsOrGoTo WithUseDirectDownload(bool trueFalse)
Parameters
| Type |
Name |
Description |
| System.Boolean |
trueFalse |
False [default - open context, choose save as]
|
Returns
WithUseHardware(Boolean)
Force all workflow element interactions to use hardware emulation (selenium is default)
NOTE: Not available for headless operations (GPAL.Browser.Get)
Declaration
public IAllowBrowserSettingsOrGoTo WithUseHardware(bool trueFalse)
Parameters
| Type |
Name |
Description |
| System.Boolean |
trueFalse |
|
Returns
WithUseHeadless(Boolean)
Use Ottomatic browser extension to control the browser
Declaration
public IAllowBrowserSettingsOrGoTo WithUseHeadless(bool trueFalse)
Parameters
| Type |
Name |
Description |
| System.Boolean |
trueFalse |
|
Returns
WithUseJavaScript(Boolean)
Force all workflow element interactions to use javascript injection (selenium is default)
NOTE: Option if forced for headless operations (GPAL.Browser.Get)
Declaration
public IAllowBrowserSettingsOrGoTo WithUseJavaScript(bool trueFalse)
Parameters
| Type |
Name |
Description |
| System.Boolean |
trueFalse |
|
Returns
WithUseOttoMagic(Boolean)
Use OttoMagic browser extension for commands
Declaration
public IAllowBrowserSettingsOrGoTo WithUseOttoMagic(bool trueFalse)
Parameters
| Type |
Name |
Description |
| System.Boolean |
trueFalse |
|
Returns
WithUsePuppeteer(Boolean)
Use puppeteer for commands
Declaration
public IAllowDebugPort WithUsePuppeteer(bool trueFalse)
Parameters
| Type |
Name |
Description |
| System.Boolean |
trueFalse |
|
Returns
| Type |
Description |
| IAllowDebugPort |
Fluent interface to specify more Browser settings
|
WithUseStealth(Enums.StealthType)
Use stealth operations to block bot detection
use Runtime.disable before clicking login button
Add persistent script the runs before all others to inject anti-CDP detection script
Declaration
public IAllowBrowserSettingsOrGoTo WithUseStealth(Enums.StealthType steathType)
Parameters
Returns
WithWaitForWindowTimeout(Int32)
Define the time in seconds to WaitForWindow/Regex
Declaration
public IAllowAfterWaitForAndSizeControl WithWaitForWindowTimeout(int waitTimeInSeconds)
Parameters
| Type |
Name |
Description |
| System.Int32 |
waitTimeInSeconds |
Wait time in seconds
|
Returns
WithWaitOnDocumentReady(Boolean)
Specifies GPAL will wait for a true in the browser DocumentReady flag before trying to locate elements.
Mutally excludes WithWaitOnNetworkIdle - setting this true will set WithWaitOnNetworkIdle to false
Declaration
public IAllowBrowserSettingsOrGoTo WithWaitOnDocumentReady(bool trueFalse = true)
Parameters
| Type |
Name |
Description |
| System.Boolean |
trueFalse |
|
Returns
Examples
Browser myBrowser = (Browser)GPAL.Browser
.WithBrowserType(BrowserType.Chrome)
.WithDriverLocation(@"c:\drivers")
.GoTo("https://www.ebay.com/")
.WithWaitOnDocumentReady(true)
.WithSelector(inputSearchSelector)
.FillInFrom("Find me");
WithWaitOnIdleConnection(Boolean)
Specifies GPAL will wait for network to be idle on current page before trying to locate elements.
Mutally excludes WithWaitOnDocumentReady - setting this true will set WithWaitOnDocumentReady to false
Declaration
public IAllowBrowserSettingsOrGoTo WithWaitOnIdleConnection(bool trueFalse = true)
Parameters
| Type |
Name |
Description |
| System.Boolean |
trueFalse |
|
Returns
Examples
Browser myBrowser = (Browser)GPAL.Browser
.WithBrowserType(BrowserType.Chrome)
.WithDriverLocation(@"c:\drivers")
.GoTo("https://www.ebay.com/")
.WithNetworkIdleTimeoutMs(500) // already the default value
.WithNetworkIdlePruneMs(10_000) // already the default value
.WithNetworkIdleMaxConnections(0) // already the default value
.WithWaitOnNetworkIdle(true)
.WithSelector(inputSearchSelector)
.FillInFrom("Find me");
WithWindowSize(Size)
Set the default window size for when the browser opens.
As well, exiting fullscreen will return to this size.
IF NOT SET: 'Normal' to restore the window will restore the window to the Size before enterinng fullscreen
Declaration
public IAllowAllBrowserAndAllSelector WithWindowSize(Size windowSize)
Parameters
| Type |
Name |
Description |
| System.Drawing.Size |
windowSize |
Cannot be less than 100 in either dimension, nor larger than screen size
|
Returns
WithWorkflow(Action<IBrowser>)
Add/define a workflow to be used with .While/.Until/.Run/.RunMode
Declaration
public IAllowWorkflowExecution WithWorkflow(Action<IBrowser> workflow)
Parameters
| Type |
Name |
Description |
| System.Action<IBrowser> |
workflow |
|
Returns
Examples
The following example searches for "laptop" on eBay, Amazon, and Walmart in parallel, with one
explicit debug port and two auto-assigned ports:
Browser browser = GPAL.Browser
.WithBrowserType(BrowserType.Chrome)
.WithDriverLocation(@"c:\drivers")
.WithDebugPort(9221) // Top-level debug port
.WithWorkflow(b =>
{
b.WithDebugPort(9669) // Explicitly use 9669
.GoTo("https://www.ebay.com")
.WithSelector(GPAL.CssSelector("#gh-ac"))
.FillInFrom("laptop")
.SendKey(GPAL.VK_ENTER);
})
.WithWorkflow(b =>
{
// No WithDebugPort, auto-assigns 9221 (top-level 9221)
b.GoTo("https://www.amazon.com")
.WithSelector(GPAL.CssSelector("#twotabsearchtextbox"))
.FillInFrom("laptop")
.SendKey(GPAL.VK_ENTER);
})
.WithWorkflow(b =>
{
// No WithDebugPort, auto-assigns 9222 (top-level 9221 + 1)
b.GoTo("https://www.walmart.com")
.WithSelector(GPAL.CssSelector("#global-search-input"))
.FillInFrom("laptop")
.SendKey(GPAL.VK_ENTER);
})
.WithRunMode(RunMode.Parallel)
.Run(maxParallel: 3);
Implements