# certbot.tests.util module

Test utilities.

class certbot.tests.util.DummyInstaller(*args: Any, **kwargs: Any)

  Bases: `Installer`

  Dummy installer plugin for test purpose.

  get_all_names() → Iterable[str]

    Returns all names that may be authenticated.

    Return type:

      `collections.Iterable` of `str`

  deploy_cert(domain: str, cert_path: str, key_path: str, chain_path: str, fullchain_path: str) → None

    Deploy certificate.

    Parameters:

      - domain (str) – domain to deploy certificate file

      - cert_path (str) – absolute path to the certificate file

      - key_path (str) – absolute path to the private key file

      - chain_path (str) – absolute path to the certificate chain file

      - fullchain_path (str) – absolute path to the certificate fullchain file (cert plus chain)

    Raises:

      .PluginError – when cert cannot be deployed

  enhance(domain: str, enhancement: str, options: List[str] | str | None = None) → None

    Perform a configuration enhancement.

    Parameters:

      - domain (str) – domain for which to provide enhancement

      - enhancement (str) – An enhancement as defined in `ENHANCEMENTS`

      - options – Flexible options parameter for enhancement. Check documentation of `ENHANCEMENTS` for expected options for each enhancement.

    Raises:

      .PluginError – If Enhancement is not supported, or if an error occurs during the enhancement.

  supported_enhancements() → List[str]

    Returns a `collections.Iterable` of supported enhancements.

    Returns:

      supported enhancements which should be a subset of `ENHANCEMENTS`

    Return type:

      `collections.Iterable` of `str`

  save(title: str | None = None, temporary: bool = False) → None

    Saves all changes to the configuration files.

    Both title and temporary are needed because a save may be intended to be permanent, but the save is not ready to be a full checkpoint.

    It is assumed that at most one checkpoint is finalized by this method. Additionally, if an exception is raised, it is assumed a new checkpoint was not finalized.

    Parameters:

      - title (str) – The title of the save. If a title is given, the configuration will be saved as a new checkpoint and put in a timestamped directory. `title` has no effect if temporary is true.

      - temporary (bool) – Indicates whether the changes made will be quickly reversed in the future (challenges)

    Raises:

      .PluginError – when save is unsuccessful

  config_test() → None

    Make sure the configuration is valid.

    Raises:

      .MisconfigurationError – when the config is not in a usable state

  restart() → None

    Restart or refresh the server content.

    Raises:

      .PluginError – when server cannot be restarted

  classmethod add_parser_arguments(add: Callable[[...], None]) → None

    Add plugin arguments to the CLI argument parser.

    Parameters:

      add (callable) – Function that proxies calls to `argparse.ArgumentParser.add_argument` prepending options with unique plugin name prefix.

  prepare() → None

    Prepare the plugin.

    Finish up any additional initialization.

    Raises:

      - .PluginError – when full initialization cannot be completed.

      - .MisconfigurationError – when full initialization cannot be completed. Plugin will be displayed on a list of available plugins.

      - .NoInstallationError – when the necessary programs/files cannot be located. Plugin will NOT be displayed on a list of available plugins.

      - .NotSupportedError – when the installation is recognized, but the version is not currently supported.

  more_info() → str

    Human-readable string to help the user.

    Should describe the steps taken and any relevant info to help the user decide which plugin to use.

    Rtype str:

certbot.tests.util.vector_path(*names: str) → str

  Path to a test vector.

certbot.tests.util.load_vector(*names: str) → bytes

  Load contents of a test vector.

certbot.tests.util.load_cert(*names: str) → Certificate

  Load certificate.

certbot.tests.util.load_jose_rsa_private_key_pem(*names: str) → ComparableRSAKey

  Load RSA private key wrapped in jose.ComparableRSAKey

certbot.tests.util.load_rsa_private_key_pem(*names: str) → RSAPrivateKey

  Load RSA private key.

certbot.tests.util.make_lineage(config_dir: str, testfile: str, ec: bool = True) → str

  Creates a lineage defined by testfile.

  This creates the archive, live, and renewal directories if necessary and creates a simple lineage.

  Parameters:

    - config_dir (str) – path to the configuration directory

    - testfile (str) – configuration file to base the lineage on

    - ec (bool) – True if we generate the lineage with an ECDSA key

  Returns:

    path to the renewal conf file for the created lineage

  Return type:

    str

certbot.tests.util.patch_display_util() → MagicMock

  Patch certbot.display.util to use a special mock display utility.

  The mock display utility works like a regular mock object, except it also also asserts that methods are called with valid arguments.

  The mock created by this patch mocks out Certbot internals. That is, the mock object will be called by the certbot.display.util functions and the mock returned by that call will be used as the display utility. This was done to simplify the transition from zope.component and mocking certbot.display.util functions directly in test code should be preferred over using this function in the future.

  See https://github.com/certbot/certbot/issues/8948

  Returns:

    patch on the function used internally by certbot.display.util to get a display utility instance

  Return type:

    mock.MagicMock

certbot.tests.util.patch_display_util_with_stdout(stdout: IO | None = None) → MagicMock

  Patch certbot.display.util to use a special mock display utility.

  The mock display utility works like a regular mock object, except it also asserts that methods are called with valid arguments.

  The mock created by this patch mocks out Certbot internals. That is, the mock object will be called by the certbot.display.util functions and the mock returned by that call will be used as the display utility. This was done to simplify the transition from zope.component and mocking certbot.display.util functions directly in test code should be preferred over using this function in the future.

  See https://github.com/certbot/certbot/issues/8948

  The `message` argument passed to the display utility methods is passed to stdout’s write method.

  Parameters:

    stdout (object) – object to write standard output to; it is expected to have a `write` method

  Returns:

    patch on the function used internally by certbot.display.util to get a display utility instance

  Return type:

    mock.MagicMock

class certbot.tests.util.FreezableMock(frozen: bool = False, func: Callable[[...], Any] | None = None, return_value: Any = sentinel.DEFAULT)

  Bases: `object`

  Mock object with the ability to freeze attributes.

  This class works like a regular mock.MagicMock object, except attributes and behavior set before the object is frozen cannot be changed during tests.

  If a func argument is provided to the constructor, this function is called first when an instance of FreezableMock is called, followed by the usual behavior defined by MagicMock. The return value of func is ignored.

  freeze() → None

    Freeze object preventing further changes.

class certbot.tests.util.TempDirTestCase(methodName='runTest')

  Bases: `TestCase`

  Base test class which sets up and tears down a temporary directory

  setUp() → None

    Execute before test

  tearDown() → None

    Execute after test

class certbot.tests.util.ConfigTestCase(methodName='runTest')

  Bases: `TempDirTestCase`

  Test class which sets up a NamespaceConfig object.

  setUp() → None

    Execute before test

certbot.tests.util.lock_and_call(callback: Callable[[], Any], path_to_lock: str) → None

  Grab a lock on path_to_lock from a foreign process then execute the callback. :param callable callback: object to call after acquiring the lock :param str path_to_lock: path to file or directory to lock

certbot.tests.util.skip_on_windows(reason: str) → Callable[[Callable[[...], Any]], Callable[[...], Any]]

  Decorator to skip permanently a test on Windows. A reason is required.

certbot.tests.util.temp_join(path: str) → str

  Return the given path joined to the tempdir path for the current platform Eg.: ‘cert’ => /tmp/cert (Linux) or ‘C:UserscurrentuserAppDataTempcert’ (Windows)