Migrate test_multiple_dirs, test_nodiff, and test_prefilter_cmd of test_fim/test_files documentation to qa-docs

tests/integration/test_fim/test_files/test_multiple_dirs/test_multiple_dirs.py

@@ -1,7 +1,78 @@
-# Copyright (C) 2015-2021, Wazuh Inc.
-# Created by Wazuh, Inc. <[email protected]>.
-# This program is free software; you can redistribute it and/or modify it under the terms of GPLv2
-
+'''
+copyright: Copyright (C) 2015-2021, Wazuh Inc.
+
+           Created by Wazuh, Inc. <[email protected]>.
+
+           This program is free software; you can redistribute it and/or modify it under the terms of GPLv2
+
+type: integration
+
+brief: File Integrity Monitoring (FIM) system watches selected files and triggering alerts
+       when these files are modified. Specifically, these tests will check if FIM detects
+       all file modification events when monitoring the maximum number of directories (64)
+       set in the 'directories' tag.
+       The FIM capability is managed by the 'wazuh-syscheckd' daemon, which checks configured
+       files for changes to the checksums, permissions, and ownership.
+
+tier: 1
+
+modules:
+    - fim
+
+components:
+    - agent
+    - manager
+
+daemons:
+    - wazuh-syscheckd
+
+os_platform:
+    - linux
+    - windows
+
+os_version:
+    - Arch Linux
+    - Amazon Linux 2
+    - Amazon Linux 1
+    - CentOS 8
+    - CentOS 7
+    - CentOS 6
+    - Ubuntu Focal
+    - Ubuntu Bionic
+    - Ubuntu Xenial
+    - Ubuntu Trusty
+    - Debian Buster
+    - Debian Stretch
+    - Debian Jessie
+    - Debian Wheezy
+    - Red Hat 8
+    - Red Hat 7
+    - Red Hat 6
+    - Windows 10
+    - Windows 8
+    - Windows 7
+    - Windows Server 2019
+    - Windows Server 2016
+    - Windows Server 2012
+    - Windows Server 2003
+    - Windows XP
+
+references:
+    - https://documentation.wazuh.com/current/user-manual/capabilities/file-integrity/index.html
+    - https://documentation.wazuh.com/current/user-manual/reference/ossec-conf/syscheck.html#directories
+
+pytest_args:
+    - fim_mode:
+        realtime: Enable real-time monitoring on Linux (using the 'inotify' system calls) and Windows systems.
+        whodata: Implies real-time monitoring but adding the 'who-data' information.
+    - tier:
+        0: Only level 0 tests are performed, they check basic functionalities and are quick to perform.
+        1: Only level 1 tests are performed, they check functionalities of medium complexity.
+        2: Only level 2 tests are performed, they check advanced functionalities and are slow to perform.
+
+tags:
+    - fim_multiple_dirs
+'''
 import os
 
 import pytest
@@ -62,20 +133,50 @@ def wait_for_event():
     (test_directories, {'multiple_dirs'})
 ])
 def test_multiple_dirs(dir_list, tags_to_apply, get_configuration, configure_environment, restart_syscheckd):
-    """
-    Check if syscheck can detect every event when adding, modifying and deleting a file within multiple monitored
-    directories.
-    Check that the maximum number of monitored directories are processed correctly, generating a warning,
-    and discarding the excess.
-
-    These directories will be added in one single entry like so:
-        <directories>testdir0, testdir1, ..., testdirn</directories>
-
-    Parameters
-    ----------
-    dir_list : list
-        List with all the directories to be monitored.
-    """
+    '''
+    description: Check if the 'wazuh-syscheckd' daemon detects every event when adding, modifying, and deleting
+                 a testing file within each one of the monitored directories. Also, it verifies that it limits
+                 the monitoring to the maximum allowed number of directories (64) set in the 'directories' tag.
+                 For this purpose, the test will try to monitor an upper number of folders allowed and make
+                 file operations inside them. Then, it will check if all FIM events are generated for
+                 each file operation made. Finally, the test will verify that the number of FIM events
+                 generated corresponds with the limit of monitored directories.
+
+    wazuh_min_version: 4.2.0
+
+    parameters:
+        - dir_list:
+            type: list
+            brief: List with the directories to be monitored.
+        - tags_to_apply:
+            type: set
+            brief: Run test if matches with a configuration identifier, skip otherwise.
+        - get_configuration:
+            type: fixture
+            brief: Get configurations from the module.
+        - configure_environment:
+            type: fixture
+            brief: Configure a custom environment for testing.
+        - restart_syscheckd:
+            type: fixture
+            brief: Clear the 'ossec.log' file and start a new monitor.
+
+    assertions:
+        - Verify that FIM events are generated for all monitored folders set
+          in the 'directories' tag to a limit of 64.
+
+    input_description: A test case (multiple_dirs) is contained in external YAML file (multiple_dirs.yaml)
+                       which includes configuration settings for the 'wazuh-syscheckd' daemon and, these are
+                       combined with the testing directories to be monitored defined in the module.
+
+    expected_output:
+        - r'.*Sending FIM event: (.+)$' ('added', 'modified', and 'deleted' events)
+
+    tags:
+        - realtime
+        - scheduled
+        - who_data
+    '''
     check_apply_test(tags_to_apply, get_configuration['tags'])
 
     discarded = wait_for_event()

tests/integration/test_fim/test_files/test_multiple_dirs/test_multiple_entries.py

@@ -1,7 +1,78 @@
-# Copyright (C) 2015-2021, Wazuh Inc.
-# Created by Wazuh, Inc. <[email protected]>.
-# This program is free software; you can redistribute it and/or modify it under the terms of GPLv2
-
+'''
+copyright: Copyright (C) 2015-2021, Wazuh Inc.
+
+           Created by Wazuh, Inc. <[email protected]>.
+
+           This program is free software; you can redistribute it and/or modify it under the terms of GPLv2
+
+type: integration
+
+brief: File Integrity Monitoring (FIM) system watches selected files and triggering alerts
+       when these files are modified. Specifically, these tests will check if FIM detects
+       all file modification events when monitoring the maximum number of directories (64)
+       set using multiple 'directories' tags.
+       The FIM capability is managed by the 'wazuh-syscheckd' daemon, which checks configured
+       files for changes to the checksums, permissions, and ownership.
+
+tier: 1
+
+modules:
+    - fim
+
+components:
+    - agent
+    - manager
+
+daemons:
+    - wazuh-syscheckd
+
+os_platform:
+    - linux
+    - windows
+
+os_version:
+    - Arch Linux
+    - Amazon Linux 2
+    - Amazon Linux 1
+    - CentOS 8
+    - CentOS 7
+    - CentOS 6
+    - Ubuntu Focal
+    - Ubuntu Bionic
+    - Ubuntu Xenial
+    - Ubuntu Trusty
+    - Debian Buster
+    - Debian Stretch
+    - Debian Jessie
+    - Debian Wheezy
+    - Red Hat 8
+    - Red Hat 7
+    - Red Hat 6
+    - Windows 10
+    - Windows 8
+    - Windows 7
+    - Windows Server 2019
+    - Windows Server 2016
+    - Windows Server 2012
+    - Windows Server 2003
+    - Windows XP
+
+references:
+    - https://documentation.wazuh.com/current/user-manual/capabilities/file-integrity/index.html
+    - https://documentation.wazuh.com/current/user-manual/reference/ossec-conf/syscheck.html#directories
+
+pytest_args:
+    - fim_mode:
+        realtime: Enable real-time monitoring on Linux (using the 'inotify' system calls) and Windows systems.
+        whodata: Implies real-time monitoring but adding the 'who-data' information.
+    - tier:
+        0: Only level 0 tests are performed, they check basic functionalities and are quick to perform.
+        1: Only level 1 tests are performed, they check functionalities of medium complexity.
+        2: Only level 2 tests are performed, they check advanced functionalities and are slow to perform.
+
+tags:
+    - fim_multiple_dirs
+'''
 import os
 
 import pytest
@@ -81,20 +152,48 @@ def get_configuration(request):
 ])
 def test_cud_multiple_dir_entries(dir_list, tags_to_apply, get_configuration, configure_environment, restart_syscheckd,
                                   wait_for_fim_start):
-    """
-    Check if syscheck can detect every event when adding, modifying and deleting a file within multiple monitored
-    directories.
-
-    These directories will be added using a new entry for every one of them:
-        <directories>testdir0</directories>
-        ...
-        <directories>testdirn</directories>
-
-    Parameters
-    ----------
-    dir_list : list
-        List with all the directories to be monitored.
-    """
+    '''
+    description: Check if the 'wazuh-syscheckd' daemon detects every event when adding, modifying, and deleting
+                 a testing file within each one of the monitored directories. Also, it verifies that it can monitor
+                 the maximum allowed number of folders using multiple 'directories' tags (64). For this purpose,
+                 the test will monitor multiple folders and make file operations inside them. Then, it will check
+                 if all FIM events are generated for each file operation made. Finally, the test will verify that
+                 the number of FIM events generated corresponds with the monitored directories.
+
+    wazuh_min_version: 4.2.0
+
+    parameters:
+        - dir_list:
+            type: list
+            brief: List with the directories to be monitored.
+        - tags_to_apply:
+            type: set
+            brief: Run test if matches with a configuration identifier, skip otherwise.
+        - get_configuration:
+            type: fixture
+            brief: Get configurations from the module.
+        - configure_environment:
+            type: fixture
+            brief: Configure a custom environment for testing.
+        - restart_syscheckd:
+            type: fixture
+            brief: Clear the 'ossec.log' file and start a new monitor.
+
+    assertions:
+        - Verify that FIM events are generated for all monitored folders set
+          in multiple 'directories' (up to a limit of 64).
+
+    input_description: A test case (multiple_dir_entries) is contained in external YAML file
+                       (multiple_entries.yaml) which includes configuration settings for
+                       the 'wazuh-syscheckd' daemon and testing directories to be monitored.
+
+    expected_output:
+        - r'.*Sending FIM event: (.+)$' ('added', 'modified', and 'deleted' events)
+
+    tags:
+        - scheduled
+        - who_data
+    '''
     check_apply_test(tags_to_apply, get_configuration['tags'])
 
     file = 'regular'