[dotnet] [bidi] Earlier preview feedback gathering

[nvborisenko]

Feature and motivation

Here we are going to gather everything related to BiDi implementation in .NET and improve it as soon as possible despite on any potential breaking changes.

1. Discriminated unions

We have a lot of classes what are inherited from a base. The basic example:

public abstract record ClipRectangle;

public record BoxClipRectangle(double X, double Y, double Width, double Height) : ClipRectangle;

public record ElementClipRectangle(Script.SharedReference Element) : ClipRectangle;

ClipRecatange is used like:

var screenshot = await context.CaptureScreenshotAsync(....); // it takes ClipRectangle as argument

And it is not clear what exactly I can put as arguments. I see base class as an argument, but I don't see what available options I can provide. We can add factory:

var screenshot = await context.CaptureScreenshotAsync(ClipRectangle.Box(5, 5, 10, 10));

But it requires to write so many boilerplate code from selenium team. Don't forget about optional parameters (which requires new class definition). So many code.

Solution

Use nested classes for all discriminated classes.

public abstract record ClipRectangle {
  public record Box(double X, double Y, double Width, double Height) : ClipRectangle;

  public record Element(Script.SharedReference Element) : ClipRectangle;
}

So user will be able to:

var screenshot = await context.CaptureScreenshotAsync(new ClipRectangle.Box(5, 5, 10, 10));

For user it seems there is no big diff, but for selenium team it is HUGE diff. And when https://github.com/dotnet/csharplang/blob/main/proposals/TypeUnions.md will be in place, it will everybody make happy: selenium team to write even less code, and user probably will write: var screenshot = await context.CaptureScreenshotAsync(new Box(5, 5, 10, 10));

2. Don't mimic BiDi instance as BrowsingContext

We have helper methods in BiDi class which actually forward to BrowsingContext module.
Example:

await bidi.CreateContextAsync(...);

Stop doing it and just expose modules. So it would be better:

await bidi.BrowsingContext.CreateAsync(...);

3. Result object as Enumerable

Some commands return result, which seems to be a list of items.

var result = await context.Storage.GetCookiesAsync();

Where result is:

storage.GetCookiesResult = {
  cookies: [*network.Cookie],
  partitionKey: storage.PartitionKey,
}

So result is GetCookiesResult class, and it would be great if it behaves as enumerable.

Solution

Implement IReadOnlyList<T>. So user is able to:

var cookies = await context.Storage.GetCookiesAsync();

Console.WriteLine(cookies[0].Name);
Console.WriteLine(cookies.PartitionKey);

And it will be also good to rename result class to CookiesList (or CookiesReadOnlyList or CookiesCollection?)

[github-actions]

@nvborisenko, thank you for creating this issue. We will troubleshoot it as soon as we can.

---

Info for maintainers

Triage this issue by using labels.

If information is missing, add a helpful comment and then I-issue-template label.

If the issue is a question, add the I-question label.

If the issue is valid but there is no time to troubleshoot it, consider adding the help wanted label.

If the issue requires changes or fixes from an external project (e.g., ChromeDriver, GeckoDriver, MSEdgeDriver, W3C), add the applicable G-* label, and it will provide the correct link and auto-close the issue.

After troubleshooting the issue, please add the R-awaiting answer label.

Thank you!

[S-Kulyk]

Wanted to get hands on the new BiDi interface, but struggled due to the lack of documentation starting from getting the BiDi object: when should driver.AsBiDiAsync() and driver.AsBidiContextAsync() be used?

Would be great to have similar samples to those that already exist for CDP
https://www.selenium.dev/documentation/webdriver/bidi/cdp/network/

I understand that it might sound more like complaint rather than a feedback, but it's safe to assume I won't be the only one who will have similar questions when tinkering with BiDI

[nvborisenko]

Sorry for that, it even may a subject for change. This is why we are collecting any feedback.

Returning back to the question:

driver.AsBiDiAsync(); // returns an object who is on top of all "tabs"

driver.AsBidiContextAsync(); // returns the current "tab"

We are still lack of documentation, construction of API is a priority. And then docs will be in place.