tests package

Submodules

tests.conftest module

Fixtures, configuration and helpers for tests.

class tests.conftest.FormatType(*values)

Bases: Enum

Sphinx document format types and their file extensions.

RST = '.rst'

MYST = '.md'

class tests.conftest.SphinxAppWrapper(app, format_type)

Bases: object

Wrapper around Sphinx application with additional testing methods.

classmethod create(format_type, tmp_path, return_srcdir=False)

Factory method to create a SphinxAppWrapper with given format.

Return type:

Generator[SphinxAppWrapper | tuple[SphinxAppWrapper, Path], None, None]

build_document(content)

Build a Sphinx document with content and return the HTML output.

Automatically detects the format from the app configuration and uses the appropriate file extension (.rst or .md).

Return type:

str | None

generate_test_content(test_case)

Generate content for a test case based on the app’s format type.

Return type:

str

tests.conftest.sphinx_app(request, tmp_path)

Create a Sphinx application for testing.

tests.conftest.sphinx_app_rst(tmp_path)

Create a Sphinx application for testing RST format only.

tests.conftest.sphinx_app_myst(tmp_path)

Create a Sphinx application for testing MyST format only.

tests.conftest.sphinx_app_myst_with_include(tmp_path)

Create a Sphinx application for testing MyST format with include files.

class tests.conftest.DirectiveTestCase(name, format_type=None, source_block=None, run_block=None, document=None, html_matches=None)

Bases: object

Test case data for directive tests.

name: str

format_type: FormatType | None = None

source_block: str | None = None

run_block: str | None = None

document: str | None = None

html_matches: Sequence[str] | str | None = None

supports_format(format_type)

Check if this test case supports the given format type.

Todo

Get rid of this method, and make the test case provide its own sphinx_app.

Return type:

bool

tests.conftest.python_block(*lines)

Build expected Python highlight block.

Return type:

str

tests.conftest.shell_block(*lines)

Build expected shell session block.

Return type:

str

tests.conftest.admonition_block(admonition_type, content)

Build expected admonition block.

Return type:

str

Args:

admonition_type: The type of admonition (note, tip, warning, etc.) content: The inner HTML content of the admonition (without the title)

tests.test_colorize module

tests.test_colorize.test_theme_definition()

Ensure we do not leave any property we would have inherited from cloup and logging primitives.

tests.test_colorize.test_extra_theme()

class tests.test_colorize.HashType(*values)

Bases: Enum

MD5 = 1

SHA1 = 2

BCRYPT = 3

class tests.test_colorize.Priority(*values)

Bases: Enum

LOW = 'low-priority'

HIGH = 'high-priority'

class tests.test_colorize.Port(*values)

Bases: IntEnum

HTTP = 80

HTTPS = 443

tests.test_colorize.test_option_highlight(opt, expected_outputs)

Test highlighting of all option variations: types, defaults, ranges, envvars, choices, flags, metavars, deprecated messages.

tests.test_colorize.test_skip_hidden_option()

Ensure hidden options are not highlighted.

tests.test_colorize.test_cross_ref_highlight_disabled()

When cross_ref_highlight is False, only structural elements are styled (bracket fields, deprecated messages, subcommands, choice metavars). Options, choices in free-form text, metavars, arguments, and CLI names are left plain.

tests.test_colorize.test_choice_does_not_override_default_style()

Choice cross-ref highlighting must not restyle text inside bracket fields.

When a default value contains a substring that matches a choice keyword (e.g. outline from rounded-outline), the choice style must not override the default value style. Regression test for the case where line-wrapping splits a hyphenated default so the second word starts a new line and passes the lookbehind.

tests.test_colorize.test_choice_collection_case(params, expected, forbidden)

Choice keywords must use the original-case strings from the type definition, not the normalized (lowercased) forms produced by normalize_choice().

tests.test_colorize.test_argument_highlight(params, expected, forbidden)

Argument metavars get the argument style, distinct from option metavars.

tests.test_colorize.test_no_false_positive_highlight(params, help_text, expected_present, expected_absent)

Verify that highlighting does not leak into compound words, URLs, dotted names, already-styled regions, or partial-word matches.

tests.test_colorize.test_parent_keywords_highlighted_in_subcommand_help()

Parent group names, options, and choices must be highlighted in subcommand help text.

tests.test_colorize.test_parent_choice_case_with_custom_metavar()

Parent choices with custom metavar must use original-case strings in subcommand help, not normalized (lowercased) forms.

tests.test_colorize.test_command_aliases_collected()

Command aliases are collected as keywords for highlighting.

tests.test_colorize.test_command_aliases_highlighted(invoke)

Aliases inside parenthetical groups are highlighted with the subcommand style.

tests.test_colorize.test_single_alias_highlighted(invoke)

A command with exactly one alias still gets highlighted.

tests.test_colorize.test_alias_no_false_positive_in_description(invoke)

An alias name appearing in a description must not be highlighted when it does not sit inside alias parentheses.

tests.test_colorize.test_alias_substring_not_highlighted(invoke)

An alias that is a substring of the subcommand name must not cause double-highlighting or partial matches.

tests.test_colorize.test_help_keywords_merge(base_kwargs, other_kwargs, checks)

HelpKeywords.merge() unions every field.

tests.test_colorize.test_help_keywords_subtract(base_kwargs, removals_kwargs, checks)

HelpKeywords.subtract() removes matching entries per field.

tests.test_colorize.test_extra_keywords_merged()

extra_keywords injects additional strings into the collected set.

tests.test_colorize.test_excluded_keywords_preserved_in_collection()

excluded_keywords does not remove from collect_keywords().

Exclusion is deferred to highlight_extra_keywords() so that choice metavars can be styled with the full choices set before the excluded choices are removed for cross-ref passes.

tests.test_colorize.test_excluded_keywords_via_constructor()

excluded_keywords can be passed through the ExtraCommand constructor.

tests.test_colorize.test_excluded_keywords_suppresses_highlighting()

Excluded keywords do not appear styled in the rendered help text.

tests.test_colorize.test_style_choice_metavar(metavar, choices, expected)

_style_choice_metavar styles known choices inside bracket-delimited metavar strings and returns None for non-bracket strings.

tests.test_colorize.test_multiple_choice_options_metavar_styled()

Each choice option gets its metavar individually styled.

tests.test_colorize.test_excluded_multiple_choices_styled_in_metavar_only()

Multiple excluded choices appear styled in their own metavar but not in free-text descriptions.

tests.test_colorize.test_excluded_keywords_inheritance(parent_excluded, child_excluded, word, expect_styled)

excluded_keywords propagate from parent groups to subcommands.

Parent choices are collected for subcommand help screens (cross-ref highlighting). The parent’s excluded_keywords must follow, otherwise excluded choices bleed into subcommand descriptions.

tests.test_colorize.test_excluded_keywords_grandparent_propagation()

excluded_keywords propagate through multiple nesting levels.

tests.test_colorize.test_excluded_keywords_plain_click_group_parent()

A plain click.Group parent without excluded_keywords does not crash.

tests.test_colorize.test_excluded_keywords_not_mutated()

Calling format_help must not mutate the command’s excluded_keywords.

tests.test_colorize.test_keyword_collection(invoke, assert_output_regex)

tests.test_colorize.test_standalone_color_option(invoke, option_decorator, param, expecting_colors, assert_output_regex)

Check color option values, defaults and effects on all things colored, including verbosity option.

tests.test_colorize.test_no_color_env_convention(invoke, env, env_expect_colors, param, param_expect_colors)

tests.test_colorize.test_integrated_color_option(invoke, param, expecting_colors, assert_output_regex)

Check effect of color option on all things colored, including verbosity option.

Also checks the color option in subcommands is inherited from parent context.

tests.test_colorize.test_substring_highlighting(content, patterns, expected, ignore_case)

tests.test_colorize.test_standalone_help_option(invoke, cmd_decorator, cmd_type, option_decorator)

tests.test_commands module

Test defaults of our custom commands, as well as their customizations and attached options, and how they interact with each others.

tests.test_commands.test_module_root_declarations()

Verify click_extra.__all__ is a superset of click and cloup.

Sort order is enforced by ruff (RUF022).

tests.test_commands.all_command_cli()

A CLI that is mixing all variations and flavors of subcommands.

tests.test_commands.test_unknown_option(invoke, all_command_cli)

tests.test_commands.test_short_option_error_enhancement(invoke, cli_options, args, exit_code, expected_fragment)

ExtraCommand.parse_args improves error messages for single-dash multi-character tokens whose first character is not a registered short option. Vanilla Click would split -dbgwrong character by character and report “No such option: -d”; we re-raise with the full token and close-match suggestions instead.

The enhancement must not interfere with valid -abc-style combining or with the per-character diagnostic when a later character is unknown.

Upstream context: https://github.com/pallets/click/issues/2779

tests.test_commands.test_unknown_command(invoke, all_command_cli)

tests.test_commands.test_required_command(invoke, all_command_cli, assert_output_regex)

tests.test_commands.test_group_help(invoke, all_command_cli, param, exit_code, assert_output_regex)

tests.test_commands.test_help_eagerness(invoke, all_command_cli, params, exit_code, expect_help, expect_empty_stderr, assert_output_regex)

See: https://click.palletsprojects.com/en/stable/click-concepts/#callback-evaluation-order

tests.test_commands.test_help_custom_name(invoke)

Removes the -h short option as we reserve it for a custom -h/--header option.

See: https://github.com/kdeldycke/mail-deduplicate/issues/762

tests.test_commands.test_subcommand_help(invoke, all_command_cli, cmd_id, param, assert_output_regex)

tests.test_commands.test_subcommand_execution(invoke, all_command_cli, cmd_id)

tests.test_commands.test_integrated_version_value(invoke, all_command_cli)

tests.test_commands.test_colored_bare_help(invoke, cmd_decorator, param)

Extra decorators are always colored.

Even when stripped of their default parameters, as reported in: https://github.com/kdeldycke/click-extra/issues/534 https://github.com/kdeldycke/click-extra/pull/543

tests.test_commands.test_duplicate_option(invoke)

See: - https://kdeldycke.github.io/click-extra/commands.html#change-default-options - https://github.com/kdeldycke/click-extra/issues/232

tests.test_commands.test_no_option_leaks_between_subcommands(invoke, assert_output_regex)

As reported in https://github.com/kdeldycke/click-extra/issues/489.

tests.test_commands.test_option_group_integration(invoke, assert_output_regex)

tests.test_commands.test_show_envvar_parameter(invoke, cmd_decorator, ctx_settings, expected_help)

tests.test_commands.test_raw_args(invoke)

Raw args are expected to be scoped in subcommands.

tests.test_commands.test_lazy_group(invoke, tmp_path, lazy_cmd_decorator, lazy_group_decorator)

Test extends the snippet from Click documentation.

tests.test_commands.test_decorator_overrides()

Ensure our decorators are not just alias of Click and Cloup ones.

tests.test_commands.test_decorator_cls_parameter(klass, should_raise)

Decorators accept custom cls parameters.

class tests.test_commands.TestHelpSubcommand

Bases: object

Tests for the auto-injected help subcommand.

test_help_shows_group_help(invoke)

mycli help produces the same output as mycli --help.

test_help_shows_subcommand_help(invoke)

mycli help greet matches mycli greet --help.

test_help_nested_group(invoke)

mycli help sub leaf resolves through nested groups.

test_help_nonexistent_subcommand(invoke)

mycli help nosuch reports an error.

test_help_subcommand_of_non_group(invoke)

mycli help leaf deeper errors when leaf is not a group.

test_help_disabled(invoke)

help_command=False suppresses auto-injection.

test_help_user_override(invoke)

User-defined help subcommand replaces the auto-injected one.

test_help_appears_in_listing(invoke)

The help subcommand is visible in the group’s command list.

test_help_search(invoke)

mycli help --search term finds matching subcommands.

test_help_search_no_match(invoke)

mycli help --search term with no matches.

test_help_in_all_command_cli(invoke, all_command_cli)

The help subcommand works on the fixture CLI.

test_help_for_subcommand_in_all_command_cli(invoke, all_command_cli)

help default-subcommand works on the fixture CLI.

tests.test_config module

tests.test_config.simple_config_cli()

tests.test_config.test_unset_conf(invoke, simple_config_cli)

tests.test_config.test_unset_conf_debug_message(invoke, simple_config_cli, assert_output_regex)

tests.test_config.test_conf_default_path(invoke, simple_config_cli)

tests.test_config.test_conf_default_pathlib_type(invoke, create_config)

Refs https://github.com/kdeldycke/click-extra/issues/1356

tests.test_config.test_conf_not_found(invoke, simple_config_cli, conf_path)

tests.test_config.test_conf_unparsable(invoke, simple_config_cli, create_config)

Explicit –config pointing to a file with garbage content.

tests.test_config.test_conf_empty_file(invoke, simple_config_cli, create_config)

Explicit –config pointing to an empty file.

tests.test_config.test_no_config_option(invoke, simple_config_cli, create_config)

tests.test_config.test_standalone_no_config_option(invoke)

@no_config_option cannot work without @config_option.

tests.test_config.test_strict_conf(invoke, create_config, conf_text, expect_error)

Strict mode rejects unknown params but accepts clean configs.

tests.test_config.test_conf_file_overrides_defaults(invoke, simple_config_cli, create_config, httpserver, conf_name, conf_text, conf_data, assert_output_regex)

tests.test_config.test_auto_envvar_conf(invoke, simple_config_cli, create_config, httpserver, conf_name, conf_text, conf_data)

tests.test_config.test_conf_file_overridden_by_cli_param(invoke, simple_config_cli, create_config, httpserver, conf_name, conf_text, conf_data)

tests.test_config.test_conf_metadata(invoke, create_config, httpserver, conf_name, conf_text, conf_data)

tests.test_config.test_conf_metadata_no_config(invoke)

ctx.meta entries are not set when –no-config skips loading.

tests.test_config.test_default_map_populated(invoke, create_config)

Verify default_map structure when config values match CLI parameters.

Complements test_conf_metadata which only checks the empty default_map case (where no config values match the CLI’s parameter structure).

tests.test_config.test_default_map_none_without_config(invoke)

Verify default_map is left alone when –no-config is used.

tests.test_config.test_nested_subcommand_config(invoke, create_config)

Config propagates through group -> subgroup -> leaf command.

tests.test_config.test_multiple_cli_shared_conf(invoke, create_config)

Two CLIs sharing the same configuration file.

Refs: https://github.com/kdeldycke/click-extra/issues/1277

tests.test_config.test_lazy_group_config(invoke, create_config, tmp_path)

Test that lazy groups work with config files.

Refs: https://github.com/kdeldycke/click-extra/issues/1332

tests.test_config.test_lazy_group_config_no_config_flag(invoke, create_config, tmp_path)

Test that –no-config works with lazy groups.

tests.test_config.test_file_pattern(file_format_patterns, expected_pattern)

Test the file_pattern property with different file format configurations.

tests.test_config.test_default_pattern_roaming_force_posix(roaming, force_posix, current_platform, expected_path, monkeypatch)

Test that roaming and force_posix affect the default pattern generation.

tests.test_config.test_default_pattern_xdg_config_home(force_posix, tmp_path, monkeypatch)

Test that default_pattern respects XDG_CONFIG_HOME on Linux.

tests.test_config.test_parent_patterns(tmp_path, search_parents, subdirs, create_file, expected_start)

tests.test_config.test_parent_patterns_with_magic_pattern(tmp_path, pattern_factory, expected_factory)

Test parent_patterns with glob patterns containing magic characters.

tests.test_config.test_parent_patterns_magic_no_search(tmp_path)

Magic pattern with search_parents=False yields only the original.

tests.test_config.test_parent_patterns_relative_path(tmp_path)

Test parent_patterns resolves relative paths to absolute.

tests.test_config.test_parent_patterns_stop_at_path(tmp_path)

stop_at as a path limits the parent directory walk.

tests.test_config.test_parent_patterns_stop_at_vcs(tmp_path, has_vcs, expected_bounded)

stop_at=VCS stops at VCS root, or walks to filesystem root if none.

tests.test_config.test_parent_patterns_inaccessible_directory(tmp_path)

Walk stops at an inaccessible directory.

tests.test_config.test_find_vcs_root(tmp_path, vcs_dir, expected)

Test _find_vcs_root with .git, .hg, and no VCS markers.

tests.test_config.test_config_option_default_no_config(invoke, create_config)

ConfigOption with default=NO_CONFIG disables autodiscovery.

tests.test_config.test_no_config_explicit_with_default_no_config(invoke)

–no-config still prints the skip message even when NO_CONFIG is the default.

tests.test_config.test_excluded_params(invoke, create_config)

Custom excluded_params prevents config values from being applied.

tests.test_config.test_included_params(invoke, create_config)

Only parameters in included_params are loaded from config.

tests.test_config.test_included_params_empty(invoke, create_config)

An empty included_params excludes all params from config.

tests.test_config.test_included_and_excluded_params_conflict()

Providing both included_params and excluded_params raises ValueError.

tests.test_config.test_multiple_files_matching_glob(invoke, create_config, tmp_path)

When multiple files match a glob, only the first parseable one is used.

tests.test_config.test_forced_flags_warnings(caplog)

Warnings fire when SPLIT, BRACE or NODIR flags are missing.

tests.test_config.test_brace_multi_format_search(invoke, tmp_path, ext)

All format extensions are found in the search directory.

Regression test: before BRACE expansion, only the first format in the default pattern got the directory prefix — others were searched in CWD.

tests.test_config.test_root_dir_parent_search_finds_non_toml(invoke, tmp_path)

Parent search with root_dir correctly finds non-TOML config in parents.

Before the root_dir refactoring, SPLIT patterns like *.toml|*.yaml only applied the directory prefix to the first sub-pattern. Now with root_dir, all sub-patterns are scoped to the correct directory.

tests.test_config.test_no_enabled_formats_raises()

ValueError raised when all formats are disabled.

tests.test_config.test_pyproject_toml_in_defaults()

ConfigOption() with default file_format_patterns includes PYPROJECT_TOML.

tests.test_config.test_pyproject_toml_tool_extraction(simple_config_cli)

parse_conf with PYPROJECT_TOML returns the [tool] subsection.

tests.test_config.test_pyproject_toml_no_tool_section(simple_config_cli)

pyproject.toml without [tool] returns empty dict.

tests.test_config.test_file_pattern_with_pyproject_toml()

Explicit file_format_patterns with PYPROJECT_TOML works.

tests.test_config.test_pyproject_toml_overrides_defaults(invoke, create_config)

End-to-end: a CLI with default formats reads from pyproject.toml.

tests.test_config.test_validate_config_valid(invoke, create_config)

–validate-config with a valid config file exits 0.

tests.test_config.test_validate_config_invalid_keys(invoke, create_config)

–validate-config with unrecognized keys exits 1.

tests.test_config.test_extensionless_config(invoke, create_config, default_pattern, expected_help_default)

Both broad and exact default patterns resolve the same .commandrc file.

The default parameter is printed as-is on the help screen, so an exact path is more informative than a broad glob, but both locate the same file.

tests.test_config.test_validate_config_unparsable(invoke, create_config)

–validate-config with garbage content exits 2.

tests.test_config.test_validate_config_missing_file(invoke, tmp_path)

–validate-config with a nonexistent file is caught by Click’s Path(exists=True).

tests.test_config.test_validate_config_requires_config_option(invoke, tmp_path)

–validate-config without @config_option raises RuntimeError.

tests.test_config.test_validate_config_pyproject_toml(invoke, create_config)

–validate-config works with pyproject.toml [tool.*] sections.

tests.test_config.test_default_subcommand_selection(invoke, create_config, cli_subcmd, expected, unexpected)

Config default is used when no subcommand given; CLI wins otherwise.

tests.test_config.test_default_subcommand_chained(invoke, create_config)

chain=True group runs multiple config-listed subcommands in order.

tests.test_config.test_default_subcommand_config_errors(invoke, create_config, conf_value, error_fragment)

Bad _default_subcommands values produce clear errors.

tests.test_config.test_default_subcommand_strict_mode_tolerance(invoke, create_config)

strict=True config with _default_subcommands doesn’t raise.

tests.test_config.test_default_subcommand_validate_config_tolerance(invoke, create_config)

–validate-config with _default_subcommands reports valid.

tests.test_config.test_default_subcommand_with_options(invoke, create_config)

Default subcommand receives its config-provided options.

tests.test_config.test_default_subcommand_no_config(invoke)

Normal behavior when no config file is loaded.

tests.test_config.test_default_subcommand_duplicates_warning(invoke, create_config)

Duplicate entries in _default_subcommands are deduplicated with a warning.

tests.test_config.test_default_subcommand_cli_override_debug_log(invoke, create_config)

Debug log emitted when CLI subcommands override config defaults.

tests.test_config.test_prepend_subcommand_selection(invoke, create_config, cli_subcmd, expected, unexpected)

Prepend fires regardless of whether a CLI subcommand is given.

tests.test_config.test_prepend_subcommand_with_defaults(invoke, create_config, cli_subcmd, expect_backup)

Prepend always applies; defaults only fire when no CLI subcommand given.

tests.test_config.test_prepend_subcommand_non_chained_error(invoke, create_config)

Error on non-chained group.

tests.test_config.test_prepend_subcommand_config_errors(invoke, create_config, conf_value, error_fragment)

Bad _prepend_subcommands values produce clear errors.

tests.test_config.test_prepend_subcommand_strict_mode_tolerance(invoke, create_config)

strict=True config with _prepend_subcommands doesn’t raise.

tests.test_config.test_prepend_subcommand_validate_config_tolerance(invoke, create_config)

–validate-config with _prepend_subcommands reports valid.

tests.test_config.test_prepend_subcommand_duplicates_warning(invoke, create_config)

Duplicate entries in _prepend_subcommands are deduplicated with a warning.

tests.test_config.test_prepend_subcommand_info_log(invoke, create_config)

INFO log emitted when _prepend_subcommands are injected.

tests.test_config.test_prepend_subcommand_multiple(invoke, create_config)

Multiple prepend subcommands run in order.

tests.test_config.test_sanity_broad_glob_narrow_format(caplog)

Broad glob + all-literal format patterns triggers a debug log.

tests.test_config.test_sanity_broad_glob_wildcard_format(caplog)

Broad glob + wildcard format patterns does NOT trigger the warning.

tests.test_config.test_sanity_disjoint_patterns(caplog)

Literal default not matching any format pattern triggers a debug log.

tests.test_config.test_sanity_disjoint_matching_literal(caplog)

Literal default matching a format pattern does NOT trigger the warning.

tests.test_config.test_sanity_format_extension_mismatch(caplog)

Format pattern extension mismatching its format triggers a debug log.

tests.test_config.test_sanity_format_extension_correct(caplog)

Correctly-matched format extension does NOT trigger the warning.

tests.test_config.test_sanity_dotfile_without_dotglob(caplog)

Dotfile in default without DOTGLOB triggers a debug log.

tests.test_config.test_sanity_dotfile_format_without_dotglob(caplog)

Dotfile in format patterns without DOTGLOB triggers a debug log.

tests.test_config.test_sanity_dotfile_with_dotglob(caplog)

Dotfile with DOTGLOB does NOT trigger the warning.

tests.test_config.test_sanity_no_explicit_default(caplog)

Without an explicit string default, checks 1/2/4 are skipped.

tests.test_config.test_sanity_format_mismatch_without_explicit_default(caplog)

Check 3 (format mismatch) runs even without explicit default.

tests.test_config.test_expand_dotted_keys(input_conf, expected)

tests.test_config.test_dotted_keys_in_config(invoke, simple_config_cli, create_config, conf_name, conf_text)

Dotted keys in config files are expanded into nested structures.

tests.test_config.test_expand_dotted_keys_conflict_warning(caplog, input_conf, warning_fragment)

Scalar/dict conflicts on the same key emit a warning.

tests.test_config.test_expand_dotted_keys_empty_segments(caplog, input_conf)

Dotted keys with empty segments are skipped with a warning.

tests.test_config.test_expand_dotted_keys_edge_cases(input_conf, expected)

tests.test_config.test_expand_dotted_keys_strict_conflict(input_conf, error_fragment)

Strict mode raises ValueError on type conflicts.

tests.test_config.test_expand_dotted_keys_strict_empty_segments(input_conf)

Strict mode raises ValueError on dotted keys with empty segments.

tests.test_config.test_strict_conf_dotted_key_conflict(invoke, create_config)

Strict mode rejects configs with dotted-key type conflicts.

tests.test_config.test_normalize_config_keys()

tests.test_config.test_config_schema_dataclass(invoke, create_config)

Dataclass schemas are auto-detected and instantiated with normalized keys.

tests.test_config.test_config_schema_callable(invoke, create_config)

A plain callable can be used as config_schema.

tests.test_config.test_config_schema_no_config_file(invoke)

When no config file is found, schema defaults are used.

tests.test_config.test_config_schema_dataclass_defaults(invoke, create_config)

Dataclass defaults are used for fields not present in the config file.

tests.test_config.test_fallback_sections(invoke, create_config)

Legacy section names are recognized with a deprecation warning.

tests.test_config.test_fallback_sections_prefers_current(invoke, create_config)

When both current and legacy sections exist, current wins.

tests.test_config.test_config_schema_multiple_formats(invoke, create_config, conf_name, conf_text)

Config schema works with YAML and JSON, not just TOML.

tests.test_config.test_config_schema_on_config_option_directly(invoke, create_config)

Config schema can be set directly on ConfigOption via the decorator.

tests.test_config.test_get_tool_config_defaults_to_current_context(invoke, create_config)

get_tool_config() works without passing ctx explicitly.

tests.test_config.test_flatten_config_keys()

tests.test_config.test_flatten_config_keys_with_normalize()

flatten + normalize maps nested kebab-case config to flat snake_case fields.

tests.test_config.test_config_schema_nested_toml(invoke, create_config)

Nested TOML sub-tables map to flat dataclass fields via flattening.

tests.test_config.test_config_schema_strict_rejects_unknown(invoke, create_config)

schema_strict=True raises ValueError on unrecognized config keys.

tests.test_config.test_config_schema_strict_passes_when_valid(invoke, create_config)

schema_strict=True does not raise when all config keys are known.

tests.test_config.test_config_schema_strict_with_nested(invoke, create_config)

schema_strict=True validates flattened keys from nested sub-tables.

tests.test_config.test_pyproject_toml_cwd_discovery(invoke, tmp_path, monkeypatch)

pyproject.toml in CWD is discovered automatically without –config.

tests.test_config.test_pyproject_toml_cwd_discovery_walks_up(invoke, tmp_path, monkeypatch)

pyproject.toml discovery walks up from CWD to parent directories.

tests.test_config.test_pyproject_toml_explicit_config_skips_cwd(invoke, create_config, tmp_path, monkeypatch)

Explicit –config skips CWD pyproject.toml discovery.

tests.test_config.test_flatten_config_keys_opaque()

opaque_keys stops flattening at matching key boundaries.

tests.test_config.test_flatten_config_keys_opaque_nested()

opaque_keys works at deeper nesting levels.

tests.test_config.test_schema_type_aware_flattening(invoke, create_config)

dict-typed dataclass fields stop flattening automatically.

tests.test_config.test_schema_field_metadata_config_path(invoke, create_config)

click_extra.config_path extracts a value at a dotted TOML path.

tests.test_config.test_schema_field_metadata_normalize_keys_true(invoke, create_config)

click_extra.normalize_keys defaults to True: keys are normalized.

tests.test_config.test_schema_nested_dataclass(invoke, create_config)

Nested dataclass fields are recursively instantiated.

tests.test_config.test_schema_nested_dataclass_with_opaque_fields(invoke, create_config)

Nested dataclass with dict-typed fields preserves opaque keys.

tests.test_config.test_schema_nested_dataclass_defaults(invoke, create_config)

Nested dataclass uses defaults when config section is absent.

tests.test_envvar module

tests.test_envvar.test_merge_envvar_ids(envvars, result)

tests.test_envvar.test_clean_envvar_id(env_name, clean_name)

tests.test_envvar.test_show_auto_envvar_help(invoke, cmd_decorator, option_help)

Check that the auto-generated envvar appears in the help screen with the extra variants.

Checks that https://github.com/pallets/click/issues/2483 is addressed.

tests.test_envvar.envvars_test_cases()

tests.test_envvar.test_auto_envvar_parsing(invoke, cmd_decorator, envvars, expected_flag)

This test highlights the way Click recognize and parse envvars.

It shows that the default behavior is not ideal, and covers how command improves the situation by normalizing the envvar name.

tests.test_envvar.test_env_copy()

tests.test_logging module

tests.test_logging.test_level_default_order()

tests.test_logging.test_root_logger_defaults()

Check our internal default is aligned to Python’s root logger.

tests.test_logging.test_integrated_verbosity_options(invoke, args, expected_level, assert_output_regex)

tests.test_logging.test_custom_verbosity_option_name(invoke, args, assert_output_regex)

tests.test_logging.test_custom_verbose_option_name(invoke, args, assert_output_regex)

tests.test_logging.test_unrecognized_verbosity_level(invoke, cmd_decorator, cmd_type)

tests.test_logging.test_standalone_option_default_logger(invoke, cmd_decorator, option_decorator, args, expected_level, assert_output_regex)

Checks: - option affect log level - the default logger is root - the default logger message format - level names are colored - log level is propagated to all other loggers

tests.test_logging.test_default_logger_param(invoke, logger_param, params)

Passing a logger instance or name to the default_logger parameter works.

tests.test_logging.test_new_extra_logger_name_passing(invoke)

Test extra logger with custom format, passed to the option by its name.

tests.test_logging.test_new_extra_logger_object_passing(invoke)

Test extra logger with custom format, passed as an object to the option.

tests.test_logging.test_new_extra_logger_root_config(invoke)

Modify the root logger via new_extra_logger()

tests.test_logging.test_logger_propagation(invoke)

tests.test_parameters module

class tests.test_parameters.Custom

Bases: ParamType

A dummy custom type.

name: str = 'Custom'

the descriptive name of this type

convert(value, param, ctx)

Convert the value to the correct type. This is not called if the value is None (the missing value).

This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.

The param and ctx arguments may be None in certain situations, such as when converting prompt input.

If the value cannot be converted, call fail() with a descriptive message.

Parameters:

• value – The value to convert.

• param – The parameter that is using this type to convert its value. May be None.

• ctx – The current context that arrived at this value. May be None.

tests.test_parameters.test_params_auto_types(invoke, option_decorator)

Check parameters types and structure are properly derived from CLI.

tests.test_parameters.assert_table_content(output, expected_table, table_format=None)

Helper to assert the content of a rendered table in the output.

Return type:

None

tests.test_parameters.test_standalone_show_params_option(invoke, cmd_decorator, option_decorator, assert_output_regex)

tests.test_parameters.test_integrated_show_params_option(invoke, create_config)

tests.test_parameters.test_show_params_table_format_ordering(invoke, args_order)

--show-params respects --table-format regardless of CLI order.

tests.test_parameters.test_show_params_native_types(invoke, table_format)

Serialization formats emit native types instead of styled glyphs.

tests.test_parameters.test_recurse_subcommands(invoke)

tests.test_parameters.test_subcommand_conflicts_with_parent_param(invoke)

A subcommand whose name matches its direct parent’s param is skipped in the parameter tree (the config key would be ambiguous), but does not crash the CLI.

[root.alpha]
# "foo" is ambiguous: is it the --foo param or the [root.alpha.foo] subcommand?
foo = ???

See: https://github.com/kdeldycke/click-extra/pull/1286

tests.test_parameters.test_nested_subcommand_no_false_conflict_with_root_param(invoke)

A nested subcommand can share a name with a root-level param without conflict.

The config paths are distinct (root.verbose vs root.alpha.verbose), so there is no ambiguity.

See: https://github.com/kdeldycke/click-extra/pull/1286

tests.test_parameters.test_standalone_table_rendering(invoke, opt1, opt2, table_format)

Check all rendering styles of the table with standalone --show-params and --table-format option.

tests.test_parameters.test_standalone_no_color_rendering(invoke, opt1, opt2, opt3, table_format)

Check that all rendering styles are responding to the --color/--no-color option.

tests.test_pygments module

tests.test_pygments.lex(text)

Shorthand: lex text and return (token_type, value) pairs.

Return type:

list[tuple]

tests.test_pygments.collect_classes(klass, prefix='Ansi')

Returns all classes defined in click_extra.pygments that are a subclass of klass, and whose name starts with the provided prefix.

tests.test_pygments.get_pyproject_section(*section_path)

Descends into the TOML tree of pyproject.toml to reach the value specified by section_path.

Return type:

dict[str, str]

tests.test_pygments.check_entry_points(entry_points, *section_path)

Return type:

None

tests.test_pygments.test_ansi_lexers_candidates(tmp_path)

Look into Pygments test suite to find all ANSI lexers candidates.

Good candidates for ANSI colorization are lexers that are producing Generic.Output tokens, which are often used by REPL-like and scripting terminal to render text in a console.

The list is manually maintained in Click Extra code, and this test is here to detect new candidates from new releases of Pygments.

Attention

The Pygments source code is downloaded from GitHub in the form of an archive, and extracted in a temporary folder.

The version of Pygments used for this test is the one installed in the current environment.

Danger

Security check While extracting the archive, we double check we are not fed an archive exploiting relative .. or . path attacks.

tests.test_pygments.test_formatter_entry_points()

tests.test_pygments.test_filter_entry_points()

tests.test_pygments.test_lexer_entry_points()

tests.test_pygments.test_registered_formatters()

tests.test_pygments.test_registered_filters()

tests.test_pygments.test_registered_lexers()

tests.test_pygments.test_ansi_lexers_doc()

tests.test_pygments.test_plain_text(text, expected)

Plain text without escape sequences passes through unchanged.

tests.test_pygments.test_sgr_fg_standard(code, color)

SGR 30-37 set standard foreground colors.

tests.test_pygments.test_sgr_bg_standard(code, color)

SGR 40-47 set standard background colors.

tests.test_pygments.test_sgr_fg_bright(code, color)

SGR 90-97 set bright foreground colors.

tests.test_pygments.test_sgr_bg_bright(code, color)

SGR 100-107 set bright background colors.

tests.test_pygments.test_sgr_text_attribute(code, attr)

SGR attribute codes set the corresponding text styling.

tests.test_pygments.test_sgr_attribute_reset(set_code, reset_code, attr)

Each attribute can be individually reset by its specific SGR code.

tests.test_pygments.test_sgr22_resets_bold_and_faint()

SGR 22 (normal intensity) resets both bold and faint simultaneously.

tests.test_pygments.test_sgr0_resets_all()

SGR 0 resets all attributes and colors.

tests.test_pygments.test_empty_sgr_is_reset()

An empty SGR sequence (ESC [ m) is equivalent to SGR 0.

tests.test_pygments.test_sgr39_resets_foreground()

SGR 39 resets foreground color to default.

tests.test_pygments.test_sgr49_resets_background()

SGR 49 resets background color to default.

tests.test_pygments.test_sgr39_keeps_other_attributes()

SGR 39 only resets foreground; other attributes persist.

tests.test_pygments.test_sgr_combined(params, expected_token)

Multiple SGR codes in a single escape sequence are applied together.

tests.test_pygments.test_256color_fg(index)

SGR 38;5;n sets foreground to 256-color index.

tests.test_pygments.test_256color_bg(index)

SGR 48;5;n sets background to 256-color index.

tests.test_pygments.test_24bit_rgb_fg(r, g, b, expected_idx)

SGR 38;2;r;g;b quantizes to nearest 256-color index.

tests.test_pygments.test_24bit_rgb_bg(r, g, b, expected_idx)

SGR 48;2;r;g;b quantizes background to nearest 256-color index.

tests.test_pygments.test_nearest_256_quantization(r, g, b, expected)

Verify RGB-to-256 quantization for representative values.

tests.test_pygments.test_extra_css_matches_sgr_attributes()

EXTRA_ANSI_CSS keys match the attribute names in _SGR_ATTR_ON.

tests.test_pygments.test_non_sgr_csi_stripped()

Non-SGR CSI sequences (cursor movement, etc.) are stripped.

tests.test_pygments.test_vt100_charset_stripped()

VT100 charset selection escapes are stripped.

tests.test_pygments.test_vt100_charset_g1_stripped()

ESC ) designator for G1 charset is stripped.

tests.test_pygments.test_unknown_escape_stripped()

Unknown single-byte escape sequences are stripped.

tests.test_pygments.test_bare_escape_at_end()

A lone ESC at the end of input is consumed without error.

tests.test_pygments.test_osc_sequence_stripped()

Non-hyperlink OSC sequences are fully consumed and stripped.

tests.test_pygments.test_osc_st_terminated_stripped()

OSC sequences terminated by ST (ESC ) are fully stripped.

tests.test_pygments.test_osc8_hyperlink(text, expected)

OSC 8 hyperlinks emit link start/end tokens around the visible text.

tests.test_pygments.test_osc8_with_sgr()

OSC 8 hyperlink combined with SGR color preserves both.

tests.test_pygments.test_osc8_unsafe_scheme_stripped(url)

OSC 8 with unsafe or missing URL scheme is stripped silently.

tests.test_pygments.test_osc8_implicit_close()

A new OSC 8 link implicitly closes the previous one.

tests.test_pygments.test_osc8_unclosed()

An unclosed OSC 8 link is automatically closed at end of input.

tests.test_pygments.test_osc8_close_without_open()

An OSC 8 close without a preceding open is silently ignored.

tests.test_pygments.test_color_persists_until_changed()

A foreground color set in one sequence persists until explicitly changed.

tests.test_pygments.test_multiple_color_changes()

Color can be changed multiple times without resetting.

tests.test_pygments.test_attribute_stacking()

Attributes accumulate: bold then italic produces bold+italic.

tests.test_pygments.test_independent_fg_bg()

Foreground and background colors are independent of each other.

tests.test_pygments.test_sgr_with_trailing_semicolons()

Trailing semicolons in SGR parameters produce zero codes, which are resets.

tests.test_pygments.test_sgr_leading_semicolons()

Leading semicolons produce 0 values (resets).

tests.test_pygments.test_sgr_double_semicolons()

Double semicolons produce empty strings that cause the sequence to be skipped.

tests.test_pygments.test_sgr_unknown_codes_ignored()

Unknown SGR codes are silently ignored; known codes still apply.

tests.test_pygments.test_256color_truncated_params()

Truncated 256-color sequence (missing color index) leaves leftover codes.

38;5: code 38 triggers extended color handling but needs at least 2 more values (mode + index). Only 1 remains (5), so 38 skips. Then 5 is processed as SGR 5 (blink).

tests.test_pygments.test_256color_out_of_range()

256-color index outside 0-255 is ignored.

tests.test_pygments.test_24bit_truncated_params()

Truncated 24-bit RGB sequence (missing channels) is ignored.

tests.test_pygments.test_24bit_out_of_range()

24-bit RGB values outside 0-255 are ignored.

tests.test_pygments.test_extended_color_unknown_mode()

Extended color with unknown mode (not 5 or 2) skips the mode byte.

38;3;100: code 38 triggers extended color handling, mode 3 is unknown so mode and nothing else are consumed, then 100 is processed as SGR 100 (bright black background).

tests.test_pygments.test_non_numeric_sgr_params()

Non-numeric characters in CSI params cause partial consumption.

ESC[abc;31m is not a valid SGR sequence. The regex consumes ESC[a as a CSI with a as the final byte, leaving bc;31mtext as plain text.

tests.test_pygments.test_consecutive_resets()

Multiple consecutive resets are harmless.

tests.test_pygments.test_empty_text_between_sequences()

Sequences with no text between them produce no empty tokens.

tests.test_pygments.test_newline_in_colored_text()

Newlines within colored text are preserved in the token value.

tests.test_pygments.test_interleaved_text_and_escapes()

Complex interleaving of plain text and escape sequences.

tests.test_pygments.test_lexer_resets_between_calls()

Each call to get_tokens starts from a clean state.

tests.test_pygments.test_ansi_styles_has_all_named_colors()

Style dict contains entries for all 16 named foreground and background colors.

tests.test_pygments.test_ansi_styles_has_256_palette()

Style dict contains entries for all 256 foreground and background indices.

tests.test_pygments.test_ansi_styles_excludes_all_attributes()

All text attribute tokens are absent from the style dict.

Furo’s dark-mode CSS generator adds color: #D0D0D0 to every token in the style dict. For attribute tokens, this overrides actual foreground colors on compound tokens when the attribute rule appears later in the CSS cascade. All attribute styling is handled by EXTRA_ANSI_CSS / custom.css instead.

tests.test_pygments.test_ansi_styles_count()

Style dict has only color entries: 32 named + 512 indexed.

tests.test_pygments.test_formatter_no_color_on_attribute_css()

CSS rules for attribute-only tokens must not set a color property.

When an attribute token (like -Ansi-Strikethrough) has a color property in its CSS rule, it can override the foreground color of a sibling color token (like -Ansi-Red) if the attribute rule appears later in the CSS cascade. This regression test catches the issue that Furo’s dark-mode generator exposed.

tests.test_pygments.test_palette_256_completeness()

256-color palette has exactly 256 entries.

tests.test_pygments.test_palette_256_hex_format()

All palette values are 7-character hex strings.

tests.test_pygments.test_lexer_map_completeness()

LEXER_MAP has one entry per session lexer.

tests.test_pygments.test_ansi_filter_transforms_output_tokens()

AnsiFilter converts Generic.Output tokens containing ANSI codes.

tests.test_pygments.test_ansi_filter_passes_through_other_tokens()

AnsiFilter does not modify tokens that are not Generic.Output.

tests.test_pygments.test_formatter_css_classes_single_color()

Single-color token gets the expected CSS classes.

tests.test_pygments.test_formatter_css_classes_compound()

Compound token gets decomposed CSS classes.

tests.test_pygments.test_formatter_css_classes_256color()

256-color tokens get the correct CSS class.

tests.test_pygments.test_formatter_style_defs_contain_ansi_colors()

get_style_defs() includes CSS rules for ANSI color tokens.

tests.test_pygments.test_formatter_osc8_hyperlink()

OSC 8 hyperlink is rendered as an HTML <a> tag.

tests.test_pygments.test_formatter_osc8_with_color()

OSC 8 hyperlink combined with SGR color renders both link and color.

tests.test_pygments.test_formatter_osc8_url_escaping()

URLs with special HTML characters are properly escaped in href.

tests.test_pygments.test_formatter_css_contains_link_rules()

get_style_defs() includes CSS for hyperlink styling.

tests.test_pygments.test_formatter_osc8_unsafe_scheme_no_link()

Unsafe URL schemes produce no <a> tag in formatted output.

tests.test_pygments.test_real_world_ansi(text, expected_tokens)

Real-world ANSI patterns from terminal tools and documentation references.

tests.test_pytest module

Test the Pytest helpers.

tests.test_pytest.test_aligned_colored_fixtures(uncolored, colored)

tests.test_sphinx module

Fixtures and utilities for Sphinx testing.

tests.test_sphinx.test_sphinx_extension_setup(sphinx_app)

Test that the Sphinx extension is properly loaded.

tests.test_sphinx.test_resolve_any_xref(sphinx_app)

Test that resolve_any_xref is implemented and returns an empty list.

See also

https://github.com/kdeldycke/click-extra/issues/1502

tests.test_sphinx_alerts module

Tests for GitHub alert syntax conversion in Sphinx with MyST parser.

tests.test_sphinx_alerts.test_all_alert_types(alert_type)

Test all supported alert types are converted correctly.

tests.test_sphinx_alerts.test_alert_conversion(text, expected)

Test GitHub alerts are converted to MyST admonitions.

When expected is None, no conversion should occur.

tests.test_sphinx_alerts.test_sphinx_integration(sphinx_app, test_case)

Integration-critical tests that verify Sphinx rendering behavior.

tests.test_sphinx_alerts.test_github_alert_no_colon_fence(tmp_path)

Test that ConfigError is raised when colon_fence is not enabled.

tests.test_sphinx_alerts.test_github_alert_in_included_files(sphinx_app_myst_with_include, included_files, main_content, expected_fragments, unexpected_fragments)

Test GitHub alerts in included files with various configurations.

tests.test_sphinx_click module

Tests for Sphinx directives click:source and click:run in rST and MyST formats.

tests.test_sphinx_click.test_directive_functionality(sphinx_app, test_case)

Test standard directive functionalities in both rST and MyST.

tests.test_sphinx_click.test_directive_option_format(sphinx_app_rst)

rST will fail to render if an :option: is not followed by an empty line.

tests.test_sphinx_click.test_directive_option_language_override(sphinx_app)

Test that language override works for click:run directive.

tests.test_sphinx_click.test_sphinx_directive_state_persistence(sphinx_app)

Test that state persists between declare and run directives in real Sphinx.

tests.test_sphinx_click.test_directive_variable_conflict(var_name, sphinx_app, content, directive_lineno, error_lineno)

Test that variable conflicts are properly detected in real Sphinx environment.

tests.test_sphinx_click.test_exit_exception_percolate(sphinx_app)

Test directives that handle command errors and exit codes.

tests.test_table module

tests.test_table.test_table_formats_definition()

Check all table formats are accounted for and properly named.

tests.test_table.test_unrecognized_format(invoke, cmd_decorator, cmd_type)

tests.test_table.test_all_table_formats_have_test_rendering()

Check all table formats have a rendering test fixture defined.

tests.test_table.test_all_table_rendering(invoke, cmd_decorator, option_decorator, format_name, expected)

tests.test_table.test_markup_strips_ansi_by_default(invoke, format_id)

Markup formats strip ANSI codes when --color is not forced.

tests.test_table.test_markup_preserves_ansi_with_color_flag(invoke, format_id)

--color overrides ANSI stripping for markup formats.

tests.test_table.test_serialize_json_compatible(table_format, data)

tests.test_table.test_serialize_roundtrip(table_format, data, loader)

tests.test_table.test_serialize_toml_list_wrapping()

Top-level lists are wrapped under a record key for TOML.

tests.test_table.test_serialize_strips_none(table_format)

TOML and XML have no null type. None values are omitted.

tests.test_table.test_serialize_xml()

tests.test_table.test_serialize_xml_list_wrapping()

Top-level lists are wrapped under a record key for XML.

tests.test_table.test_serialize_xml_custom_root_element()

tests.test_table.test_serialize_default_callback()

Custom types are converted via the default callback.

tests.test_table.test_serialize_unsupported_format_raises()

tests.test_table.test_strip_none(data, expected)

tests.test_table.test_apply_default_native_types_unchanged()

tests.test_table.test_apply_default_custom_type_converted(data, expected)

tests.test_table.test_missing_dependency_clean_error(monkeypatch, func, args, kwargs, match)

Missing optional dependency produces a clean error, no traceback.

tests.test_table.test_render_table_sort(data, headers, sort_key, expected_fruits)

tests.test_table.test_render_table_header_edge_cases(headers, data, expected)

Edge cases for header handling in structured format rendering.

tests.test_table.test_column_sort_key(header_defs, rows, sort_columns, cell_key, expected_first_col)

tests.test_table.test_print_sorted_table_empty_rows(capsys)

Empty table produces no output.

tests.test_table.test_sort_by_option_choices_and_default(header_defs, expected_choices, expected_default)

SortByOption choices and default are derived from column definitions.

tests.test_table.test_sort_by_option_wires_context(invoke)

SortByOption replaces ctx.print_table with the sorted variant.

tests.test_table.test_sort_by_option_multi_column(invoke)

Multiple –sort-by options define sort priority.

tests.test_telemetry module

tests.test_telemetry.test_standalone_telemetry_option(invoke, cmd_decorator, telemetry_help, option_decorator)

tests.test_telemetry.test_multiple_envvars(invoke, cmd_decorator, telemetry_help)

tests.test_testing module

Test the testing utilities and the simulation of CLI execution.

tests.test_testing.test_real_fs()

Check a simple test is not caught into the CLI runner fixture which is encapsulating all filesystem access into temporary directory structure.

tests.test_testing.test_temporary_fs(extra_runner)

Check the CLI runner fixture properly encapsulated the filesystem in temporary directory.

tests.test_testing.test_runner_output()

tests.test_testing.check_default_colored_rendering(result)

tests.test_testing.check_default_uncolored_rendering(result)

tests.test_testing.check_forced_uncolored_rendering(result)

tests.test_testing.test_invoke_optional_color(invoke)

tests.test_testing.test_invoke_default_color(invoke)

tests.test_testing.test_invoke_forced_color_stripping(invoke)

tests.test_testing.test_invoke_color_keep(invoke)

tests.test_testing.test_invoke_color_forced(invoke)

Test colors are preserved while invoking, and forced to be rendered on Windows.

tests.test_testing.test_extra_command_default_color()

With @command, ExtraContext defaults root color=True and ColorOption defaults True. Verify ctx.color=True and ANSI codes present in output.

tests.test_testing.test_extra_command_no_color_flag()

Invoke with –no-color. Verify ctx.color=False and ANSI stripped from echo output.

tests.test_testing.test_force_color_attribute()

ExtraCliRunner.force_color=True overrides color parameter.

tests.test_testing.test_no_color_envvar()

NO_COLOR=1 env var causes ctx.color=False via ColorOption.

tests.test_testing.test_force_color_envvar()

FORCE_COLOR=1 env var keeps ctx.color=True via ColorOption.

tests.test_testing.test_extra_context_root_defaults_color_true()

Root ExtraContext without color= arg defaults to color=True.

tests.test_testing.test_extra_context_inherits_from_parent()

Child ExtraContext inherits color from parent when not set.

tests.test_testing.test_extra_context_explicit_overrides_parent()

Child ExtraContext with explicit color overrides parent.

tests.test_testing.test_should_strip_ansi_non_tty()

In a test runner (non-TTY), should_strip_ansi behaves based on color arg.

tests.test_testing.test_resolve_color_default_no_context()

Outside any Click context, resolve_color_default returns None or passed value.

tests.test_timer module

Test defaults of our custom commands, as well as their customizations and attached options, and how they interact with each others.

tests.test_timer.test_integrated_time_option(invoke, subcommand_id, time_min)

tests.test_timer.test_integrated_notime_option(invoke, subcommand_id)

tests.test_timer.test_standalone_timer_option(invoke, cmd_decorator, option_decorator, assert_output_regex)

tests.test_types module

tests.test_types.test_click_choice_behavior()

Lockdown the behavior of method inherited from Click’s Choice type.

Return type:

None

tests.test_types.test_enum_string_choices(enum_definition, choice_source, result)

Return type:

None

tests.test_types.test_enum_choice_show_aliases(enum_definition, choice_source, show_aliases, result)

Test that EnumChoice correctly handles Enum with aliases.

Return type:

None

class tests.test_types.MyEnum(*values)

Bases: Enum

Produce different strings for keys/names, values and str().

FIRST_VALUE = 'first-value'

SECOND_VALUE = 'second-value'

tests.test_types.test_enum_choice_internals(source, expected_choices)

Return type:

None

tests.test_types.test_enum_choice_case_sensitivity(case_sensitive)

Return type:

None

tests.test_types.test_enum_choice_duplicate_string()

Return type:

None

tests.test_types.test_enum_choice_command(invoke, cmd_decorator, opt_decorator, case_sensitive, valid_args, invalid_args)

Test EnumChoice used within an option.

Return type:

None

tests.test_types.test_enum_choice_default_value(invoke, cmd_decorator, opt_decorator, opt_type, default_value)

Test EnumChoice used within an option with a default value.

Return type:

None

tests.test_types.test_enum_choice_callback(invoke, cmd_decorator, opt_decorator, choice_source, cli_value)

Test that option callbacks receive properly converted Enum members.

Return type:

None

tests.test_version module

Test the --version option.

Todo

Test standalone scripts setting package name to filename and version to None.

Todo

Test standalone script fetching version from __version__ variable.

tests.test_version.test_standalone_version_option(invoke, cmd_decorator, option_decorator)

tests.test_version.test_debug_output(invoke, cmd_decorator, option_decorator, assert_output_regex)

tests.test_version.test_set_version(invoke)

tests.test_version.test_custom_message(invoke, cmd_decorator, message, regex_stdout, assert_output_regex)

tests.test_version.test_style_reset(invoke, cmd_decorator)

tests.test_version.test_custom_message_style(invoke, cmd_decorator)

tests.test_version.test_context_meta(invoke, cmd_decorator, assert_output_regex)

tests.test_version.test_context_meta_laziness(invoke, cmd_decorator)

Accessing a single field from ctx.meta must not evaluate unrelated fields.

Ensures that the _LazyVersionDict defers property evaluation: reading click_extra.version should not trigger expensive properties like env_info or git fields.

tests.test_version.test_module_version_parent_package_fallback(monkeypatch)

module_version falls back to parent package’s __version__.

Simulates the Nuitka use-case: a CLI whose module is myapp.__main__ (no __version__), with the parent package myapp providing it.

tests.test_version.test_cli_frame_fallback(monkeypatch)

cli_frame() falls back to the outermost frame when all frames are from the Click ecosystem.

tests.test_version.test_integrated_version_option_precedence(invoke, params)

tests.test_version.test_version_fields_forwarded_to_version_option(invoke)

version_fields on @command forwards to ExtraVersionOption.

tests.test_version.test_version_fields_forwarded_on_group(invoke)

version_fields works on @group too.

tests.test_version.test_version_fields_multiple(invoke)

Multiple fields can be overridden at once.

tests.test_version.test_version_fields_rejects_unknown(invoke)

Unknown field names raise TypeError.

tests.test_version.test_color_option_precedence(invoke)

–no-color has an effect on –version, if placed in the right order.

Eager parameters are evaluated in the order as they were provided on the command line by the user as expleined in: https://click.palletsprojects.com/en/stable/click-concepts/#callback-evaluation-order

Todo

Maybe have the possibility to tweak CLI callback evaluation order so we can let the user to have the NO_COLOR env set to allow for color-less --version output.

tests.test_version.test_dev_version_appends_git_hash(invoke, cmd_decorator)

A .dev version gets a +hash suffix appended (or not, if git is unavailable).

tests.test_version.test_prebaked_dev_version_not_double_suffixed(invoke, cmd_decorator)

A version with an existing + is returned as-is — no second hash appended.

tests.test_version.test_release_version_unchanged(invoke, cmd_decorator)

A non-dev version is never modified.

tests.test_version.init_file(tmp_path)

Helper that creates a temporary __init__.py with the given content.

tests.test_version.test_prebake_dev_version(init_file)

A .dev version gets +hash appended in the file.

tests.test_version.test_prebake_single_quotes(init_file)

Single-quoted __version__ is also handled.

tests.test_version.test_prebake_already_baked_skipped(init_file)

A version with existing + is left untouched.

tests.test_version.test_prebake_release_skipped(init_file)

A release version (no .dev) is not modified.

tests.test_version.test_prebake_no_version_in_file(init_file)

A file without __version__ returns None.

tests.test_version.test_prebake_missing_local_version_raises(init_file)

Calling without local_version raises TypeError.

tests.test_version.test_prebake_idempotent(init_file)

Running prebake twice does not double-suffix.

tests.test_version.test_prebake_preserves_surrounding_content(init_file)

Content around __version__ is not disturbed.

tests.test_version.test_prebake_dunder_empty_replaced(init_file)

An empty dunder variable gets replaced.

tests.test_version.test_prebake_dunder_single_quotes(init_file)

Single-quoted empty dunder is also handled.

tests.test_version.test_prebake_dunder_nonempty_skipped(init_file)

A dunder with an existing non-empty value is left untouched.

tests.test_version.test_prebake_dunder_not_found(init_file)

A file without the target dunder returns None.

tests.test_version.test_prebake_dunder_idempotent(init_file)

Running prebake_dunder twice does not overwrite.

tests.test_version.test_prebake_dunder_preserves_surrounding_content(init_file)

Content around the target dunder is not disturbed.

tests.test_version.test_prebake_dunder_full_sha(init_file)

A full 40-character SHA is handled correctly.

tests.test_version.test_discover_finds_init(tmp_path, monkeypatch)

Discovers __init__.py from [project.scripts].

tests.test_version.test_discover_no_pyproject(tmp_path, monkeypatch)

Returns empty list when pyproject.toml is missing.

tests.test_version.test_discover_no_scripts(tmp_path, monkeypatch)

Returns empty list when [project.scripts] is absent.

tests.test_version.test_discover_deduplicates(tmp_path, monkeypatch)

Multiple scripts from the same package yield one path.

tests.test_version.test_prebaked_git_branch()

A pre-baked __git_branch__ dunder is used over subprocess.

tests.test_version.test_prebaked_git_long_hash()

A pre-baked __git_long_hash__ dunder is used over subprocess.

tests.test_version.test_prebaked_git_tag_sha()

A pre-baked __git_tag_sha__ dunder is resolved.

tests.test_version.test_prebaked_empty_dunder_ignored()

An empty dunder is not treated as a pre-baked value.

tests.test_version.test_prebaked_non_string_ignored()

A non-string dunder is not treated as a pre-baked value.