blob: 1bb7565026ee5aaf3cbd865dc884a22a865410a8 [file] [edit]
// <copyright file="AccessibilitySnapshotter.cs" company="Selenium Committers">
// Licensed to the Software Freedom Conservancy (SFC) under one
// or more contributor license agreements. See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership. The SFC licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the License for the
// specific language governing permissions and limitations
// under the License.
// </copyright>
using System.Text.Json;
using OpenQA.Selenium.BiDi;
using OpenQA.Selenium.BiDi.Script;
using OpenQA.Selenium.Internal;
using OpenQA.Selenium.Internal.Logging;
using BiDiBrowsingContext = OpenQA.Selenium.BiDi.BrowsingContext.BrowsingContext;
using BrowsingContextInfo = OpenQA.Selenium.BiDi.BrowsingContext.Info;
using GetTreeOptions = OpenQA.Selenium.BiDi.BrowsingContext.GetTreeOptions;
namespace OpenQA.Selenium;
/// <summary>
/// Takes accessibility snapshots over a BiDi connection: runs the atom's wire entry in the sandbox
/// realm of each document and stitches child frames into the tree. The atom hands the tree back as
/// one JSON string beside the element and frame references, so this class only maps references and
/// recurses into frames. It holds no state of its own, so one instance serves a driver for its life;
/// it knows nothing of the driver beyond how to find the current window and how to turn a node
/// reference into an element.
/// </summary>
internal sealed class AccessibilitySnapshotter
{
private static readonly ILogger s_logger = Log.GetLogger<AccessibilitySnapshotter>();
/// <summary>
/// The sandbox realm the atom runs in: page scripts cannot reach its prototypes.
/// </summary>
private const string Sandbox = "selenium";
private const string StaleMessage = "the snapshot root is no longer attached to a document";
private readonly IBiDi _bidi;
private readonly Func<string> _currentWindowHandle;
private readonly Func<string, IWebElement> _createElement;
/// <summary>
/// Initializes a new instance of the <see cref="AccessibilitySnapshotter"/> class.
/// </summary>
/// <param name="bidi">The BiDi connection to run the atom over.</param>
/// <param name="currentWindowHandle">Gives the handle of the current window, the id of the top-level browsing context a snapshot is taken in, at the time of each snapshot.</param>
/// <param name="createElement">Turns the shared id of a node into the element the snapshot references.</param>
public AccessibilitySnapshotter(IBiDi bidi, Func<string> currentWindowHandle, Func<string, IWebElement> createElement)
{
_bidi = bidi;
_currentWindowHandle = currentWindowHandle;
_createElement = createElement;
}
/// <summary>
/// Snapshots the whole page, or the subtree under the element <paramref name="rootId"/> refers to.
/// </summary>
/// <param name="rootId">The reference of the element whose subtree to snapshot, or <see langword="null"/> for the page of the current window's top-level browsing context.</param>
/// <param name="interestingOnly">Whether unnamed generic and presentational elements produce no node; with <see langword="false"/> every rendered element produces one.</param>
/// <param name="cancellationToken">A token to cancel the operation.</param>
/// <returns>The snapshot, with every reachable child frame's tree attached under its <c>iframe</c> node.</returns>
/// <exception cref="StaleElementReferenceException">When the root no longer belongs to a document.</exception>
public async Task<AccessibilityNode> SnapshotAsync(string? rootId, bool interestingOnly, CancellationToken cancellationToken)
{
IBiDi session = _bidi;
BiDiBrowsingContext top = new BiDiBrowsingContext(session, _currentWindowHandle());
if (rootId is null)
{
return await SnapshotContextAsync(session, top, null, interestingOnly, cancellationToken).ConfigureAwait(false)
?? throw new WebDriverException("accessibility snapshot: the script returned nothing");
}
// The element may live in any frame of the window. Chromium resolves its shared id only in
// the document that owns it; Firefox resolves it in any document of the browsing context
// group, so the atom checks ownership itself and each context is tried until the owner is
// found.
foreach (BiDiBrowsingContext context in await ListContextsAsync(session, top, cancellationToken).ConfigureAwait(false))
{
AccessibilityNode? node = await SnapshotContextAsync(session, context, rootId, interestingOnly, cancellationToken).ConfigureAwait(false);
if (node is not null)
{
return node;
}
}
throw new StaleElementReferenceException(StaleMessage);
}
/// <summary>
/// The snapshot of a context, or null when the document of that context does not own the root:
/// either the remote end refused the shared id, or the atom answered null for it. The
/// interestingOnly flag goes first, so a whole-page call sends no placeholder for a root.
/// </summary>
private async Task<AccessibilityNode?> SnapshotContextAsync(IBiDi session, BiDiBrowsingContext context, string? rootId, bool interestingOnly, CancellationToken cancellationToken)
{
ImmutableArray<LocalValue> arguments = rootId is null
? ImmutableArray.Create<LocalValue>(new BooleanLocalValue(interestingOnly))
: ImmutableArray.Create<LocalValue>(new BooleanLocalValue(interestingOnly), new SharedReferenceLocalValue(rootId));
RemoteValue? result = await CallAsync(session, context, arguments, cancellationToken).ConfigureAwait(false);
if (result is null || result is NullRemoteValue)
{
return null;
}
Dictionary<string, RemoteValue> fields = ReadObjectFields(result);
if (fields.ContainsKey("error"))
{
// The only error the atom reports as data: the root left its document.
throw new StaleElementReferenceException(StaleMessage);
}
List<IWebElement> elements = new List<IWebElement>();
foreach (RemoteValue node in ReadItems(GetRequired(fields, "elements")))
{
elements.Add(_createElement(ReadSharedId(node)));
}
List<BiDiBrowsingContext?> windows = new List<BiDiBrowsingContext?>();
foreach (RemoteValue window in ReadItems(GetRequired(fields, "windows")))
{
windows.Add(ReadContext(window));
}
using JsonDocument document = JsonDocument.Parse(ReadString(GetRequired(fields, "json")));
return await BuildNodeAsync(
document.RootElement,
elements,
index => StitchAsync(session, windows[index], interestingOnly, cancellationToken)).ConfigureAwait(false);
}
/// <summary>
/// Builds the node tree from the atom's wire form: the node's fields, with "element" an index
/// into the elements and, on a frame node, "frame" an index the frame children callback
/// resolves to the frame's own tree.
/// </summary>
private async Task<AccessibilityNode> BuildNodeAsync(JsonElement data, IReadOnlyList<IWebElement> elements, Func<int, Task<IReadOnlyList<AccessibilityNode>>> frameChildren)
{
List<AccessibilityNode> children = new List<AccessibilityNode>();
if (data.TryGetProperty("frame", out JsonElement frame))
{
children.AddRange(await frameChildren(frame.GetInt32()).ConfigureAwait(false));
}
else
{
foreach (JsonElement child in data.GetProperty("children").EnumerateArray())
{
children.Add(await BuildNodeAsync(child, elements, frameChildren).ConfigureAwait(false));
}
}
Dictionary<string, object> states = new Dictionary<string, object>();
foreach (JsonProperty state in data.GetProperty("states").EnumerateObject())
{
states[state.Name] = ReadState(state.Value);
}
return new AccessibilityNode(
data.GetProperty("role").GetString() ?? string.Empty,
data.GetProperty("name").GetString() ?? string.Empty,
data.TryGetProperty("description", out JsonElement description) ? description.GetString() ?? string.Empty : string.Empty,
data.TryGetProperty("value", out JsonElement value) ? value.GetString() : null,
data.TryGetProperty("url", out JsonElement url) ? url.GetString() : null,
states,
data.TryGetProperty("element", out JsonElement element) ? elements[element.GetInt32()] : null,
children);
}
/// <summary>
/// Runs the atom's wire entry in the sandbox of the context; the remote value of its result, or
/// null when the document of the context does not own the root's shared id. The first argument
/// is the interestingOnly flag, the optional second the root.
/// </summary>
private static async Task<RemoteValue?> CallAsync(IBiDi session, BiDiBrowsingContext context, ImmutableArray<LocalValue> arguments, CancellationToken cancellationToken)
{
CallFunctionOptions options = new CallFunctionOptions
{
Arguments = arguments,
ResultOwnership = ResultOwnership.None,
SerializationOptions = new SerializationOptions { MaxDomDepth = 0 },
};
EvaluateResult result;
try
{
result = await session.Script.CallFunctionAsync(
"(interestingOnly, root) => (" + ResourceUtilities.AccessibilitySnapshotAtom + ")(root, {interestingOnly})",
false,
new ContextTarget(context) { Sandbox = Sandbox },
options,
cancellationToken).ConfigureAwait(false);
}
catch (BiDiException e) when (arguments.Length > 1 && Mentions(e, "no such node"))
{
// The root lives in another frame, or its document is gone.
return null;
}
if (result is EvaluateResultSuccess success)
{
return success.Result;
}
string text = result is EvaluateResultException failure ? failure.ExceptionDetails.Text : result.ToString()!;
throw new WebDriverException("accessibility snapshot failed in the page: " + text);
}
/// <summary>
/// The document of a frame as the frame node's one child, or no children when unreachable.
/// </summary>
private async Task<IReadOnlyList<AccessibilityNode>> StitchAsync(IBiDi session, BiDiBrowsingContext? context, bool interestingOnly, CancellationToken cancellationToken)
{
if (context is null)
{
return Array.Empty<AccessibilityNode>();
}
try
{
AccessibilityNode? document = await SnapshotContextAsync(session, context, null, interestingOnly, cancellationToken).ConfigureAwait(false);
return document is null ? Array.Empty<AccessibilityNode>() : new[] { document };
}
catch (BiDiException e) when (Mentions(e, "no such frame"))
{
// Gone between discovery and the call, or mid-navigation: the frame stays a leaf.
// Anything else is a real failure.
s_logger.Debug("accessibility snapshot: frame " + context.Id + " not reachable: " + e.Message);
return Array.Empty<AccessibilityNode>();
}
}
/// <summary>
/// The window's browsing contexts, top-level first, then each frame depth-first.
/// </summary>
private static async Task<List<BiDiBrowsingContext>> ListContextsAsync(IBiDi session, BiDiBrowsingContext top, CancellationToken cancellationToken)
{
var tree = await session.BrowsingContext.GetTreeAsync(new GetTreeOptions { Root = top }, cancellationToken).ConfigureAwait(false);
List<BiDiBrowsingContext> contexts = new List<BiDiBrowsingContext> { top };
foreach (BrowsingContextInfo info in tree.Contexts)
{
CollectContexts(info, top, contexts);
}
return contexts;
}
/// <summary>
/// Adds every context below the top-level one to the list, depth-first; the top-level context is listed by the caller.
/// </summary>
private static void CollectContexts(BrowsingContextInfo info, BiDiBrowsingContext top, List<BiDiBrowsingContext> contexts)
{
if (info.Context.Id != top.Id)
{
contexts.Add(info.Context);
}
foreach (BrowsingContextInfo child in info.Children ?? ImmutableArray<BrowsingContextInfo>.Empty)
{
CollectContexts(child, top, contexts);
}
}
/// <summary>
/// Whether the exception's message carries the text; the BiDi layer has no typed error for "no such node" yet.
/// </summary>
private static bool Mentions(Exception e, string text)
{
return e.Message is not null && e.Message.Contains(text);
}
/// <summary>
/// The properties of an object remote value, by name.
/// </summary>
private static Dictionary<string, RemoteValue> ReadObjectFields(RemoteValue value)
{
if (value is not ObjectRemoteValue obj)
{
throw new WebDriverException("accessibility snapshot: expected an object remote value, got " + value.GetType().Name);
}
Dictionary<string, RemoteValue> fields = new Dictionary<string, RemoteValue>();
foreach (ImmutableArray<RemoteValue> pair in obj.Value ?? ImmutableArray<ImmutableArray<RemoteValue>>.Empty)
{
if (pair.Length != 2)
{
throw new WebDriverException("accessibility snapshot: expected object entries");
}
// A property name is written as a plain string, or as a string remote value.
fields[ReadString(pair[0])] = pair[1];
}
return fields;
}
/// <summary>
/// The items of an array remote value.
/// </summary>
private static ImmutableArray<RemoteValue> ReadItems(RemoteValue value)
{
if (value is not ArrayRemoteValue array)
{
throw new WebDriverException("accessibility snapshot: expected an array remote value, got " + value.GetType().Name);
}
return array.Value ?? ImmutableArray<RemoteValue>.Empty;
}
/// <summary>
/// The named property, or a <see cref="WebDriverException"/> when the atom's result lacks it.
/// </summary>
private static RemoteValue GetRequired(Dictionary<string, RemoteValue> fields, string name)
{
if (!fields.TryGetValue(name, out RemoteValue? value))
{
throw new WebDriverException("accessibility snapshot: the result has no " + name);
}
return value;
}
/// <summary>
/// The shared id of a node remote value from the elements list.
/// </summary>
private static string ReadSharedId(RemoteValue value)
{
if (value is not NodeRemoteValue node || string.IsNullOrEmpty(node.SharedId))
{
throw new WebDriverException("accessibility snapshot: expected a node reference in the elements list");
}
return node.SharedId;
}
/// <summary>
/// The browsing context of a window remote value; null for a frame with no reachable context.
/// </summary>
private static BiDiBrowsingContext? ReadContext(RemoteValue value)
{
return value is WindowProxyRemoteValue window ? window.Value.Context : null;
}
/// <summary>
/// The text of a string remote value; empty for null or undefined.
/// </summary>
private static string ReadString(RemoteValue value)
{
return value switch
{
StringRemoteValue s => s.Value,
NullRemoteValue or UndefinedRemoteValue => string.Empty,
_ => value.ToString() ?? string.Empty,
};
}
/// <summary>
/// A state value as the node exposes it: a <see cref="bool"/>, a <see cref="long"/> or a <see cref="string"/>.
/// </summary>
private static object ReadState(JsonElement value)
{
return value.ValueKind switch
{
JsonValueKind.True => true,
JsonValueKind.False => false,
JsonValueKind.Number => value.GetInt64(),
_ => value.GetString() ?? string.Empty,
};
}
}