Selection by Name - SeleniumBase for Rust

A program turns built-in plugins, and plugins of its own registry, on by name: from the [plugins] table of the settings file, the SB_PLUGINS variable, the command-line flags --plugin and --plugin-opt, or code. The names and options are a PluginSelection; the launch builders and plugin_host::build_with turn it into a PluginSet (Host). The user guide is Choosing plugins. PluginSelection and PLUGINS_ENV are always compiled, so a settings file with a [plugins] table parses in every build; the items marked “Feature: plugins” need that feature.

PluginSelection#

struct seleniumbase_rs::config::plugins::PluginSelection

#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]pub struct PluginSelection {    // private: `enable`, the names in order, and every other key of the    // table, the options of the plugin of that name}

The plugins to turn on, by name, and their options. It is the [plugins] table of the settings file (the plugins object of a JSON settings file): enable lists the names in the order their plugins are added, and a table named like a plugin holds that plugin’s options.

sbase_config.toml

[plugins]enable = ["shield", "block-resources"][plugins.shield]level = "strict"

The same value comes from SB_PLUGINS, from the flags through apply_flags, or from code with enable and with_options. Options are kept as JSON values.

PluginSelection::new#

#[must_use]pub fn new() -> Self

returnPluginSelection#

A selection that turns nothing on.

PluginSelection::from_list#

#[must_use]pub fn from_list(list: &str) -> Self

list&strrequired#

A comma-separated list of names, as SB_PLUGINS holds it, such as shield,block-resources.

returnPluginSelection#

The selection of those names, with no options. Spaces around a name and empty entries are ignored: " shield, ,block-resources," gives ["shield", "block-resources"].

PluginSelection::enable#

#[must_use]pub fn enable(mut self, name: impl Into<String>) -> Self

nameimpl Into<String>required#

A plugin name.

returnPluginSelection#

The selection with name after the plugins already enabled. A name enabled twice is kept twice, and the build then refuses it (already in the set).

PluginSelection::with_options#

#[must_use]pub fn with_options(mut self, name: impl Into<String>, options: Value) -> Self

nameimpl Into<String>required#

The plugin the options are for.

optionsserde_json::Valuerequired#

What the plugin’s option table holds, usually a JSON object.

returnPluginSelection#

The selection with these options, replacing earlier options of name.

The plugin must also be enabled: options for a plugin that is not are an error when the selection is built.

PluginSelection::set_enabled_from_list#

pub fn set_enabled_from_list(&mut self, list: &str)

list&strrequired#

A comma-separated list, as SB_PLUGINS holds it.

Replaces the enabled names with the list, as SB_PLUGINS does. The options of the plugins the list still names stay; the options of the others are dropped, so they do not fail the build as stray options. An empty list turns every plugin off.

PluginSelection::set_enabled_keeping_options#

pub fn set_enabled_keeping_options(&mut self, list: &str)

list&strrequired#

A comma-separated list.

set_enabled_from_list that keeps every option table. A program that applies command-line flags after the variable uses it, so a plugin the flags turn on again keeps the options of the settings file, and calls prune_unused once the flags are applied.

PluginSelection::prune_unused#

pub fn prune_unused(&mut self)

Drops the options of the plugins that are not enabled.

PluginSelection::extend#

pub fn extend(&mut self, other: &Self)

other&PluginSelectionrequired#

Another selection.

Adds the plugins of other after this selection’s, and takes its options over those of the same name. LaunchOptionsBuilder::plugin_selection uses it.

PluginSelection::enable_once#

pub fn enable_once(&mut self, name: impl Into<String>)

nameimpl Into<String>required#

A plugin name.

Adds name after the plugins already enabled, unless it is enabled already, in which case it keeps its place.

PluginSelection::apply_flags#

pub fn apply_flags<N, O>(&mut self, plugins: &[N], options: &[O]) -> Result<(), SeleniumBaseError>where    N: AsRef<str>,    O: AsRef<str>,

plugins&[impl AsRef<str>]required#

The values of every --plugin NAME, in order.

options&[impl AsRef<str>]required#

The values of every --plugin-opt NAME.KEY=VALUE, in order.

returnResult<(), SeleniumBaseError>#

SeleniumBaseError::InvalidConfig for a plugin name that is empty or holds a space, a tab or a comma; an option that is not NAME.KEY=VALUE with a TOML VALUE; an option of a plugin that nothing turns on; and the same option given twice.

Applies the command line to a selection read from the settings file and SB_PLUGINS, so the precedence is the command line over SB_PLUGINS over the file. Each --plugin name is added with enable_once. Each --plugin-opt sets one option of one plugin: NAME ends at the first ., KEY at the first =, and VALUE is a TOML value (so a string is quoted: shield.level="strict"). It replaces the same key from the file and keeps the plugin’s other options. A TOML date, or a float with no JSON form, is refused.

PluginSelection::to_list#

#[must_use]pub fn to_list(&self) -> String

returnString#

The enabled names joined with commas: the value of SB_PLUGINS that enables the same plugins, the inverse of from_list.

PluginSelection::enabled#

#[must_use]pub fn enabled(&self) -> &[String]

return&[String]#

The names of the plugins to enable, in order.

PluginSelection::options_of#

#[must_use]pub fn options_of(&self, name: &str) -> Option<&Value>

name&strrequired#

A plugin name.

returnOption<&Value>#

The options given for that plugin, if any.

PluginSelection::is_empty#

#[must_use]pub fn is_empty(&self) -> bool

returnbool#

Whether the selection turns nothing on and holds no options.

PluginSelection::ensure_supported#

pub fn ensure_supported(&self) -> Result<(), SeleniumBaseError>

returnResult<(), SeleniumBaseError>#

Ok(()) when the build has the feature plugins or the selection is empty; otherwise SeleniumBaseError::InvalidConfig naming what was asked for and saying to rebuild with --features plugins-builtin (or --features plugins for the API alone), or to remove the [plugins] table and SB_PLUGINS.

A program that asked for privacy hardening and silently runs without it is worse than one that stops: Settings::load calls it after SB_PLUGINS is applied.

PLUGINS_ENV#

const seleniumbase_rs::config::plugins::PLUGINS_ENV

pub const PLUGINS_ENV: &str = "SB_PLUGINS";

The environment variable that names the plugins to turn on, as a comma-separated list such as shield,block-resources. It replaces the names of the file’s enable, and carries names only. Unlike the other SB_* variables, an empty value is an answer: SB_PLUGINS= turns every plugin off.

Settings::plugins#

field seleniumbase_rs::config::settings::Settings::plugins

#[serde(default, skip_serializing_if = "PluginSelection::is_empty")]pub plugins: PluginSelection,

The [plugins] table of the settings file with SB_PLUGINS on top, as Settings::load and Settings::load_from read it. A build without the feature plugins refuses a non-empty selection when it loads the settings. Turn it into plugins with LaunchOptionsBuilder::plugin_selection or BrowserConfig::with_plugin_selection.

Settings::load_plugin_selection#

fn seleniumbase_rs::config::settings::Settings::load_plugin_selection

pub fn load_plugin_selection<P: AsRef<Path>>(    path: Option<P>,) -> Result<PluginSelection, SeleniumBaseError>

pathOption<impl AsRef<Path>>required#

A settings file (TOML for a name that ends in .toml, JSON otherwise), or None for the global file of the current folder: the first of sbase_config.toml, .sbase_config.toml and .sbase_config that exists.

returnResult<PluginSelection, SeleniumBaseError>#

The [plugins] table of the file, with SB_PLUGINS on top. With None and no settings file in the folder, the table is empty. SeleniumBaseError::InvalidConfig when the file cannot be read or parsed, or its table is not a plugin selection.

Only the plugin part of the file is read, so a value that is wrong for a browser (headless = "maybe") or an invalid SB_HEADLESS does not stop a program that only needs the plugins. Whether this build can run plugins is not checked: call ensure_supported on the result, or build it.

Settings::load_plugin_table#

fn seleniumbase_rs::config::settings::Settings::load_plugin_table

pub fn load_plugin_table<P: AsRef<Path>>(    path: Option<P>,) -> Result<PluginSelection, SeleniumBaseError>

pathOption<impl AsRef<Path>>required#

As for load_plugin_selection.

returnResult<PluginSelection, SeleniumBaseError>#

The [plugins] table of the file and nothing else: SB_PLUGINS is not read.

For a program that applies SB_PLUGINS and the command line itself, and so can tell which plugins the file turned on, as PluginChoice::load does.

PluginChoice#

struct seleniumbase_rs::cli::plugin_cmd::PluginChoice

#[derive(Debug, Clone, PartialEq)]pub struct PluginChoice { /* private: selection, origins */ }

The plugins an operator chose for a program: what the settings file, SB_PLUGINS and the command line turn on and configure, and where each name came from. sbrs, sbrs devtools and sbrs-mcp build one, so the precedence is the same for all of them.

PluginChoice::load#

pub fn load<P, N, O>(    config: Option<P>,    plugins: &[N],    options: &[O],) -> Result<Self, SeleniumBaseError>where    P: AsRef<Path>,    N: AsRef<str>,    O: AsRef<str>,

configOption<impl AsRef<Path>>required#

The file --config names, or None for the settings file of the current folder.

plugins&[impl AsRef<str>]required#

The --plugin values.

options&[impl AsRef<str>]required#

The --plugin-opt values.

returnResult<PluginChoice, SeleniumBaseError>#

The choice, or SeleniumBaseError::InvalidConfig for a file that cannot be read and for a flag apply_flags refuses.

Reads the [plugins] table of the file (load_plugin_table), replaces the names with SB_PLUGINS when it is set (keeping the options), applies the flags, and then, when the variable was set, drops the options of plugins nothing turns on. Each enabled name’s origin is the strongest place that named it: the command line, then SB_PLUGINS, then the file.

PluginChoice::selection#

#[must_use]pub fn selection(&self) -> &PluginSelection

return&PluginSelection#

The plugins to turn on and their options.

PluginChoice::into_selection#

#[must_use]pub fn into_selection(self) -> PluginSelection

returnPluginSelection#

The selection, to hand to a builder.

PluginChoice::origins#

#[must_use]pub fn origins(&self) -> &[PluginOrigin]

return&[PluginOrigin]#

The enabled plugins in order, each with where its name was given.

PluginChoice::check#

pub fn check(&self) -> Result<(), SeleniumBaseError>

returnResult<(), SeleniumBaseError>#

check_selection, then (feature plugins) check_origins_with against the built-in registry; SeleniumBaseError::InvalidConfig naming the mistake.

The check a program makes before it starts a browser. A program with a registry of its own calls check_selection_with and check_origins_with with it instead.

PluginChoice::log#

pub fn log(&self)

Logs one INFO line for each enabled plugin with the place that enabled it, such as plugin enabled plugin=shield source="the settings file in the current folder", so a file in the folder cannot turn one on unseen.

PluginSource#

enum non_exhaustive seleniumbase_rs::cli::plugin_cmd::PluginSource

#[derive(Debug, Clone, Copy, PartialEq, Eq)]#[non_exhaustive]pub enum PluginSource {    ProjectFile,    ConfigFile,    Environment,    CommandLine,}impl PluginSource {    #[must_use]    pub fn describe(self) -> &'static str;}

Where the name of a plugin was given. The file is told apart by how it was found, because a file the operator names with --config is theirs, and the sbase_config.toml of the current folder may be a cloned project’s.

PluginSourceenum#

Show variants, with describe()

ProjectFileunit variant#

The [plugins] table of the settings file found in the current folder: the settings file in the current folder.

ConfigFileunit variant#

The [plugins] table of the file --config names: the settings file named by --config.

Environmentunit variant#

The SB_PLUGINS variable: SB_PLUGINS.

CommandLineunit variant#

A --plugin flag: --plugin.

PluginOrigin#

struct seleniumbase_rs::cli::plugin_cmd::PluginOrigin

#[derive(Debug, Clone, PartialEq, Eq)]pub struct PluginOrigin {    pub name: String,    pub source: PluginSource,}

nameString#

The plugin’s name.

sourcePluginSource#

Where the name came from; the strongest place wins.

check_selection#

fn seleniumbase_rs::cli::plugin_cmd::check_selection

pub fn check_selection(selection: &PluginSelection) -> Result<(), SeleniumBaseError>

selection&PluginSelectionrequired#

The selection to check.

returnResult<(), SeleniumBaseError>#

SeleniumBaseError::InvalidConfig (exit status 2) naming the mistake.

Checks a selection the way a command-line program should before it starts a browser: this build can run plugins (ensure_supported), and, with the feature plugins, check_selection_with against the built-in registry. Without the feature it refuses any non-empty selection.

check_selection_with#

fn Feature: plugins seleniumbase_rs::cli::plugin_cmd::check_selection_with

pub fn check_selection_with(    registry: &Registry,    selection: &PluginSelection,) -> Result<(), SeleniumBaseError>

registry&Registryrequired#

The plugins that can be named.

selection&PluginSelectionrequired#

The selection to check.

returnResult<(), SeleniumBaseError>#

SeleniumBaseError::InvalidConfig for an unknown name (no plugin named `NAME` (known: ...); `sbrs plugin list` shows them), and for every error plugin_host::build_with returns, as plugin `NAME`: REASON.

check_origins_with#

fn Feature: plugins seleniumbase_rs::cli::plugin_cmd::check_origins_with

pub fn check_origins_with(    registry: &Registry,    origins: &[PluginOrigin],) -> Result<(), SeleniumBaseError>

registry&Registryrequired#

The plugins that can be named.

origins&[PluginOrigin]required#

PluginChoice::origins.

returnResult<(), SeleniumBaseError>#

SeleniumBaseError::InvalidConfig naming the plugin, the capabilities and how to name the plugin yourself.

Refuses a plugin named only by the settings file of the current folder (PluginSource::ProjectFile) when its descriptor’s metadata (describe()) lists launch.proxy, artifacts.write or a host.* capability, in capabilities or optional. --plugin, SB_PLUGINS and a file named with --config count as the operator choosing. A name the registry does not have is left to check_selection_with.

apply_to_config#

fn seleniumbase_rs::cli::plugin_cmd::apply_to_config

pub fn apply_to_config(    config: BrowserConfig,    selection: &PluginSelection,) -> Result<BrowserConfig, SeleniumBaseError>

configBrowserConfigrequired#

The configuration of a WebDriver session.

selection&PluginSelectionrequired#

The plugins to give it.

returnResult<BrowserConfig, SeleniumBaseError>#

BrowserConfig::with_plugin_selection with the feature plugins; without it, SeleniumBaseError::InvalidConfig for a non-empty selection instead of leaving it out of the program.

list#

fn seleniumbase_rs::cli::plugin_cmd::list

#[must_use]pub fn list(selection: &PluginSelection) -> String

selection&PluginSelectionrequired#

What the file, the variable and the flags turn on.

returnString#

What sbrs plugin list prints: list_with of the built-in registry, or, in a build without the feature, No plugins: this build has no built-in plugin; rebuild with --features plugins-builtin (...).

list_with#

fn Feature: plugins seleniumbase_rs::cli::plugin_cmd::list_with

#[must_use]pub fn list_with(registry: &Registry, selection: &PluginSelection) -> String

registry&Registryrequired#

The plugins to list, in registry order.

selection&PluginSelectionrequired#

What is turned on.

returnString#

A table with the columns NAME, CATEGORY, ENABLED and SUMMARY, the names the selection enables that the registry does not have (Plugins enabled but not in this build: ...), and a line on how to turn one on.

info#

fn seleniumbase_rs::cli::plugin_cmd::info

pub fn info(name: &str, selection: &PluginSelection) -> Result<String, SeleniumBaseError>

name&strrequired#

A plugin name.

selection&PluginSelectionrequired#

What is turned on, with the options in effect.

returnResult<String, SeleniumBaseError>#

What sbrs plugin info NAME prints: info_with of the built-in registry. Without the feature, always SeleniumBaseError::InvalidConfig.

info_with#

fn Feature: plugins seleniumbase_rs::cli::plugin_cmd::info_with

pub fn info_with(    registry: &Registry,    name: &str,    selection: &PluginSelection,) -> Result<String, SeleniumBaseError>

registry&Registryrequired#

The plugins that can be named.

name&strrequired#

The plugin to describe.

selection&PluginSelectionrequired#

What is turned on, with the options in effect.

returnResult<String, SeleniumBaseError>#

The description, or SeleniumBaseError::InvalidConfig for a name the registry does not have, listing the ones it has.

The text (see the ResponseExample) gives the name and version, the summary, then one row each for category, enabled, phase (the declared phase, or the category’s), needs (the requirements in words), capabilities and optional (each with its risk and enforced or declared only), requires, conflicts, runs after, runs before, seals and options. The metadata comes from the descriptor (describe()); needs comes from the plugin built with the selection’s options, or with no options when it refuses them, and the options row then quotes the plugin’s own message. A note on declared only ends the text when a capability is declared only.