feat(test): CCT-661 - Adding betelgeuse docstrings to test_collection.py

integration-tests/test_collection.py

@@ -9,11 +9,33 @@
 
 ARCHIVE_CACHE_DIRECTORY = "/var/cache/insights-client"
 
+"""
+:requirement: RHSS-291297
+:subsystemteam: sst_csi_client_tools
+:caseautomation: Automated
+:upstream: Yes
+"""
+
 
 def test_output_file_valid_parameters(insights_client, tmp_path):
-    """Test --output-file (with valid parameters)
-    Test --output-file option pointing to:
-        - a non-existing file (so a new one should be created properly)
+    """
+    :title: Tets Output File with Valid Parameters
+    :description: This test verifies that the --output-file option correctly
+    creates a new archive file when provided with a valid path
+    :tier: Tier 0
+    :steps:
+        1. Define the archive name path
+        2. Run insights-client in an offline mode with --output-file
+        pointing to the archive name
+        3. Verify that a new archive file is created
+        4. Verify that the command output confirms the collected
+        data was copied to the new archive
+    :expected results:
+        1. The archive name path is set correctly
+        2. The insights-client runs successfully with the specified output file path
+        3. A new archive file are created at the specified location
+        4. The command output confirms that the collected data was copied to the new
+        archive
     """
     archive_name = tmp_path / "archive"
 
@@ -24,9 +46,25 @@ def test_output_file_valid_parameters(insights_client, tmp_path):
 
 
 def test_output_file_non_existing_path(insights_client):
-    """Test --output-file (with invalid parameters)
-    Test --output-file option pointing to:
-        - not existing path (parent directory doesn't exist)
+    """
+    :title: test Output File with Non-Existing Path
+    :description: Checks that the --output-file option fails with an appropriate error
+    message when provided with a non-existent path
+    :tier: Tier 0
+    :steps:
+        1. Define an archive file path in a non-existing directory
+        2. Define the parent directory path
+        3. Run insights-client with the --output-file option pointing
+        to an non-existing path
+        4. Verify that the command output fails with a return code of 1
+        5. Verify that the error message indicates the parent directory
+        does not exist
+    :expected results:
+        1. The archive path is set to a non-existent directory
+        2. The parent directory path is correctly derived
+        3. The insights-client runs with the specified output file path
+        4. The command returns code of 1
+        5. The error message contains the expected message
     """
     archive_location = "/not-existing-dir/archive_file.tar.gz"
     parent_dir = os.path.dirname(archive_location)
@@ -39,15 +77,41 @@ def test_output_file_non_existing_path(insights_client):
 
 
 def test_output_dir_without_specifying_a_path(insights_client):
-    """Test --output-dir (without specifying path)"""
+    """
+    :title: Test Output Directory Without Specifying a Path
+    :description: Verifies that the --output-dir option fails with an appropriate
+    error message when no path is specified
+    :tier: Tier 0
+    :steps:
+        1. Run insights-client with an empty --output-file option
+        2. Verify that the command fails with a return code of 1
+        3. Verify that the error message indicates that --output-file cannot be empty
+    :expected results:
+        1. The insights-client runs with an emptu option
+        2. The command fails with a return code of 1
+        3. The error message is as expected
+    """
     cmd_result = insights_client.run("--output-file=", check=False)
     assert cmd_result.returncode == 1
     assert "ERROR: --output-file cannot be empty" in cmd_result.stderr
 
 
 def test_output_specifying_both_dir_and_file(insights_client, tmp_path):
-    """Test both --output-file and --output-dir (with valid parameters) at once.
-    This should fail with error message suggesting to specify only one at a time.
+    """
+    :title: Test Output Specifying Both Directory and File
+    :description: Verifies that specifying both output file and output directory
+    option together fails with an appropriate error message
+    :tier: Tier 0
+    :steps:
+        1. Define both output file and directory paths
+        2. Run insights-client with --output-file and --output-dir
+        3. Verify the command fails with an error code of 1
+        4. Verify the error message is appropriate and as expected
+    :expected results:
+        1. the output file and directory paths are set correctly
+        2. The insights-client runs with specified options
+        3. The command fails with a return code of 1
+        4. The error message is as expected
     """
     # Parent directory does not exist
     output_file = tmp_path / "output_file.tar.gz"
@@ -60,9 +124,22 @@ def test_output_specifying_both_dir_and_file(insights_client, tmp_path):
 
 
 def test_output_file_with_relative_path(insights_client):
-    """Test --output-file (with relative path)
-    Test --output-file option pointing to:
-        - relative path (so test will indicate path is already a directory)
+    """
+    :title: Test output File with Relative Path
+    :description: Verifies that using a relative path that points to a directory
+    with the --output-file option fails with an appropriate error message
+    :tier: Tier 0
+    :steps:
+        1. Define a relative path pointing to a directory
+        2. Run insights-client with the --output file option poining to
+        this relative path
+        3. Verify that the command fails with a return code of 1
+        4. Verify the error message is as expected
+    :expected results:
+        1. The relative path is correctly
+        2. The insights-client runs with the specified option
+        3. The command fails with an exit code of 1
+        4. The error message is as expected
     """
     relative_path = os.path.realpath("")
     cmd_result = insights_client.run(f"--output-file={relative_path}", check=False)
@@ -71,10 +148,21 @@ def test_output_file_with_relative_path(insights_client):
 
 
 def test_output_dir_with_not_empty_directory(insights_client):
-    """Test --output-dir (with not empty directory)
-    Test --output-dir option pointing to:
-        - execution path (just to indicate a not empty dir, so test will indicate
-          that dir already exists and is not empty)
+    """
+    :title: Test output Directory with Non-Empty Directory
+    :description: Verify that when the --output-dir option is used with an existing
+    non-empty directory, the command fails with an appropriate error message
+    :tier: Tier 0
+    :steps:
+        1. Define a path to an existing non-empty directory
+        2. Run insights-client with --output-dir option specified
+        3. Verify the command fails with a return code of 1
+        4. Verify the error message is as expected
+    :expected results:
+        1. The path to the non-empty directory is set correctly
+        3. The insights-client is run
+        4. The command fails with a return code of 1
+        5. The error message is as expected
     """
     relative_path = os.path.realpath("")
     cmd_result = insights_client.run(f"--output-dir={relative_path}", check=False)
@@ -86,10 +174,22 @@ def test_output_dir_with_not_empty_directory(insights_client):
 
 
 def test_output_dir_creates_archive_for_directory(insights_client, tmp_path):
-    """Test --output-file (indicating a directory, not a file)
-    Test --output-file option pointing to:
-        - existing directory (archive named should be generated combining
-        the name of directory+'.tar.gz')
+    """
+    :title: Test output Directory Creates Archive for Directory
+    :description: Checks that when the --output-file option is used with a path that is
+    an existing directory, the insights-client correctly generates an archive
+    with the directory name appended with .tar.gz
+    :tier: Tier 0
+    :steps:
+        1. Define a directory path
+        2. Run insights-client with the --output-file option pointing to that directory
+        3. Verify that the command creates an archive file with the directory name plus
+        4. Clean up by removing the generated archive file
+    :expected results:
+        1. The dorectory is set correctly
+        2. The insights-client runs with the specified dir path
+        3. An archive file with the directory name is created
+        4. The generated archive file is successfully removed
     """
     directory = "/tmp/directory/"
     try:
@@ -100,9 +200,22 @@ def test_output_dir_creates_archive_for_directory(insights_client, tmp_path):
 
 
 def test_output_file_already_exists(insights_client, tmp_path):
-    """Test --output-file (already existing archive)
-    Test --output-file option pointing to:
-        - already existing archive
+    """
+    :title: Test output File Already Exists
+    :description: Cerify that when the --output-file option is used with a path
+    that points
+    to an existing archive file, the command fails with an appropriate error message
+    :tier:
+    :steps:
+        1. Create an archive file at a specified location
+        2. Run insights-client with the --output-file option to this existing archive
+        3. Verify the command fails with a return code of 1
+        4. Verify that the error message indicates that the file already exists
+    :expected results:
+        1. The archive file is created at the specified location
+        2. The insights-client is run with the specified output file path
+        3. The command fails with a return code of 1
+        4. The error message indicates that the file aready exists
     """
     # File should already exist
     output_file = tmp_path / "output_file.tar.gz"
@@ -118,10 +231,24 @@ def test_output_file_already_exists(insights_client, tmp_path):
 @pytest.mark.usefixtures("register_subman")
 def test_cmd_timeout(insights_client):
     """
-    Test cmd_timeout config option
-    Client executes all commands with timeout. If the command doesn't finish within
-    a specified amount of seconds, it is killed.
-    Test that setting a custom amount of seconds to cmd_timeout config option works.
+    :title: Test CMD Timeout Configuration
+    :description: Verify that the cmd_timeout configuration correctly limits the
+    execution
+    time of commands, killing them if thez exceed said limit
+    :tier: Tier 1
+    :steps:
+        1. Register the insights-client
+        2. Set the cmd_timeout option to 10 seconds
+        3. Run insights-client with a command that would take lomger than the
+        the timeout limit
+        4. Verify the command is terminated after 10 seconds
+        5. Verify that the output includes expected message
+    :expected results:
+        1. The insights-client is registered
+        2. The cmd_timeout option is set to 10 seconds
+        3. The command is run with the specified timeout
+        4. The command is terminated after 10 seconds
+        5. The outpus is as expected
     """
     cmd_output_message = "Executing: [['timeout', '-s', '9', '10'"
 
@@ -138,12 +265,22 @@ def test_cmd_timeout(insights_client):
 @pytest.mark.usefixtures("register_subman")
 def test_branch_info(insights_client, test_config, subman):
     """
-    Test that branch_info includes all required information
-    branch_info is used to identify the host when it is connected via Satellite.
-    It uses branch_id and leaf_id to identify.
-    Ref:
-    https://docs.google.com/document/d/193mN5aBwxtzpP4U-vnL3yVawPxiG20n0zkzDYsam-eU/edit
-
+    :title: Test Branch Info Includes All Required Information
+    :description: Verify that the branch_info file generated by the insights-client
+    contains all necessary information for identifying the host when connected
+    via Satellite
+    :tier: Tier 2
+    :steps:
+        1. Register the insights-client
+        2. Run insights-client with the --no-upload option to generate the
+        branch_info file
+        3. Extract the latest archive
+        4. Inspect the branch_info file to verify it containes correct values
+    :expected results:
+        1. The insights-client is registered
+        2. The branch_info file is generated
+        3. The latest archive should be successfully extracted
+        4. The branch_info includes correct values
     """
     insights_client.register()
     assert conftest.loop_until(lambda: insights_client.is_registered)
@@ -172,7 +309,23 @@ def test_branch_info(insights_client, test_config, subman):
 @pytest.mark.usefixtures("register_subman")
 def test_archive_structure(insights_client):
     """
-    Test that the archive have the correct structure
+    :title: Test Archive Structure
+    :description: Verify that the generated archive from insights-client has the
+    correct directory structure and contains all the necessary dirs and subdirs
+    :tier: Tier 1
+    :steps:
+        1. Register insights-client
+        2. Run insights-client with --no-upload
+        3. Extract the latest archive
+        4. Verify that all required directories are present in the archive
+        5. Verify that all required subdirectories are present under the
+        data directory
+    :expected results:
+        1. Insights-client is registered
+        2. The archive is generated
+        3. The latest archive is extracted
+        4. All required directories are present
+        5. All required subdirectories are present
     """
     dirs_list = [
         "blacklist_report",