Write a documentation for undocumented QACTL modules

deps/wazuh_testing/wazuh_testing/qa_ctl/configuration/qa_ctl_configuration.py

@@ -1,5 +1,22 @@
 
 class QACTLConfiguration:
+    """Class implemented to control the different options for the output config module.
+
+    Args:
+        configuration_data (dict) : Dict with all the info needed for this module coming from config file.
+
+    Attributes:
+        configuration_data (dict) : Dict with all the info needed for this module coming from config file.
+        vagrant_output (boolean): Defines if the vagrant's outputs are going to be replaced by customized
+        outputs or if they remain with the default outputs. This parameter is set to 'False' by default.
+        ansible_output (boolean): Defines if the ansible's outputs are going to be replaced by customized 
+        outputs or if they remain with the default outputs. This parameter is set to 'False' by default.
+        logging_enable (boolean): This field is used for enabling or disabling the logging outputs option.
+        Its default value is set to 'True'.
+        logging_level (string): Defines the logging level for the outputs. 
+        Four options are available: DEBUG, INFO, WARNING, ERROR, CRITICAL.
+        logging_file (string): This field defines a path for a file where the outputs will be logged as well
+    """
 
     def __init__(self, configuration_data):
         self.configuration_data = configuration_data
@@ -12,6 +29,9 @@ def __init__(self, configuration_data):
         self.__read_configuration_data()
 
     def __read_configuration_data(self):
+        """Read the given configuration data of the object and sets the values of the
+            parameters of the class.
+        """
         if 'config' in self.configuration_data:
             if 'vagrant_output' in self.configuration_data['config']:
                 self.vagrant_output = self.configuration_data['config']['vagrant_output']
@@ -27,6 +47,7 @@ def __read_configuration_data(self):
 
 
     def __str__(self):
+        """Define how the class object is to be displayed."""
         return f"vagrant_output: {self.vagrant_output}\nansible_output: {self.ansible_output}\n" \
                f"logging_enable: {self.logging_enable}\nloggin_level: {self.logging_level}\n"\
                f"logging_file: {self.logging_file}\n"

deps/wazuh_testing/wazuh_testing/qa_ctl/deployment/vagrantfile.py

@@ -56,6 +56,12 @@ def __init__(self, file_path, box_image, vm_label, vm_name, cpus, memory, system
         self.box_url = self.__get_box_url()
 
     def __get_box_url(self):
+        """Get the box URL of the specified box_image parameter
+
+        Returns:
+            str: String with the URL of the specified box (if exists). In case the box is not found in the map,
+            it will return a 'None' value.
+        """
         box_mapping = {
             'qactl/ubuntu_20_04': 'https://s3.amazonaws.com/ci.wazuh.com/qa/boxes/QACTL_ubuntu20_04.box',
             'qactl/centos_8': 'https://s3.amazonaws.com/ci.wazuh.com/qa/boxes/QACTL_centos_8.box'

deps/wazuh_testing/wazuh_testing/qa_ctl/provisioning/ansible/ansible_inventory.py

@@ -80,6 +80,7 @@ def write_inventory_to_file(self):
             inventory.write(self.__str__())
 
     def delete_playbook_file(self):
+        """Delete all created playbook files"""
         # if os.path.exists(self.inventory_file_path):
         #     os.remove(self.inventory_file_path)
         pass

deps/wazuh_testing/wazuh_testing/qa_ctl/provisioning/ansible/ansible_playbook.py

@@ -72,6 +72,7 @@ def write_playbook_to_file(self):
             file.write(self.__str__())
 
     def delete_playbook_file(self):
+        """Delete the existing playbook file"""
         if os.path.exists(self.playbook_file_path):
             os.remove(self.playbook_file_path)
             AnsiblePlaybook.LOGGER.debug(f"{self.playbook_file_path} playbook file was deleted")

deps/wazuh_testing/wazuh_testing/qa_ctl/provisioning/ansible/ansible_runner.py

@@ -52,6 +52,18 @@ def run(self):
 
     @staticmethod
     def run_ephemeral_tasks(ansible_inventory_path, playbook_parameters, raise_on_error=True, output=False):
+        """Run the ansible tasks given from playbook parameters
+
+        Args:
+            ansible_inventory_path (string): Path were the ansible directory is placed.
+            playbook_parameters : parameters for the ansible playbook.
+            raise_on_error (boolean): Sets if errors or unexpected behaviour are goint to raise errors, Set to 'True' by default.
+            output (boolena): sets if there are going to be outputs. Set to 'False' by default.
+
+        Returns:
+            AnsibleOutput: Result of the ansible playbook run.
+
+        """
         ansible_playbook = AnsiblePlaybook(**playbook_parameters)
         quiet = not output
 

deps/wazuh_testing/wazuh_testing/qa_ctl/provisioning/qa_provisioning.py

@@ -199,5 +199,6 @@ def run(self):
         QAProvisioning.LOGGER.info(f"The instances have been provisioned sucessfully")
 
     def destroy(self):
+        """Destroy all the temporary files created by an instance of this object"""
         if os.path.exists(self.inventory_file_path):
             os.remove(self.inventory_file_path)

deps/wazuh_testing/wazuh_testing/qa_ctl/provisioning/wazuh_deployment/wazuh_installation.py

@@ -5,6 +5,18 @@
 
 
 class WazuhInstallation(ABC):
+    """Install a Wazuh instance set from the configuration file
+
+    Args:
+        wazuh_target (string): Type of the wazuh installation desired (manager or agent).
+        installation_files_path (string): Path where the Wazuh instalation files are located.
+        qa_ctl_configuration (QACTLConfiguration): QACTL configuration.
+
+    Attributes:
+        wazuh_target (string): Type of the wazuh installation desired (manager or agent).
+        installation_files_path (string): Path where the wazuh installation files are located.
+        qa_ctl_configuration (QACTLConfiguration): QACTL configuration.       
+    """
     def __init__(self, wazuh_target, installation_files_path, qa_ctl_configuration):
         self.wazuh_target = wazuh_target
         self.installation_files_path = installation_files_path
@@ -13,6 +25,13 @@ def __init__(self, wazuh_target, installation_files_path, qa_ctl_configuration):
 
     @abstractmethod
     def download_installation_files(self, inventory_file_path, ansible_tasks, hosts='all'):
+        """Download the installation files of Wazuh  by creating an ansible playbook and launching it
+
+        Args:
+            inventory_file_path (string): path where the instalation files are going to be stored
+            ansible_tasks (ansible object): ansible instance with already provided tasks to run
+            hosts (string): Parameter set to `all` by default
+        """
         create_path_task = AnsibleTask({'name': f"Create {self.installation_files_path} path",
                                         'file': {'path': self.installation_files_path, 'state': 'directory'}})
         # Add path creation task at the beggining of the playbook

deps/wazuh_testing/wazuh_testing/qa_ctl/provisioning/wazuh_deployment/wazuh_local_package.py

@@ -9,6 +9,23 @@
 
 
 class WazuhLocalPackage(WazuhPackage):
+    """Install Wazuh from a local existent package
+
+    Args:
+        wazuh_target (string): Type of the Wazuh instance desired (agent or manager).
+        installation_files_path (string): Path where is located the Wazuh instalation files.
+        local_package_path (string): Path where the local package is located.
+        qa_ctl_configuration (QACTLConfiguration): QACTL configuration.
+        version (string): The version of Wazuh. Parameter set by default to 'None'.
+        system (string): System of the Wazuh installation files. Parameter set by default to 'None'.
+
+    Attributes:
+        local_package_path (string): Path where the local package is located.
+        package_name (string): name of the Wazuh package.
+        installation_files_path (string): Path where the Wazuh installation files are located.
+        local_package_path (string): Path where the local package is located.
+        qa_ctl_configuration (QACTLConfiguration): QACTL configuration.
+    """
     LOGGER = Logging.get_logger(QACTL_LOGGER)
 
     def __init__(self, wazuh_target, installation_files_path, local_package_path, qa_ctl_configuration, version=None,
@@ -19,6 +36,15 @@ def __init__(self, wazuh_target, installation_files_path, local_package_path, qa
                          system=system, qa_ctl_configuration=qa_ctl_configuration)
 
     def download_installation_files(self, inventory_file_path, hosts='all'):
+        """Download the installation files of Wazuh in the given inventory file path
+
+        Args:
+            inventory_file_path (string): path where the instalation files are going to be stored.
+            hosts (string): Parameter set to `all` by default.
+
+        Returns:
+            str: String with the complete path of the installation package
+        """
         WazuhLocalPackage.LOGGER.debug(f"Copying local package {self.local_package_path} to "
                                        f"{self.installation_files_path} in {hosts} hosts")
 

deps/wazuh_testing/wazuh_testing/qa_ctl/provisioning/wazuh_deployment/wazuh_package.py

@@ -4,6 +4,23 @@
 
 
 class WazuhPackage(WazuhInstallation, ABC):
+    """Install Wazuh from the given sources. In this case, the installation
+        will be done from a package file.
+
+    Args:
+        version (string): The version of Wazuh.
+        system (string): System of the Wazuh installation files.
+        wazuh_target (string): Type of the Wazuh instance desired (agent or manager).
+        installation_files_path (string): Path where is located the Wazuh instalation files.
+        qa_ctl_configuration (QACTLConfiguration): QACTL configuration.
+
+    Attributes:
+        version (string): The version of Wazuh.
+        system (string): System of the Wazuh installation files.
+        wazuh_target (string): Type of the Wazuh instance desired (agent or manager).
+        installation_files_path (string): Path where is located the Wazuh instalation files.
+        qa_ctl_configuration (QACTLConfiguration): QACTL configuration.
+    """
     def __init__(self, version, system, wazuh_target, installation_files_path, qa_ctl_configuration):
         self.version = version
         self.system = system
@@ -12,4 +29,11 @@ def __init__(self, version, system, wazuh_target, installation_files_path, qa_ct
 
     @abstractmethod
     def download_installation_files(self, inventory_file_path, ansible_tasks, hosts='all'):
+        """Download the installation files of Wazuh.
+
+        Args:
+            inventory_file_path (string): path where the instalation files are going to be stored
+            ansible_tasks (ansible object): ansible instance with already provided tasks to run
+            hosts (string): Parameter set to `all` by default
+        """
         super().download_installation_files(inventory_file_path, ansible_tasks, hosts)

deps/wazuh_testing/wazuh_testing/qa_ctl/provisioning/wazuh_deployment/wazuh_s3_package.py

@@ -9,6 +9,32 @@
 
 
 class WazuhS3Package(WazuhPackage):
+    """Install Wazuh from a S3 URL package
+
+    Args:
+        wazuh_target (string): Type of the Wazuh instance desired (agent or manager).
+        s3_package_url (string): URL of the S3 Wazuh package.
+        installation_files_path (string): Path where is located the Wazuh instalation files.
+        qa_ctl_configuration (QACTLConfiguration): QACTL configuration.
+        version (string): The version of Wazuh. Parameter set by default to 'None'.
+        system (string): System of the Wazuh installation files. Parameter set by default to 'None'.
+        revision (string): Revision of the wazuh package. Parameter set by default to 'None'.
+        repository (string): Repository of the wazuh package. Parameter set by default to 'None'.
+        architecture (string): Architecture of the Wazuh package. Parameter set by default to 'None'.
+
+    Attributes:
+        wazuh_target (string): Type of the Wazuh instance desired (agent or manager).
+        s3_package_url (string): URL of the S3 Wazuh package.
+        package_name (string): Name of the S3 package.
+        installation_files_path (string): Path where is located the Wazuh instalation files.
+        qa_ctl_configuration (QACTLConfiguration): QACTL configuration.
+        version (string): The version of Wazuh. Parameter set by default to 'None'.
+        system (string): System of the Wazuh installation files. Parameter set by default to 'None'.
+        revision (string): Revision of the wazuh package. Parameter set by default to 'None'.
+        repository (string): Repository of the wazuh package. Parameter set by default to 'None'.
+        architecture (string): Architecture of the Wazuh package. Parameter set by default to 'None'.
+    """
+
     LOGGER = Logging.get_logger(QACTL_LOGGER)
 
     def __init__(self, wazuh_target, s3_package_url, installation_files_path, qa_ctl_configuration, version=None,
@@ -29,6 +55,16 @@ def get_s3_package_url(self):
         pass
 
     def download_installation_files(self, s3_package_url, inventory_file_path, hosts='all'):
+        """Download the installation files of Wazuh in the given inventory file path
+
+        Args:
+            s3_package_url (string): URL of the S3 Wazuh package.
+            inventory_file_path (string): path where the instalation files are going to be stored.
+            hosts (string): Parameter set to `all` by default.
+
+        Returns:
+            str: String with the complete path of the downloaded installation package
+        """   
         WazuhS3Package.LOGGER.debug(f"Downloading Wazuh S3 package from <url> in {hosts} hosts")
 
         download_s3_package = AnsibleTask({'name': 'Download S3 package',

deps/wazuh_testing/wazuh_testing/qa_ctl/provisioning/wazuh_deployment/wazuh_sources.py

@@ -4,6 +4,27 @@
 from wazuh_testing.tools.logging import Logging
 
 class WazuhSources(WazuhInstallation):
+    """Install Wazuh from the given sources. In this case, the installation
+        will be done from the source files of a repository.
+
+    Args:
+        wazuh_target (string): Type of the Wazuh instance desired (agent or manager).
+        installation_files_path (string): Path where is located the Wazuh instalation files.
+        qa_ctl_configuration (QACTLConfiguration): QACTL configuration.
+        wazuh_branch (string): String containing the branch from where the files are going to be downloaded.
+        This field is set to 'master' by default.
+        wazuh_repository_url (string): URL from the repo where the wazuh sources files are located. 
+        This parameter is set to 'https://github.com/wazuh/wazuh.git' by default.
+
+    Attributes:
+        wazuh_target (string): Type of the Wazuh instance desired (agent or manager).
+        installation_files_path (string): Path where is located the Wazuh instalation files.
+        qa_ctl_configuration (QACTLConfiguration): QACTL configuration.
+        wazuh_branch (string): String containing the branch from where the files are going to be downloaded.
+        This field is set to 'master' by default.
+        wazuh_repository_url (string): URL from the repo where the wazuh sources files are located. 
+        This parameter is set to 'https://github.com/wazuh/wazuh.git' by default.
+    """
     LOGGER = Logging.get_logger(QACTL_LOGGER)
 
     def __init__(self, wazuh_target, installation_files_path, qa_ctl_configuration, wazuh_branch='master',
@@ -14,6 +35,15 @@ def __init__(self, wazuh_target, installation_files_path, qa_ctl_configuration,
                          installation_files_path=f"{installation_files_path}/wazuh-{self.wazuh_branch}")
 
     def download_installation_files(self, inventory_file_path, hosts='all'):
+        """Download the source files of Wazuh using an AnsibleTask instance.
+
+        Args:
+            inventory_file_path (string): path where the instalation files are going to be stored
+            hosts (string): Parameter set to `all` by default
+
+        Returns:
+            str: String with the path where the installation files are located
+        """
         WazuhSources.LOGGER.debug(f"Downloading Wazuh sources from {self.wazuh_branch} branch in {hosts} hosts")
 
         download_wazuh_sources_task = AnsibleTask({'name': f"Download Wazuh branch in {self.installation_files_path}",

deps/wazuh_testing/wazuh_testing/qa_ctl/run_tests/qa_test_runner.py

@@ -146,5 +146,6 @@ def run(self):
         QATestRunner.LOGGER.info('The test run is finished')
 
     def destroy(self):
+        """"Destroy all the temporary files created during a running QAtestRunner instance"""
         if os.path.exists(self.inventory_file_path):
             os.remove(self.inventory_file_path)