| // <copyright file="UserPromptHandler.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> | |
| namespace OpenQA.Selenium; | |
| /// <summary> | |
| /// Represents a WebDriver session's user prompt handler, which defines how unhandled browser prompts | |
| /// (alerts, confirms, prompts, beforeunload dialogs, file selection dialogs) are managed during automation. | |
| /// </summary> | |
| /// <remarks> | |
| /// This corresponds to the W3C WebDriver <c>unhandledPromptBehavior</c> capability, which may be expressed | |
| /// either as a single string applied to all prompt types, or as a per-prompt-type map. | |
| /// <para> | |
| /// Available variants: | |
| /// <list type="bullet"> | |
| /// <item><description><see cref="Uniform"/> - Wraps a single <see cref="UnhandledPromptBehavior"/> value applied to all prompt types. Create via the implicit conversion from <see cref="UnhandledPromptBehavior"/> or by constructing <see cref="Uniform"/> directly.</description></item> | |
| /// <item><description><see cref="PerPromptType"/> - Allows configuring per-prompt behaviors (Alert, Confirm, Prompt, BeforeUnload, File, Default).</description></item> | |
| /// </list> | |
| /// </para> | |
| /// </remarks> | |
| public abstract record UserPromptHandler | |
| { | |
| private UserPromptHandler() { } | |
| /// <summary> | |
| /// Converts a nullable <see cref="UnhandledPromptBehavior"/> to a <see cref="UserPromptHandler"/> instance, | |
| /// or <see langword="null"/> when <paramref name="value"/> is <see langword="null"/>. | |
| /// </summary> | |
| /// <param name="value">The <see cref="UnhandledPromptBehavior"/> value to convert.</param> | |
| public static implicit operator UserPromptHandler?(UnhandledPromptBehavior? value) | |
| => value is { } v ? new Uniform(v) : null; | |
| internal abstract object? ToCapabilities(); | |
| private static string ConvertBehaviorToString(UnhandledPromptBehavior behavior) => | |
| behavior switch | |
| { | |
| UnhandledPromptBehavior.Ignore => "ignore", | |
| UnhandledPromptBehavior.Accept => "accept", | |
| UnhandledPromptBehavior.Dismiss => "dismiss", | |
| UnhandledPromptBehavior.AcceptAndNotify => "accept and notify", | |
| UnhandledPromptBehavior.DismissAndNotify => "dismiss and notify", | |
| _ => throw new InvalidOperationException($"UnhandledPromptBehavior value '{behavior}' is not recognized."), | |
| }; | |
| /// <summary> | |
| /// Represents a user prompt handler that applies a single <see cref="UnhandledPromptBehavior"/> value | |
| /// as the fallback default for all prompt types. | |
| /// </summary> | |
| /// <param name="Value">The unhandled prompt behavior to apply. Specifies how unexpected browser prompts are handled during automation.</param> | |
| public sealed record Uniform(UnhandledPromptBehavior Value) : UserPromptHandler | |
| { | |
| internal override object? ToCapabilities() | |
| { | |
| #pragma warning disable CS0618 // UnhandledPromptBehavior.Default is obsolete | |
| if (Value == UnhandledPromptBehavior.Default) | |
| { | |
| return null; | |
| } | |
| #pragma warning restore CS0618 | |
| return ConvertBehaviorToString(Value); | |
| } | |
| } | |
| /// <summary> | |
| /// Represents a user prompt handler that specifies distinct <see cref="UnhandledPromptBehavior"/> values | |
| /// for individual prompt types (alert, confirm, prompt, beforeunload, file), with a fallback default. | |
| /// </summary> | |
| /// <remarks>Use this variant to configure distinct behaviors for alert, confirm, prompt, beforeunload, and file | |
| /// selection dialogs encountered during browser automation. Each property allows you to control the response to a | |
| /// specific type of unhandled prompt, enabling fine-grained handling beyond a single global setting.</remarks> | |
| public sealed record PerPromptType : UserPromptHandler | |
| { | |
| /// <summary> | |
| /// Gets the behavior to use when an unexpected alert is encountered during automation, | |
| /// or <see langword="null"/> to leave it unset. | |
| /// </summary> | |
| public UnhandledPromptBehavior? Alert { get; init; } | |
| /// <summary> | |
| /// Gets the behavior to use when a confirmation prompt is encountered, | |
| /// or <see langword="null"/> to leave it unset. | |
| /// </summary> | |
| public UnhandledPromptBehavior? Confirm { get; init; } | |
| /// <summary> | |
| /// Gets the behavior to use when an unexpected prompt is encountered during automation, | |
| /// or <see langword="null"/> to leave it unset. | |
| /// </summary> | |
| public UnhandledPromptBehavior? Prompt { get; init; } | |
| /// <summary> | |
| /// Gets the behavior to use when an unexpected beforeunload dialog is encountered, | |
| /// or <see langword="null"/> to leave it unset. | |
| /// </summary> | |
| public UnhandledPromptBehavior? BeforeUnload { get; init; } | |
| /// <summary> | |
| /// Gets the behavior to use when an unexpected file selection dialog is encountered, | |
| /// or <see langword="null"/> to leave it unset. | |
| /// </summary> | |
| /// <remarks>The "file" prompt type is respected only in WebDriver BiDi sessions.</remarks> | |
| public UnhandledPromptBehavior? File { get; init; } | |
| /// <summary> | |
| /// Gets the fallback behavior to use when no specific handler is defined for a given prompt type, | |
| /// or <see langword="null"/> to leave it unset. | |
| /// </summary> | |
| public UnhandledPromptBehavior? Default { get; init; } | |
| internal override object? ToCapabilities() | |
| { | |
| Dictionary<string, string> capabilities = []; | |
| AddIfSet(capabilities, "alert", Alert); | |
| AddIfSet(capabilities, "confirm", Confirm); | |
| AddIfSet(capabilities, "prompt", Prompt); | |
| AddIfSet(capabilities, "beforeUnload", BeforeUnload); | |
| AddIfSet(capabilities, "file", File); | |
| AddIfSet(capabilities, "default", Default); | |
| return capabilities; | |
| } | |
| private static void AddIfSet(Dictionary<string, string> capabilities, string key, UnhandledPromptBehavior? value) | |
| { | |
| #pragma warning disable CS0618 // UnhandledPromptBehavior.Default is obsolete | |
| if (value is { } v && v != UnhandledPromptBehavior.Default) | |
| { | |
| capabilities[key] = ConvertBehaviorToString(v); | |
| } | |
| #pragma warning restore CS0618 | |
| } | |
| } | |
| } | |
| /// <summary> | |
| /// Specifies how a WebDriver session handles an unhandled user prompt. | |
| /// </summary> | |
| /// <remarks> | |
| /// Corresponds to the handler values defined for the W3C WebDriver | |
| /// <c>unhandledPromptBehavior</c> capability: | |
| /// <c>dismiss</c>, <c>accept</c>, <c>dismiss and notify</c>, <c>accept and notify</c>, and <c>ignore</c>. | |
| /// When no handler is configured, the spec's implicit default is <see cref="DismissAndNotify"/>. | |
| /// </remarks> | |
| public enum UnhandledPromptBehavior | |
| { | |
| /// <summary> | |
| /// Sentinel value meaning "behavior not set". Not part of the W3C WebDriver spec. | |
| /// </summary> | |
| [Obsolete("Use a nullable UnhandledPromptBehavior? and pass null to leave the behavior unset. This member will be removed in v4.46.")] | |
| Default, | |
| /// <summary> | |
| /// Ignore unexpected alerts, such that the user must handle them. | |
| /// </summary> | |
| Ignore, | |
| /// <summary> | |
| /// Accept unexpected alerts. | |
| /// </summary> | |
| Accept, | |
| /// <summary> | |
| /// Dismiss unexpected alerts. | |
| /// </summary> | |
| Dismiss, | |
| /// <summary> | |
| /// Accepts unexpected alerts and notifies the user that the alert has | |
| /// been accepted by throwing an <see cref="UnhandledAlertException"/> | |
| /// </summary> | |
| AcceptAndNotify, | |
| /// <summary> | |
| /// Dismisses unexpected alerts and notifies the user that the alert has | |
| /// been dismissed by throwing an <see cref="UnhandledAlertException"/> | |
| /// </summary> | |
| DismissAndNotify | |
| } |