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.

scauto --help

Note

Each subcommand has it’s own --help message.

Global Options

These options can be used with any scauto command.

  • --conf <PATH> / -c <PATH>

    • 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 <LEVEL> / -v <LEVEL>

    • 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 <TYPE> / -t <TYPE>

        • 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] <NAME>

    • Options:
      • --card-dir <PATH> / -d <PATH>

        • 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 <TYPE> / -t <TYPE>

        • 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 <PASSWORD> / -p <PASSWORD>

        • 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 <PIN> / -P <PIN>

        • 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 <TYPE> / -T <TYPE>

        • 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:
      • <NAME>

        • 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] <SUBCOMMAND> [<SUBCOMMAND> ...]

    • 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] <NAME>

    • 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:
      • <NAME>

        • 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 <NAME>

    • Arguments:
      • <NAME>

        • 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 <KEY>

    • Arguments:
      • <KEY>

        • 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 <TEXT>

    • Arguments:
      • <TEXT>

        • 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.