@@ -60,7 +60,7 @@ namespace CSF.Screenplay.Selenium
6060 /// Developers may use the configuration to store a library of available WebDriver configurations, and use a single
6161 /// environment variable to switch between them at execution time.
6262 /// </para>
63- /// <code>
63+ /// <code language="csharp" >
6464 /// using CSF.Extensions.WebDriver;
6565 /// using CSF.Screenplay.Selenium;
6666 ///
@@ -97,9 +97,42 @@ public class BrowseTheWeb : ICanReport, IDisposable
9797 /// </summary>
9898 /// <remarks>
9999 /// <para>
100- /// When this value is set to <see langword="true"/>, this will trigger usage of <see cref="Actions.BeginCollectingLogsWithJavaScript"/>
101- /// at points where it is required. This is applicable only when the current <see cref="WebDriver"/> implementation has the
102- /// quirk <see cref="BrowserQuirks.CanGetLogsWithJavascriptWorkaround"/>.
100+ /// Different web driver implementations have varying levels of support for providing access to web browser's console logs.
101+ /// As of June 2026, the only implementations which provide native access are local implementations of Chromium-based
102+ /// web drivers, such as <see cref="OpenQA.Selenium.Chrome.ChromeDriver"/> and <see cref="OpenQA.Selenium.Edge.EdgeDriver"/>.
103+ /// For other web browsers/drivers, as well as all remote web drivers, Selenium is unable to directly access their
104+ /// logs using a native API.
105+ /// </para>
106+ /// <para>
107+ /// When this property is set to <see langword="true"/>, it triggers behaviour which causes Screenplay to attempt to access
108+ /// the browser's console logs more aggressively. Screenplay activates a JavaScript-based workaround when native log-collection is not viable.
109+ /// That JavaScript-based approach is coordinated from the Task <see cref="Tasks.BeginCollectingLogsWithJavaScriptIfApplicable"/>
110+ /// and ultimately the Action <see cref="Actions.BeginCollectingLogsWithJavaScript"/>.
111+ /// This functionality is consumed by the logic of two Tasks:
112+ /// </para>
113+ /// <list type="bullet">
114+ /// <item><description><see cref="Tasks.NavigateToUrl"/></description></item>
115+ /// <item><description><see cref="Tasks.ClickAndWaitForDocumentReady"/></description></item>
116+ /// </list>
117+ /// <para>
118+ /// In both cases, these tasks will execute the logic of <see cref="Tasks.BeginCollectingLogsWithJavaScriptIfApplicable"/>.
119+ /// In determining whether the JavaScript approach is applicable, the task verifies that this setting is <see langword="true"/>,
120+ /// and whether the current web driver implementation requires the JavaScript workaround to get logs.
121+ /// That is - the <see cref="WebDriver"/> is <b>not</b> remote, and it <b>does</b> have the quirk
122+ /// <see cref="BrowserQuirks.CanGetLogsWithJavascriptWorkaround"/> and it <b>does not</b> have the quirk
123+ /// <see cref="BrowserQuirks.HasNativeLogsSupport"/>. If all these criteria are satisfied, then the action
124+ /// <see cref="Actions.BeginCollectingLogsWithJavaScript"/> is executed, to begin collecting logs in JavaScript.
125+ /// </para>
126+ /// <para>
127+ /// It's important to understand that the JavaScript workaround for getting console logs <em>is imperfect</em>.
128+ /// Logs are only collected from the point at which the 'begin collection' script is sent to the web browser.
129+ /// Any logs which were written before that script arrives will be missed and will be unavailable for reading.
130+ /// This is why the collection begins immediately after two tasks which cause page reloads.
131+ /// Even so, imagine the loading of a new web page, and immediately as the page loads, there is an important console message written.
132+ /// It's quite possible that - in the brief (perhaps milliseconds) delay between the page load completing and the "Begin
133+ /// collecting logs" script arriving, that the important message was already written to the logs. In this circumstance
134+ /// the important message will not be available to Screenplay. Unfortunately there is no better solution or workaround to
135+ /// this problem when using Selenium.
103136 /// </para>
104137 /// </remarks>
105138 public bool ShouldCollectLogs => collectLogs ;
0 commit comments