doc: Add of test_logcollector documentation in QA Docs style

The following tests have been documentated:
  * test_reconnect_time.py
  * test_statistics_macos.py
The current scheme of the issue #1694 has been used.
PEP-8 fixes.

Closes: #1813

tests/integration/test_logcollector/test_macos/test_macos_multiline_values.py

@@ -126,7 +126,7 @@ def test_macos_multiline_values(restart_logcollector_required_daemons_package, g
 
  expected_output:
  - r'Monitoring macOS logs with.*'
- - r'Here is a multiline log. Line 0 \nLine 1. \nLast line.'
+ - r'Here is a multiline log.*'
 
  tags:
  - logs

tests/integration/test_logcollector/test_reconnect_time/test_reconnect_time.py

@@ -1,6 +1,51 @@
-# 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: The 'wazuh-logcollector' daemon monitors configured files and commands for new log messages.
+ Specifically, these tests will check if the logcollector uses the interval of reconnection
+ attempts when the Windows Event Channel service is down, defined in the 'reconnect_time' tag.
+ Log data collection is the real-time process of making sense out of the records generated by
+ servers or devices. This component can receive logs through text files or Windows event logs.
+ It can also directly receive logs via remote syslog which is useful for firewalls and
+ other such devices.
+
+tier: 0
+
+modules:
+ - logcollector
+
+components:
+ - agent
+
+daemons:
+ - wazuh-logcollector
+
+os_platform:
+ - windows
+
+os_version:
+ - 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/log-data-collection/index.html
+ - https://documentation.wazuh.com/current/user-manual/reference/ossec-conf/localfile.html#reconnect-time
+
+tags:
+ - logcollector_reconnect_time
+'''
 import os
 import pytest
 from datetime import timedelta, datetime
@@ -70,12 +115,59 @@ def get_local_internal_options():
 
 def test_reconnect_time(get_local_internal_options, configure_local_internal_options, get_configuration,
  configure_environment, restart_logcollector):
- """Check if reconnect_time value works properly
-
- Ensure correspond debug logs are generated when Windows event log service stop. Also, when event log service is
- restarted, `wazuh-agent` should reconnect to it using reconnect_time value.
- """
-
+ '''
+ description: Check if the 'wazuh-logcollector' daemon uses the interval of reconnection attempts when
+ the Windows Event Channel service is down. That interval is set in the 'reconnect_time' tag.
+ For this purpose, the test will configure a 'localfile' section to monitor a windows 'event
+ log', and once the logcollector is started, it will verify that the 'event log' is being
+ monitored by detecting the event that indicates it. Then, the test will stop the event
+ channel service and wait for the event that indicates that the 'event log' is unavailable.
+ After this, it will verify that the 'trying to reconnect' event includes the time set in
+ the 'reconnect_time' tag and start the event channel service again. Finally, the test
+ will verify that the event indicating the successful reconnection to the 'event log'
+ is generated in the time set by the 'reconnect_time' tag.
+
+ wazuh_min_version: 4.2.0
+
+ parameters:
+ - get_local_internal_options:
+ type: fixture
+ brief: Get local internal options from the module.
+ - configure_local_internal_options:
+ type: fixture
+ brief: Configure the Wazuh local internal options.
+ - get_configuration:
+ type: fixture
+ brief: Get configurations from the module.
+ - configure_environment:
+ type: fixture
+ brief: Configure a custom environment for testing.
+ - restart_logcollector:
+ type: fixture
+ brief: Clear the 'ossec.log' file and start a new monitor.
+
+ assertions:
+ - Verify that the logcollector starts monitoring an 'event log'.
+ - Verify that the logcollector detects when the 'event channel' service is down generating an event.
+ - Verify that the logcollector tries to reconnect to an unavailable 'even log'
+ using the time specified in the 'reconnect_time' tag.
+ - Verify that the logcollector generates an event when successfully reconnects to an 'event log'.
+
+ input_description: A configuration template (test_reconnect_time) is contained in an external YAML file
+ (wazuh_reconnect_time.yaml). That template is combined with different test cases
+ defined in the module. Those include configuration settings
+ for the 'wazuh-logcollector' daemon.
+
+ expected_output:
+ - r'Analyzing event log.*'
+ - r'The eventlog service is down. Unable to collect logs from .* channel.'
+ - r'Trying to reconnect .* channel in .* seconds.'
+ - r'.* channel has been reconnected succesfully.'
+
+ tags:
+ - logs
+ - time_travel
+ '''
  config = get_configuration['metadata']
 
  if time_to_seconds(config['reconnect_time']) >= timeout_callback_reconnect_time:

tests/integration/test_logcollector/test_statistics/test_statistics_macos.py

@@ -1,6 +1,45 @@
-# 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: The 'wazuh-logcollector' daemon monitors configured files and commands for new log messages.
+ Specifically, these tests will check if the logcollector updates the 'wazuh-logcollector.state'
+ file when using the macOS unified logging system (ULS). Log data collection is the real-time
+ process of making sense out of the records generated by servers or devices. This component can
+ receive logs through text files or Windows event logs. It can also directly receive logs via
+ remote syslog which is useful for firewalls and other such devices.
+
+tier: 1
+
+modules:
+ - logcollector
+
+components:
+ - agent
+
+daemons:
+ - wazuh-logcollector
+
+os_platform:
+ - macos
+
+os_version:
+ - macOS Catalina
+
+references:
+ - https://documentation.wazuh.com/current/user-manual/capabilities/log-data-collection/index.html
+ - https://documentation.wazuh.com/current/user-manual/reference/ossec-conf/localfile.html
+ - https://documentation.wazuh.com/current/user-manual/reference/statistics-files/wazuh-logcollector-state.html
+ - https://documentation.wazuh.com/current/user-manual/reference/internal-options.html#logcollector
+
+tags:
+ - logcollector_statistics
+'''
 import os
 import pytest
 
@@ -31,7 +70,8 @@
 
 local_internal_options = {'logcollector.state_interval': 1}
 
-daemons_handler_configuration = {'daemons': ['wazuh-logcollector', 'wazuh-agentd', 'wazuh-execd'], 'ignore_errors': False}
+daemons_handler_configuration = {'daemons': ['wazuh-logcollector', 'wazuh-agentd', 'wazuh-execd'],
+ 'ignore_errors': False}
 
 
 @pytest.fixture(scope='module', params=configurations, ids=configuration_ids)
@@ -40,17 +80,47 @@ def get_configuration(request):
  return request.param
 
 
-def test_options_state_interval_no_file(configure_local_internal_options_module,
- get_configuration,
- configure_environment,
- daemons_handler):
- """Check if the monitored file appears in logcollector.state.
-
- Raises:
- AssertionError: If the elapsed time is different from the interval.
- TimeoutError: If the expected callback is not generated in the expected time.
- """
-
+def test_options_state_interval_no_file(configure_local_internal_options_module, get_configuration,
+ configure_environment, daemons_handler):
+ '''
+ description: Check if the 'wazuh-logcollector' daemon updates the statistic file 'wazuh-logcollector.state'
+ when using the macOS unified logging system (ULS). For this purpose, the test will configure
+ a 'localfile' section using the macOS settings. Once the logcollector is started, it will check
+ if the 'wazuh-logcollector.state' file has been created. Finally, the test will verify that the
+ 'wazuh-logcollector.state' has the 'macos' value in its 'location' tag of the 'global' and
+ 'interval' sections.
+
+ wazuh_min_version: 4.2.0
+
+ parameters:
+ - configure_local_internal_options_module:
+ type: fixture
+ brief: Set internal configuration for testing.
+ - get_configuration:
+ type: fixture
+ brief: Get configurations from the module.
+ - configure_environment:
+ type: fixture
+ brief: Configure a custom environment for testing.
+ - daemons_handler:
+ type: fixture
+ brief: Handler of Wazuh daemons.
+
+ assertions:
+ - Verify that the logcollector creates the 'wazuh-logcollector.state' file.
+ - Verify that the 'macos' value is in the 'location' tag in the 'global' and 'interval' sections
+ of the 'wazuh-logcollector.state' file.
+
+ input_description: A configuration template (test_statistics_macos) is contained in an external YAML file
+ (wazuh_statistics_macos.yaml). That template is combined with a test case defined in
+ the module. Those include configuration settings for the 'wazuh-logcollector' daemon.
+
+ expected_output:
+ - The content of the 'wazuh-logcollector.state' file.
+
+ tags:
+ - stats_file
+ '''
  # Ensure wazuh-logcollector.state is created
  logcollector.wait_statistics_file(timeout=logcollector_stats_file_tout)