[dotnet] Support UnhandledPromptBehavior option as string and map (breaking change)

[nvborisenko]

User description

🔗 Related Issues

Fixes #16102

💥 What does this PR do?

This PR changes UnhandledPromptBehavior property return type to custom type, supporting both string and map representation at serialization phase.

// Same handler for every prompt
options.UnhandledPromptBehavior = UnhandledPromptBehavior.Accept;

// Per prompt type (only set what you need)
options.UnhandledPromptBehavior = new UserPromptHandler.PerPromptType
{
    Alert = UnhandledPromptBehavior.Accept,
    Confirm = UnhandledPromptBehavior.Dismiss,
    File = UnhandledPromptBehavior.Dismiss,    // BiDi only
    Default = UnhandledPromptBehavior.DismissAndNotify, // fallback
};

// Leave unset (driver picks spec default = "dismiss and notify")
options.UnhandledPromptBehavior = null;
options.UnhandledPromptBehavior = default;

🔧 Implementation Notes

It is not a breaking change at compilation level! One file change to emphasize that users are not affected.

💡 Additional Considerations

I intentionally didn't introduce new property in Options class, it would lead to a mess in my opinion.

🔄 Types of changes

• New feature (non-breaking change for 99% users)
• Breaking change, binary

---

PR Type

Enhancement

---

Description

• Support UnhandledPromptBehavior as both string and dictionary representations

• Introduce abstract record hierarchy for flexible prompt behavior configuration

• Enable per-prompt-type behavior specification via UnhandledPromptBehaviorMultiOption

• Maintain backward compatibility with existing enum-based API

---

Diagram Walkthrough

flowchart LR
  A["UnhandledPromptBehavior enum"] -->|implicit conversion| B["UnhandledPromptBehaviorOption"]
  B -->|Single| C["UnhandledPromptBehaviorSingleOption"]
  B -->|Multi| D["UnhandledPromptBehaviorMultiOption"]
  C -->|serializes to| E["string capability"]
  D -->|serializes to| F["dictionary capability"]

Loading

File Walkthrough

Relevant files

Enhancement

DriverOptions.cs Add flexible prompt behavior option types with dual serialization dotnet/src/webdriver/DriverOptions.cs Introduced abstract record UnhandledPromptBehaviorOption with two sealed implementations: UnhandledPromptBehaviorSingleOption (for string representation) and UnhandledPromptBehaviorMultiOption (for dictionary representation with per-prompt-type settings) Added implicit operator and factory methods (Single(), Multi()) for convenient instantiation Changed UnhandledPromptBehavior property type from enum to nullable UnhandledPromptBehaviorOption Refactored serialization logic in GenerateDesiredCapabilities() to handle both single and multi-option cases, converting to appropriate capability format Updated merge conflict detection to use null checks instead of enum comparison Extracted enum-to-string conversion into local helper function UnhandledPromptBehaviorToString() +79/-18

---

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
🟡	🎫 #16102 🟢 Allow setting unhandledPromptBehavior as a dictionary/map per spec for BiDi/Chrome 137+. Preserve ability to set unhandledPromptBehavior as a single value (legacy enum) for backward compatibility. Ensure options serialization outputs correct wire values (strings or map) for capabilities. Avoid requiring users to use AdditionalOption workaround or internal DesiredCapabilities. Behavior should work in .NET bindings (C#) without breaking compilation for existing users. ⚪ Validate in real Chrome 137+ with BiDi that alerts behave per provided map (runtime/browser check).
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: No auditing: The new serialization logic for UnhandledPromptBehavior does not include any audit logging of critical actions, but this may be out of scope for a client options class. Referred Code [return: NotNullIfNotNull(nameof(behavior))] static string? UnhandledPromptBehaviorToString(UnhandledPromptBehavior? behavior) => behavior switch { Selenium.UnhandledPromptBehavior.Ignore => "ignore", Selenium.UnhandledPromptBehavior.Accept => "accept", Selenium.UnhandledPromptBehavior.Dismiss => "dismiss", Selenium.UnhandledPromptBehavior.AcceptAndNotify => "accept and notify", Selenium.UnhandledPromptBehavior.DismissAndNotify => "dismiss and notify", _ => null }; if (this.UnhandledPromptBehavior is UnhandledPromptBehaviorSingleOption singleOption) { var stringValue = UnhandledPromptBehaviorToString(singleOption.Value); if (stringValue is not null) { capabilities.SetCapability(CapabilityType.UnhandledPromptBehavior, stringValue); } } else if (this.UnhandledPromptBehavior is UnhandledPromptBehaviorMultiOption multiOption) ... (clipped 33 lines)
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Missing validation: Mapping functions accept nullable behaviors and silently skip invalid/unknown values without error or logging, which could hide misconfigurations. Referred Code [return: NotNullIfNotNull(nameof(behavior))] static string? UnhandledPromptBehaviorToString(UnhandledPromptBehavior? behavior) => behavior switch { Selenium.UnhandledPromptBehavior.Ignore => "ignore", Selenium.UnhandledPromptBehavior.Accept => "accept", Selenium.UnhandledPromptBehavior.Dismiss => "dismiss", Selenium.UnhandledPromptBehavior.AcceptAndNotify => "accept and notify", Selenium.UnhandledPromptBehavior.DismissAndNotify => "dismiss and notify", _ => null }; if (this.UnhandledPromptBehavior is UnhandledPromptBehaviorSingleOption singleOption) { var stringValue = UnhandledPromptBehaviorToString(singleOption.Value); if (stringValue is not null) { capabilities.SetCapability(CapabilityType.UnhandledPromptBehavior, stringValue); } } else if (this.UnhandledPromptBehavior is UnhandledPromptBehaviorMultiOption multiOption) ... (clipped 33 lines)
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Input validation: The new API accepts nullable option values and constructs a dictionary without explicit validation of keys/values, potentially allowing unsupported configurations to pass silently. Referred Code { Dictionary<string, string> multiOptionDictionary = []; if (multiOption.Alert is not null) { multiOptionDictionary["alert"] = UnhandledPromptBehaviorToString(multiOption.Alert); } if (multiOption.Confirm is not null) { multiOptionDictionary["confirm"] = UnhandledPromptBehaviorToString(multiOption.Confirm); } if (multiOption.Prompt is not null) { multiOptionDictionary["prompt"] = UnhandledPromptBehaviorToString(multiOption.Prompt); } if (multiOption.BeforeUnload is not null) { multiOptionDictionary["beforeUnload"] = UnhandledPromptBehaviorToString(multiOption.BeforeUnload); ... (clipped 12 lines)
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	✅ The solution introduces a breaking change Suggestion Impact: The commit adjusts the new UnhandledPromptBehaviorOption approach to be more backward-friendly by setting a default value (Default) and tightening handling to non-null enum values, reducing source-breaking risk for readers. It retains the Option type but mitigates the breaking change concerns, reflecting responsiveness to the suggestion. code diff: @@ -195,7 +126,7 @@ /// Gets or sets the value for describing how unexpected alerts are to be handled in the browser. /// Defaults to <see cref="UnhandledPromptBehavior.Default"/>. /// </summary> - public UnhandledPromptBehaviorOption? UnhandledPromptBehavior { get; set; } + public UnhandledPromptBehaviorOption? UnhandledPromptBehavior { get; set; } = Selenium.UnhandledPromptBehavior.Default; /// <summary> /// Gets or sets the value for describing how the browser is to wait for pages to load in the browser. @@ -334,7 +265,7 @@ return result; } - if (this.UnhandledPromptBehavior is not null && other.UnhandledPromptBehavior is not null) + if (this.UnhandledPromptBehavior != other.UnhandledPromptBehavior) { result.IsMergeConflict = true; result.MergeConflictOptionName = "UnhandledPromptBehavior"; @@ -539,51 +470,47 @@ capabilities.SetCapability(CapabilityType.PageLoadStrategy, pageLoadStrategySetting); } - [return: NotNullIfNotNull(nameof(behavior))] - static string? UnhandledPromptBehaviorToString(UnhandledPromptBehavior? behavior) => behavior switch + static string UnhandledPromptBehaviorToString(UnhandledPromptBehavior behavior) => behavior switch { Selenium.UnhandledPromptBehavior.Ignore => "ignore", Selenium.UnhandledPromptBehavior.Accept => "accept", Selenium.UnhandledPromptBehavior.Dismiss => "dismiss", Selenium.UnhandledPromptBehavior.AcceptAndNotify => "accept and notify", Selenium.UnhandledPromptBehavior.DismissAndNotify => "dismiss and notify", - _ => null + _ => throw new ArgumentOutOfRangeException(nameof(behavior), $"UnhandledPromptBehavior value '{behavior}' is not recognized."), }; - if (this.UnhandledPromptBehavior is UnhandledPromptBehaviorSingleOption singleOption) + if (this.UnhandledPromptBehavior is UnhandledPromptBehaviorSingleOption singleOption && singleOption.Value != Selenium.UnhandledPromptBehavior.Default) { var stringValue = UnhandledPromptBehaviorToString(singleOption.Value); - if (stringValue is not null) - { - capabilities.SetCapability(CapabilityType.UnhandledPromptBehavior, stringValue); - } + capabilities.SetCapability(CapabilityType.UnhandledPromptBehavior, stringValue); } else if (this.UnhandledPromptBehavior is UnhandledPromptBehaviorMultiOption multiOption) { Dictionary<string, string> multiOptionDictionary = []; - if (multiOption.Alert is not null) + if (multiOption.Alert is not Selenium.UnhandledPromptBehavior.Default) { multiOptionDictionary["alert"] = UnhandledPromptBehaviorToString(multiOption.Alert); } - if (multiOption.Confirm is not null) + if (multiOption.Confirm is not Selenium.UnhandledPromptBehavior.Default) { multiOptionDictionary["confirm"] = UnhandledPromptBehaviorToString(multiOption.Confirm); } - if (multiOption.Prompt is not null) + if (multiOption.Prompt is not Selenium.UnhandledPromptBehavior.Default) { multiOptionDictionary["prompt"] = UnhandledPromptBehaviorToString(multiOption.Prompt); } - if (multiOption.BeforeUnload is not null) + if (multiOption.BeforeUnload is not Selenium.UnhandledPromptBehavior.Default) { multiOptionDictionary["beforeUnload"] = UnhandledPromptBehaviorToString(multiOption.BeforeUnload); } - if (multiOption.Default is not null) + if (multiOption.Default is not Selenium.UnhandledPromptBehavior.Default) { multiOptionDictionary["default"] = UnhandledPromptBehaviorToString(multiOption.Default); } The suggestion highlights that changing the UnhandledPromptBehavior property's type is a breaking change for users who read its value. It recommends adding a new property for the dictionary-based functionality to ensure backward compatibility. Examples: dotnet/src/webdriver/DriverOptions.cs [198] public UnhandledPromptBehaviorOption? UnhandledPromptBehavior { get; set; } Solution Walkthrough: Before: // In DriverOptions.cs public class DriverOptions { public UnhandledPromptBehavior UnhandledPromptBehavior { get; set; } = UnhandledPromptBehavior.Default; // ... } // Example user code (compiles) public void ConfigureDriver(DriverOptions options) { // Reading the property is straightforward UnhandledPromptBehavior behavior = options.UnhandledPromptBehavior; if (behavior == UnhandledPromptBehavior.Ignore) { // ... } } After: // In DriverOptions.cs public class DriverOptions { public UnhandledPromptBehaviorOption? UnhandledPromptBehavior { get; set; } // ... } // Example user code (breaks compilation) public void ConfigureDriver(DriverOptions options) { // This line no longer compiles due to type mismatch // UnhandledPromptBehavior behavior = options.UnhandledPromptBehavior; // User must now add type checking and casting if (options.UnhandledPromptBehavior is UnhandledPromptBehaviorSingleOption single) { UnhandledPromptBehavior? behavior = single.Value; // ... } } Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies a critical source-breaking change in the public API by altering the type of the UnhandledPromptBehavior property, which contradicts the PR's claim of being non-breaking.	High
Learned best practice	✅ Validate mapped capability values Suggestion Impact: The commit changed UnhandledPromptBehavior handling to be non-nullable with defaults and made the mapping function throw on unknown values, and it only adds entries when not Default. This achieves the validation intent, though it didn't introduce the exact TryAdd helper. code diff: - [return: NotNullIfNotNull(nameof(behavior))] - static string? UnhandledPromptBehaviorToString(UnhandledPromptBehavior? behavior) => behavior switch + static string UnhandledPromptBehaviorToString(UnhandledPromptBehavior behavior) => behavior switch { Selenium.UnhandledPromptBehavior.Ignore => "ignore", Selenium.UnhandledPromptBehavior.Accept => "accept", Selenium.UnhandledPromptBehavior.Dismiss => "dismiss", Selenium.UnhandledPromptBehavior.AcceptAndNotify => "accept and notify", Selenium.UnhandledPromptBehavior.DismissAndNotify => "dismiss and notify", - _ => null + _ => throw new ArgumentOutOfRangeException(nameof(behavior), $"UnhandledPromptBehavior value '{behavior}' is not recognized."), }; - if (this.UnhandledPromptBehavior is UnhandledPromptBehaviorSingleOption singleOption) + if (this.UnhandledPromptBehavior is UnhandledPromptBehaviorSingleOption singleOption && singleOption.Value != Selenium.UnhandledPromptBehavior.Default) { var stringValue = UnhandledPromptBehaviorToString(singleOption.Value); - if (stringValue is not null) - { - capabilities.SetCapability(CapabilityType.UnhandledPromptBehavior, stringValue); - } + capabilities.SetCapability(CapabilityType.UnhandledPromptBehavior, stringValue); } else if (this.UnhandledPromptBehavior is UnhandledPromptBehaviorMultiOption multiOption) { Dictionary<string, string> multiOptionDictionary = []; - if (multiOption.Alert is not null) + if (multiOption.Alert is not Selenium.UnhandledPromptBehavior.Default) { multiOptionDictionary["alert"] = UnhandledPromptBehaviorToString(multiOption.Alert); } - if (multiOption.Confirm is not null) + if (multiOption.Confirm is not Selenium.UnhandledPromptBehavior.Default) { multiOptionDictionary["confirm"] = UnhandledPromptBehaviorToString(multiOption.Confirm); } - if (multiOption.Prompt is not null) + if (multiOption.Prompt is not Selenium.UnhandledPromptBehavior.Default) { multiOptionDictionary["prompt"] = UnhandledPromptBehaviorToString(multiOption.Prompt); } - if (multiOption.BeforeUnload is not null) + if (multiOption.BeforeUnload is not Selenium.UnhandledPromptBehavior.Default) { multiOptionDictionary["beforeUnload"] = UnhandledPromptBehaviorToString(multiOption.BeforeUnload); } - if (multiOption.Default is not null) + if (multiOption.Default is not Selenium.UnhandledPromptBehavior.Default) { multiOptionDictionary["default"] = UnhandledPromptBehaviorToString(multiOption.Default); } Validate that mapped strings are non-null before adding to the dictionary to prevent invalid capability values. Optionally throw a clear error for unknown enum values. dotnet/src/webdriver/DriverOptions.cs [566-589] -if (multiOption.Alert is not null) +void TryAdd(IDictionary<string, string> dict, string key, UnhandledPromptBehavior? value) { - multiOptionDictionary["alert"] = UnhandledPromptBehaviorToString(multiOption.Alert); + var str = UnhandledPromptBehaviorToString(value); + if (str is null && value is not null) + { + throw new ArgumentOutOfRangeException(nameof(value), $"Unsupported UnhandledPromptBehavior value '{value}'."); + } + if (str is not null) + { + dict[key] = str; + } } -if (multiOption.Confirm is not null) -{ - multiOptionDictionary["confirm"] = UnhandledPromptBehaviorToString(multiOption.Confirm); -} +TryAdd(multiOptionDictionary, "alert", multiOption.Alert); +TryAdd(multiOptionDictionary, "confirm", multiOption.Confirm); +TryAdd(multiOptionDictionary, "prompt", multiOption.Prompt); +TryAdd(multiOptionDictionary, "beforeUnload", multiOption.BeforeUnload); +TryAdd(multiOptionDictionary, "default", multiOption.Default); -if (multiOption.Prompt is not null) -{ - multiOptionDictionary["prompt"] = UnhandledPromptBehaviorToString(multiOption.Prompt); -} - -if (multiOption.BeforeUnload is not null) -{ - multiOptionDictionary["beforeUnload"] = UnhandledPromptBehaviorToString(multiOption.BeforeUnload); -} - -if (multiOption.Default is not null) -{ - multiOptionDictionary["default"] = UnhandledPromptBehaviorToString(multiOption.Default); -} - [Suggestion processed] Suggestion importance[1-10]: 6 __ Why: Relevant best practice - Guard external API-facing option mapping with validation to avoid null or invalid values leaking into capabilities.	Low
General	✅ Use init-only setters for record Suggestion Impact: The UnhandledPromptBehaviorMultiOption record (and related option types) was removed entirely and the UnhandledPromptBehavior handling was refactored to use a different type (UserPromptHandler) with capability generation via ToCapabilities(), making the suggested init-setter change moot. code diff: -public abstract record UnhandledPromptBehaviorOption -{ - public static implicit operator UnhandledPromptBehaviorOption(UnhandledPromptBehavior? value) - => Single(value); - - public static UnhandledPromptBehaviorOption Single(UnhandledPromptBehavior? value) - => new UnhandledPromptBehaviorSingleOption(value); - - public static UnhandledPromptBehaviorOption Multi(UnhandledPromptBehavior? alert = null, - UnhandledPromptBehavior? confirm = null, - UnhandledPromptBehavior? prompt = null, - UnhandledPromptBehavior? beforeUnload = null, - UnhandledPromptBehavior? @default = null) - => new UnhandledPromptBehaviorMultiOption() with { Alert = alert, Confirm = confirm, Prompt = prompt, BeforeUnload = beforeUnload, Default = @default }; -} - -public sealed record UnhandledPromptBehaviorSingleOption(UnhandledPromptBehavior? Value) : UnhandledPromptBehaviorOption; - -public sealed record UnhandledPromptBehaviorMultiOption : UnhandledPromptBehaviorOption -{ - public UnhandledPromptBehavior? Alert { get; set; } - - public UnhandledPromptBehavior? Confirm { get; set; } - - public UnhandledPromptBehavior? Prompt { get; set; } - - public UnhandledPromptBehavior? BeforeUnload { get; set; } - - public UnhandledPromptBehavior? Default { get; set; } -} - Replace the set accessors with init accessors in the UnhandledPromptBehaviorMultiOption record to make its properties immutable after initialization. dotnet/src/webdriver/DriverOptions.cs [47-58] public sealed record UnhandledPromptBehaviorMultiOption : UnhandledPromptBehaviorOption { - public UnhandledPromptBehavior? Alert { get; set; } + public UnhandledPromptBehavior? Alert { get; init; } - public UnhandledPromptBehavior? Confirm { get; set; } + public UnhandledPromptBehavior? Confirm { get; init; } - public UnhandledPromptBehavior? Prompt { get; set; } + public UnhandledPromptBehavior? Prompt { get; init; } - public UnhandledPromptBehavior? BeforeUnload { get; set; } + public UnhandledPromptBehavior? BeforeUnload { get; init; } - public UnhandledPromptBehavior? Default { get; set; } + public UnhandledPromptBehavior? Default { get; init; } } [Suggestion processed] Suggestion importance[1-10]: 5 __ Why: The suggestion correctly points out that using init setters for a record's properties enhances immutability, which is idiomatic for records and improves code quality and maintainability.	Low
Update

[RenderMichael]

A breaking change like this should be well-tested. Could we add tests here?

[nvborisenko]

A breaking change like this should be well-tested. Could we add tests here?

I have no capacity to test the functionality which was not indented to be tested. You can "request changes", please propose.

[RenderMichael]

A breaking change like this should be well-tested. Could we add tests here?

I have no capacity to test the functionality which was not indented to be tested. You can "request changes", please propose.

I propose new tests for this functionality.

[nvborisenko]

Existing tests don't satisfy you? You ask me to increase the coverage. But what is coverage?

[nvborisenko]

@RenderMichael welcome to #15536

UPD: is it only one concern from your side?

[YevgeniyShunevych]

Generally, looks good, @nvborisenko. What I don't like is a nullability of properties and parameters (UnhandledPromptBehaviorOption?, UnhandledPromptBehavior?). If I understand correctly, for UnhandledPromptBehavior? null and Default values are equivalent. So 2 states basically indicate the same state. So why not to make it non-nullable and use Default as a default. I would also rename UnhandledPromptBehavior.Default to None, as it is not clear what "Default" means, but "None" means no behavior is specified.

[Copilot]

Pull request overview

Adds a new .NET representation for the W3C unhandledPromptBehavior capability so it can serialize either as a single string value or as a per-prompt-type dictionary, addressing BiDi/Chrome 137+ requirements.

Changes:

• Introduces OpenQA.Selenium.UserPromptHandler (with Uniform and PerPromptType) and moves/updates UnhandledPromptBehavior enum (with Default marked obsolete).
• Updates DriverOptions.UnhandledPromptBehavior to use the new handler type and serializes via ToCapabilities().
• Updates alert-related tests to cover null and per-type handler usage; minor whitespace cleanup.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
dotnet/src/webdriver/DriverOptions.cs	Switches UnhandledPromptBehavior to the new handler type and updates capability serialization + merge-conflict logic.
dotnet/src/webdriver/UserPromptHandler.cs	Adds the new handler model and serialization (string vs map) for unhandledPromptBehavior.
dotnet/test/webdriver/UnexpectedAlertBehaviorTests.cs	Updates tests to use null and per-type handler variants.
dotnet/test/webdriver/AlertsTests.cs	Removes trailing whitespace at EOF.

Comments suppressed due to low confidence (1)

dotnet/src/webdriver/DriverOptions.cs:267

• GetMergeResult currently flags a merge conflict whenever the two UnhandledPromptBehavior values are not equal. This is stricter than the previous behavior and will incorrectly reject scenarios where only one options object sets the capability (e.g., must-match leaves it unset/null and first-match sets it). It will also treat null and new UserPromptHandler.Uniform(UnhandledPromptBehavior.Default) as conflicting even though both serialize to “unset”. Consider only reporting a conflict when both sides specify a non-null capability value (ideally based on the serialized capability via ToCapabilities()).

        if (this.UnhandledPromptBehavior != other.UnhandledPromptBehavior)
        {
            result.IsMergeConflict = true;
            result.MergeConflictOptionName = "UnhandledPromptBehavior";
            return result;