Skip to content

# `cli_testing`

This is where you can configure everything related to the testing through the CLI.

## Overview

.PyFunceble.overwrite.yaml

    cli_testing:
      # Provides everything directly related to the testing through the CLI.

      # Set the IP to prefix each hosts file lines with.
      #
      # CLI Argument: -ip | --hosts-ip
      hosts_ip: "0.0.0.0"

      # Set the amount of maximal workers to use to perform tests.
      #
      # NOTE:
      #     If set to `null`, the value is implicitly CPU * Cores - 2
      #
      # CLI Argument: -w | --max-workers
      max_workers: null

      # Enable/Disable the autocontinue datasets.
      #
      # The autocontinue datasets/database is a database that temporarily store the
      # result of the tested subject in the hope to continue as soon as possible
      # after a break or shortage.
      #
      # CLI Argument: -c | --auto-continue | --continue
      autocontinue: no

      # Enable/Disable the inactive datasets.
      #
      # The inactive datasets/database is used to store the INACTIVE and INVALID
      # subjects to purposely retest then at a later time.
      #
      # This mechanism let you cleanup your source file while being sure that
      # pyfunceble will retest the old entries of your source file. After retesting,
      # pyfunceble will throw the newly ACTIVE subject from the database and put
      # it into your ACTIVE output files so that you can reintroduce them into
      # your list.
      #
      # CLI Argument:  --inactive-db
      inactive_db: yes

      # Enable/Disable the whois storage of whois records.
      #
      # This mechanism let us avoid spaming the WHOIS servers by storing the
      # expiration dates from the whois record into a local datasets/database.
      # Later on, PyFunceble will query the local database first.
      #
      # CLI Argument: -wdb | --whois-database
      whois_db: yes

      # Enable/Disable the testing and generation of complements.
      #
      # A complement is `www.example.org` when `example.org` is given and vice-versa.
      #
      # CLI Argument: --complements
      complements: no

      # Enable/Disable the expension and testing of single addresses of a CIDR.
      #
      # CLI Argument: --cidr
      cidr_expand: no

      # Set the cooldown time to apply between each tests.
      #
      # This is essential to avoid spaming remote resources - especially WHOIS servers.
      #
      # WARNING:
      #     This must be a value >= 0.0
      #
      # CLI Argument: --cooldown-time
      cooldown_time: 0.0

      # Sets the Database Connector type to use.
      # Available: csv | mariadb | mysql | postgresql
      #
      # Set the type of database to use or generate to store long term information-s.
      #
      # When set to `mariadb`, `mysql` or `postgesql` the following environment
      # variables are required.
      #
      #     PYFUNCEBLE_DB_HOST - The host or unix socket path of the database server.
      #     PYFUNCEBLE_DB_PORT - The port to use to reach the database server.
      #     PYFUNCEBLE_DB_USERNAME - The username to use to connect to the database server - when applicable.
      #     PYFUNCEBLE_DB_PASSWORD - The password to use to connect to the database server - when applicable.
      #     PYFUNCEBLE_DB_NAME - The name of the database to work with.
      #     PYFUNCEBLE_DB_CHARSET - The charset to use - when applicable.
      #
      # Available Values: csv | mariadb | mysql | postgresql
      #
      # CLI Argument: --database-type
      db_type: csv

      # Set the filter to apply while reading inputs.
      #
      # In other words, a global filter to apply to select the subject to tests.
      # Meaning that if you give `\.info$` (for example), we will only test the
      # subjects that ends with `.info`.
      #
      # CLI Argument: --filter
      file_filter: null

      # Enable/Disable the mining of subjects.
      #
      # When enabled, PyFunceble will follow the HTTP redirects and put all redirected
      # subjects into the testing queue and outputs.
      #
      # CLI Argument: --mining
      mining: no

      # Acknowledge/Dismiss that we are testing for subjects that are only on the
      # local network.
      #
      # NOTE:
      #     When enabled, no syntax checking will be processed when performing
      #     availability and reputation tests.
      #
      # CLI Argument: --local
      local_network: no

      # Enable/Disable the preloading of the given input file(s).
      #
      # When enabled, we take the time to pre-load subjects by decoding inputs files
      # and storing the informatino in the chosen datasets/database format.
      # The hope is to optimise some of our process by only focusing on testing.
      #
      # WARNING:
      #     While this is helpful for long running tasks, this might not be a good
      #     idea if you are testing a URL directly. This process is not optimizied
      #     for sources that are constantly updated (checksums).
      #
      # CLI Argument: --preload
      preload_file: no

      # Enable/Disable a chancy testing mode that unleashes and bypass the safety
      # workflow-s in place in hope of speed.
      #
      # DANGER / WARNING:
      #     You have been warned. This mode is for the chancy and lucky one.
      #
      #     You shouldn't use this unless you fele really, really, really lucky and
      #     trust your machine.
      #
      #     Enabling this mode makes thinks look 'fast', but it may produce some
      #     rather ... unexpected behavior and results - IF N+1 process simultaneously
      #     write the same output file.
      #
      #     This mode also makes the CLI terminal output unparsable - either.
      #
      #     **MAY THE FORCE BE WITH YOU!**
      #
      # CLI Argument: --chancy
      chancy_tester: no

      ci:
        # Provides everything related to the testing within a Continuous integration
        # engine.

        # Enable/Disable the CI/CD mode.
        #
        # When enabled, PyFunceble will assume that it works with a git repository.
        # Therefore, you have to declare the following environment variables to
        # configure git for pushing - which is normally not available withing a
        # CI engine.
        #
        #       GIT_NAME - The `git.name` to setup and use.
        #       GIT_EMAIL - The `git.email` to setup and use.
        #       GIT_BRANCH - (optional) - The git branch to use to distribute results betwen sessions.
        #       GIT_DISTRIBUTION_BRANCH - (optional) - The git branch to use to distribute the final results.
        #       GITHUB_TOKEN - The token to use to authenticate ourselves against GitHub. Read when under a GitHub Action or Jenkins CI worker.
        #       GL_TOKEN - The token to use to authenticate ourselves againt GitLab. Read when under a GitLab Runner.
        #       GH_TOKEN - The token to ue to authenticate ourselves against GitHub. Read when under a Travis CI instance.
        #
        # CLI Argument: --ci
        active: no

        # Set the commit message to apply to all results commit except the final one.
        #
        # CLI Argument: --ci-commit-message
        commit_message: "PyFunceble - AutoSave"

        # Set the commit message to apply to the very last and final result commit.
        #
        # CLI Argument: --ci-end-commit-message
        end_commit_message: "PyFunceble - Results"

        # Set the number of minutes to wait before to start saving and stopping a session.
        #
        # This parameter can be understood as the running time of PyFunceble under a
        # CI Engine.
        #
        # CLI Argument: --ci-max-minutes
        max_exec_minutes: 15

        # Set the branch to use to distribute results between multiple CI/CD sessions.
        #
        # Environment Variable: GIT_BRANCH
        # CLI Argument: --ci-branch
        branch: master

        # Set the branch to use to distribute the final results of multiple CI/CD session.
        #
        # Environment Variable: GIT_DISTRIBUTION_BRANCH
        # CLI Argument: --ci-distribution-branch
        distribution_branch: master

        # Set the command to execute before each (except last) result commit.
        #
        # CLI Argument: --ci-command
        command: null

        # Set the command to execute before the very last result commit.
        #
        # CLI Argument: --ci-end-command
        end_command: null

      display_mode:
        # Provides everything related to the display/OUTPUT of PyFunceble.

        # Enable/Disable the printing of dots.
        #
        # Dots !? Why Dots ? WTH ?!
        #   Yes, you read correctly dots. Those dots are crutial under CI/CD engines
        #   that assumes that no-output within a few minutes is an error. To avoid
        #   such situation when the CI/CD engines just kill the job, we print dots,
        #   when we perform some tasks that may not output anything for a few minutes.
        #
        #   An example is when you are on the second session of testing and PyFunceble
        #   is going through the list of subjects but it sees that the subject has been
        #   already tested.
        #
        # NOTE:
        #   This argument is automatically switched to `yes` when under a CI/CD engine
        #   (aka cli_testing.ci set to yes).
        #
        # CLI Argument: --dots
        dots: no

        # Enable/Disable the printing of the execution time at the end of a test session.
        #
        # CLI Argument: -ex | --execution
        execution_time: no

        # Enable/Disable the printing of the percentage stats per status at the end
        # of a test session.
        #
        # CLI Argument: --percentage
        percentage: yes

        # Enable/Disable the printing of the registrar stats per subjects at the end
        # of a test session.
        #
        # CLI Argument: --registrar
        registrar: no

        # Enable/Disable the printing of any outputs.
        #
        # CLI Argument: -q | --quiet
        quiet: no

        # Enable/Disable the printing of minimal tabular information when testing.
        less: yes

        # Enable/Disable the printing of most tabular information when testing.
        #
        # CLI Argument: -a | --all
        all: no

        # Enable/Disable the printing of an extreme simple and minimalistic information
        # when testing.
        #
        # CLI Argument: -s | --simple
        simple: no

        # Enable/Disable the printing of colored tabular information.
        #
        # CLI Argument: --colour | --color
        colour: yes

        # Enable/Disable the printing of background colors.
        #
        # CLI Argument: --background-colour | --background-color
        background_colour: yes

        # Set the status to display to STDOUT.
        #
        # WARNING:
        #   When this parameter is not set to `ALL`, only the subjects matching the
        #   selected status will be printed to STDOUT. Howerver, this doesn't have
        #   any effect on the generated files.
        #
        # CLI Argument: --display-status
        status: all

        # Set the maximal number of registrar to display when we have to print the
        # registrar stats per subject.
        #
        # NOTE:
        #   This doesn't have any effect on the generated files.
        #
        # CLI Argument: --max-registrar
        max_registrar: 15

        # Enable/Disable the printing of the datetime of the test.
        #
        # CLI Argument: --display-datetime
        datetime: no

        # The format to use when displaying the datetime of the test.
        #
        # WARNING:
        #   This parameter is only taken into consideration when `datetime` is set
        #   to `yes`.
        #
        # CLI Argument: --display-datetime-fmt
        datetime_format: "%Y-%m-%d %H:%M:%S"

      testing_mode:
        # Provides and select the testing mode.
        #
        # NOTE:
        #   Only one can be active at a time.

        # Enable/Disable the availability test mode.
        availability: yes

        # Enable/Disable the syntax test mode.
        #
        # CLI Argument: --syntax
        syntax: no

        # Enable/Disable the reputation test mode.
        #
        # CLI Argument: --reputation
        reputation: no

      days_between:
        # Provides everything which is x days periodic.

        # NOT IMPLEMENTED (Anticipation for future usage).
        db_clean: 28

        # Set the minimal number of days between the retest of subject which were
        # stored into the inactive datasets/database.
        #
        # CLI Argument: -dbr | --days-between-db-retest
        db_retest: 1

      sorting_mode:
        # Provides everything related to the output sorting.
        #
        # NOTE:
        #   Only one can be active at a time.
        #
        # WARNING:
        #   The parameters below only applies to the generated files. NOT STDOUT.

        # Enable/Disable the hierarchical sorting.
        #
        # CLI Argument: --hierarchical
        hierarchical: no

        # Enable/Disable the standard sorting.
        standard: yes

      file_generation:
        # Provides everything related to the generation of files.

        # Enable/Disable the generation of files.
        #
        # CLI Argument: --no-files
        no_file: no

        # Enable/Disable the generation of hosts formatted files.
        #
        # CLI Argument: -h | --hosts
        hosts: no

        # Enable/Disable the generation of plain/raw formatted files.
        #
        # CLI Argument: --plain
        plain: yes

        # Enable/Disable the generation of analytic files.
        #
        # Analytic ?! WTH !?
        #   Yes, analytic! While PyFunceble is really good for a lot of things, sometime
        #   it takes some decision without being really sure about it or without
        #   wanting to be biased. Therefore, it generates files inside the analytic folder.
        #   The files inside the analytic folder are there for human to analyse or
        #   to invite the community to influence PyFunceble.
        #
        #   If you are sure that the behavior of PyFunceble should be adopted for sure,
        #   fill an issue and let's evolve it together :-)
        #
        analytic: yes

        # Enable/Disable the generation of unified results files.
        #
        # WARNING:
        #   This parameter simply generate a unified copy of the STDOUT instead of 1
        #   file per status.
        #
        # CLI Argument: --unified-results
        unified_results: no

        # Enable/Disable the merging of the results of all inputted files into one
        # single output directory.
        #
        # Normally, PyFunceble generated a dedicated output folder for each inputted
        # files. However, if you want the results to be merged inside a single
        # folder, just switch this parameter.
        #
        # CLI Argument: --merge-output
        merge_output_dirs: no