Tutorials

Tutorials

Image Matching and Selectors Inside Iframes

Two advanced selector techniques in one workflow: matching an element by a saved screenshot with WithImage and offsets, and reaching into nested iframes with InIframe before clicking an element that only exists inside the frame's own DOM.

Complete Program

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

using GenerallyPositive;

using GenerallyPositive.Browser;

using static GenerallyPositive.Enums;

static Selector imageSelector = (Selector)GPAL.Selector

.WithImage(GPAL.File.WithFileName(@"C:imagesebay.saved.plus.png").ToGPALObject())

.WithImageOffsetX(20)

.WithImageOffsetY(10);

public static Selector outerIframeSelector = (Selector)GPAL.Selector

.WithCSS(@"html > body > section > div > div > iframe")

.WithSelectorName("outer iframe");

public static Selector innerIframeSelector = (Selector)GPAL.Selector

.WithCSS(@"#Multiple > iframe")

.WithSelectorName("inner iframe");

public static Selector iframeInputSelector = (Selector)GPAL.Selector

.WithCSS(@"html > body > section > div > div > div > input")

.WithOffsetX(112)

.WithOffsetY(5)

.WithSelectorName("iframe input");

IBrowser browser = GPAL.Browser

.WithBrowserType(BrowserType.Chrome)

.WithUseAutomationEngine(AutomationEngine.PuppeteerPort)

.WithDriverLocation(@"c:drivers")

.GoTo("https://example.com/frames")

.LeftClick(innerIframeSelector)

.InIframe(innerIframeSelector)

.InIframe(outerIframeSelector)

.LeftClick(iframeInputSelector)

.FillInFrom("Hello World")

.ToGPALObject();

browser

.GoTo("https://www.example.com/")

.WithSelector(imageSelector)

.Hover()

.Close(true);

Matching an Element by Image

WithImage points a Selector at a saved screenshot of the element you want to find, instead of (or in addition to) CSS/XPath. GPAL matches the live page against that image. WithImageOffsetX and WithImageOffsetY shift the click/hover point relative to the matched image's origin - useful when the actual clickable target is a few pixels away from the most reliable visual anchor.

static Selector imageSelector = (Selector)GPAL.Selector

.WithImage(GPAL.File.WithFileName(@"C:imagesebay.saved.plus.png").ToGPALObject())

.WithImageOffsetX(20)

.WithImageOffsetY(10);

TIP

GPAL.File.WithFileName(...).ToGPALObject() wraps the screenshot path as a GPALFile, the same value object used for uploads and downloads elsewhere in GPAL. See GPALFile: Files as Objects.

Defining Iframe Selectors

Iframes are just selectors that happen to point at an <iframe> element. Give each one a clear name with WithSelectorName so logs make sense - especially important once you're nesting one iframe inside another.

public static Selector outerIframeSelector = (Selector)GPAL.Selector

.WithCSS(@"html > body > section > div > div > iframe")

.WithSelectorName("outer iframe");

public static Selector innerIframeSelector = (Selector)GPAL.Selector

.WithCSS(@"#Multiple > iframe")

.WithSelectorName("inner iframe");

public static Selector iframeInputSelector = (Selector)GPAL.Selector

.WithCSS(@"html > body > section > div > div > div > input")

.WithOffsetX(112)

.WithOffsetY(5)

.WithSelectorName("iframe input");

InIframe Scopes the Rest of the Chain

Click into the frame's container, then call InIframe to tell GPAL that subsequent selectors should be evaluated inside that iframe's document. Stacking InIframe calls drills into a frame nested inside another frame, just like the DOM itself is nested.

browser

.LeftClick(innerIframeSelector)

.InIframe(innerIframeSelector)

.InIframe(outerIframeSelector)

.LeftClick(iframeInputSelector)

.FillInFrom("Hello World");

WARNING

After InIframe, every selector in the chain is looked up relative to that frame's DOM, not the main page. If you need to go back to the top-level document, call InMainDom() to reset the scope before continuing.

Switching Pages Doesn't Affect Image Matching

Image-based selectors don't care about the page's DOM structure at all - GoTo a different page, point a fresh chain at the image selector, and Hover() (or LeftClick) the same way you would with any other selector. This makes image matching a useful fallback when an element's markup is unstable or generated by a canvas/widget.

browser

.GoTo("https://www.example.com/")

.WithSelector(imageSelector)

.Hover()

.Close(true);

On this page

Tutorials
Image Matching and Selectors Inside Iframes
  • Complete Program
  • Matching an Element by Image
  • Defining Iframe Selectors
  • InIframe Scopes the Rest of the Chain
  • Switching Pages Doesn't Affect Image Matching