====================================== SCAutolib Command-Line Interface (CLI) ====================================== The ``SCAutolib/cli_commands.py`` file defines the command-line interface (CLI) for the SCAutolib project using the ``click`` library. This CLI allows users to perform various system configurations and smart card related operations directly from the terminal. To use the CLI, you would typically run the script directly, for example: ``python -m SCAutolib.cli_commands`` (assuming ``SCAutolib`` is in your Python path), or a symbolic link created during installation ``scauto``. .. code-block:: bash scauto --help .. note:: Each subcommand has it's own ``--help`` message. ----- Global Options ============== These options can be used with any ``scauto`` command. * ``--conf `` / ``-c `` * **Description:** Specifies the absolute or relative path to the primary JSON configuration file that SCAutolib should use for its operations. This file typically contains details about CAs, users, and smart card settings, guiding the execution of commands like ``prepare``. * **Default:** `./conf.json` * **Type:** Path to a file. * **Usage:** ``scauto --conf /etc/scautolib/config.json prepare`` * ``--force`` / ``-f`` * **Description:** A boolean flag that, when set, compels the command to proceed with actions even if it means overwriting existing configurations or files. * **Default:** `False` * **Type:** Flag (boolean). * **Usage:** ``scauto --force prepare`` * ``--verbose `` / ``-v `` * **Description:** Controls the verbosity level of the logging output generated by SCAutolib. Setting a lower level (e.g., DEBUG) provides more detailed diagnostic information, which is invaluable during development and debugging, while higher levels (e.g., ERROR, CRITICAL) reduce output to only critical issues. * **Default:** `DEBUG` * **Type:** Choice (case-insensitive): ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``, ``CRITICAL``. * **Usage:** ``scauto --verbose INFO prepare`` ----- Main Commands ============= These are the primary commands available through the ``scauto`` CLI. * ``prepare`` * **Description:** This command is designed to configure the entire underlying system to properly support smart card operations based on the settings defined in the active configuration file. It handles the installation of necessary system packages and dependencies required for smart card interaction and testing environments. * **Usage:** ``scauto prepare [OPTIONS]`` * **Options:** * ``--gdm`` / ``-g`` * **Description:** If specified, this flag instructs the command to proceed with the installation of the GDM (GNOME Display Manager) package, which is relevant for graphical login environments where smart card authentication might be used. * **Default:** `False` * **Type:** Flag (boolean). * ``--graphical`` * **Description:** When this flag is enabled, the ``prepare`` command will ensure that all necessary dependencies for the GUI testing module are installed. This is essential for executing automated tests that interact with graphical user interfaces. * **Default:** `False` * **Type:** Flag (boolean). * ``--install-missing`` / ``-i`` * **Description:** This flag controls whether the command should automatically install any detected missing software packages that are prerequisites for SCAutolib's functionalities. It helps in setting up a complete environment with minimal manual intervention. * **Default:** `False` * **Type:** Flag (boolean). * ``setup-ca`` * **Description:** This command is responsible for configuring Certificate Authorities (CAs) on the system as defined within the specified configuration file. It provides flexibility to configure all CAs or target a specific type (local or IPA) if multiple CA definitions are present in the configuration. * **Usage:** ``scauto setup-ca [OPTIONS]`` * **Options:** * ``--ca-type `` / ``-t `` * **Description:** Allows specifying which type of CA should be configured. If left at its default, the command will attempt to configure all CA types (both local and ipa) defined in the conf.json. * **Default:** `all` * **Type:** Choice (case-insensitive): ``all``, ``local``, ``ipa``. .. warning:: The ``setup-ca`` command was designed for debugging puproses and not for real testing use. * ``setup-user`` * **Description:** Configures a specific user on the system, with optional smart card integration, based on the definitions in the configuration file. If the user specified by NAME is not found in the configuration, the command attempts to create a new user on the fly, requiring additional arguments for their properties and smart card type. * **Usage:** ``scauto setup-user [OPTIONS] `` * **Options:** * ``--card-dir `` / ``-d `` * **Description:** Specifies the file system path where the smart card's related files and directories should be created. This is a mandatory argument when defining a new user directly via the CLI without a pre-existing configuration entry. * **Default:** `None` * **Type:** String. * ``--card-type `` / ``-t `` * **Description:** Defines the specific type of smart card to be associated with the user. This can be a ``virtual`` card for software-based simulation, a ``real`` physical smart card, or a ``removinator`` type for specialized testing hardware. * **Default:** `virtual` * **Type:** Choice (case-insensitive): ``virtual``, ``real``, ``removinator``. * ``--passwd `` / ``-p `` * **Description:** Sets the password for the user being configured or created. This argument is required if the user is being defined directly via the command line and not loaded from the config file. * **Default:** `None` * **Type:** String. * ``--pin `` / ``-P `` * **Description:** Specifies the PIN for the smart card associated with the user. This argument is required if the user is being defined directly via the command line and not loaded from the config file. * **Default:** `None` * **Type:** String. * ``--user-type `` / ``-T `` * **Description:** Determines whether the user being created is a local system user or an ipa (Identity Management for Linux) user. This choice influences how the user account is provisioned and managed. * **Default:** `local` * **Type:** Choice (case-insensitive): ``local``, ``ipa``. * **Arguments:** * ```` * **Description:** The name of the user to be configured or created on the system. * **Required:** Yes. .. warning:: The ``setup-user`` command was designed for debugging puproses and not for real testing use. * ``cleanup`` * **Description:** This command performs a comprehensive cleanup operation, reverting all system configurations and changes that were applied by the prepare command. It aims to restore the environment to a state prior to SCAutolib's modifications, so the systtem will be as close to the initial state as possible. * **Usage:** ``scauto cleanup`` * **Options:** None. ----- GUI Test Commands (`gui` group) =============================== This section details commands specifically designed for running GUI-based smart card tests. These commands are typically chained together. * ``gui`` (Group Command) * **Description:** This is a top-level command group that encapsulates various subcommands for running automated GUI tests. Commands within this group are designed to be invoked sequentially, allowing for the execution of complex graphical test scenarios in a single CLI call. * **Usage:** ``scauto gui [OPTIONS] [ ...]`` * **Options:** * ``--install-missing`` / ``-i`` * **Description:** Similar to the ``prepare`` command's option, this flag ensures that any missing software packages required specifically for GUI testing operations are installed before test execution begins. * **Default:** `False` * **Type:** Flag (boolean). Subcommands within ``gui`` -------------------------- * ``gui init`` * **Description:** This subcommand initializes the graphical user interface environment for subsequent GUI testing actions. It prepares the display and underlying GUI automation framework for interaction. * **Usage:** ``scauto gui init`` * **Options:** None. * ``gui assert-text`` * **Description:** Checks for the presence of a specific text string on the currently displayed GUI screen. * **Usage:** ``scauto gui assert-text [OPTIONS] `` * **Options:** * ``--no`` * **Description:** When this flag is present, it reverses the assertion, causing the command to check if the specified text is *not* found on the screen * **Default:** `False` * **Type:** Flag (boolean). * **Arguments:** * ```` * **Description:** The exact word or phrase that the GUI test should look for on the screen. * **Required:** Yes. * ``gui click-on`` * **Description:** Simulates a mouse click action on a GUI object or area that contains the specified text. * **Usage:** ``scauto gui click-on `` * **Arguments:** * ```` * **Description:** The text content of the GUI object that should be clicked. * **Required:** Yes. * ``gui check-home-screen`` * **Description:** Verifies whether the currently displayed graphical screen corresponds to the expected "home screen" state of the system under test. This is often used as a checkpoint to confirm successful login. * **Usage:** ``scauto gui check-home-screen [OPTIONS]`` * **Options:** * ``--no`` * **Description:** Reverses the check, asserting that the current screen is *not* the home screen * **Default:** `False` * **Type:** Flag (boolean). * ``gui kb-send`` * **Description:** Sends one or more specific keyboard keys to the active GUI window. This is useful for simulating presses of special keys like ``enter``, ``tab``, ``escape``, or combinations thereof. * **Usage:** ``scauto gui kb-send `` * **Arguments:** * ```` * **Description:** The key or sequence of keys to send (e.g., ``enter``, ``alt+f4``. * **Required:** Yes. * ``gui kb-write`` * **Description:** Types a literal string of characters into the active GUI input field or window, as if a user were typing on a keyboard. After sending the string, an 'enter' key press is automatically appended. * **Usage:** ``scauto gui kb-write `` * **Arguments:** * ```` * **Description:** The string of text to be written. * **Required:** Yes. * ``gui done`` * **Description:** Serves as a finalization step for a sequence of GUI test commands. It triggers cleanup actions after all preceding GUI test operations have completed, ensuring a proper state transition or resource release. * **Usage:** ``scauto gui done`` * **Options:** None.