file_content_matches_regex
===========================

.. role:: status-tested
   :class: status-tested

:Status: :status-tested:`● Tested`
:Category: File System
:Function Name: ``file_content_matches_regex``

**Tests if file content matches a given regular expression.**

This test function reads a file and checks if its content matches the provided regular expression pattern. It's useful for validating log entries, configuration values, or any structured text content.

Parameters
----------

.. list-table::
   :widths: 20 15 65
   :header-rows: 1

   * - Parameter
     - Type
     - Description
   * - ``dst``
     - string
     - **Required.** The file path to read and test. Supports glob patterns for dynamic path resolution.
   * - ``regex``
     - string
     - **Required.** The regular expression pattern to match against the file content.
   * - ``encoding``
     - string
     - **Optional.** Text encoding to use when reading the file (default: "utf-8"). Common values: "utf-8", "utf-16", "latin-1", "ascii". Use "BOM" to auto-detect encoding from file's Byte Order Mark.
   * - ``strip_bom``
     - boolean
     - **Optional.** Remove Byte Order Mark (BOM) from file content before regex matching (default: false). Useful for Windows files that include BOM.

Usage Example
-------------

Log File Validation
~~~~~~~~~~~~~~~~~~~

.. code-block:: yaml

   tests:
     - name: verify_error_logged
       function: file_content_matches_regex
       parameter:
         dst: "/var/log/application.log"
         regex: "ERROR.*Authentication failed.*user:.*"
       description: "Verify authentication error was logged with user details"

Configuration Validation
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: yaml

   tests:
     - name: check_config_value
       function: file_content_matches_regex
       parameter:
         dst: "/etc/myapp/config.ini"
         regex: "port\\s*=\\s*8080"
       description: "Verify port is configured correctly"

Multi-line Pattern Matching
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: yaml

   tests:
     - name: verify_sql_query
       function: file_content_matches_regex
       parameter:
         dst: "/tmp/generated_query.sql"
         regex: "SELECT\\s+\\*\\s+FROM\\s+users\\s+WHERE\\s+active\\s*=\\s*1"
       description: "Verify correct SQL query was generated"

Windows UTF-16 File Pattern Matching
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: yaml

   tests:
     - name: verify_windows_config
       function: file_content_matches_regex
       parameter:
         dst: "C:\\Program Files\\MyApp\\config.txt"
         regex: "version\\s*=\\s*[0-9]+\\.[0-9]+\\.[0-9]+"
         encoding: "utf-16"
       description: "Verify version number pattern in UTF-16 encoded config file"

BOM Handling Examples
~~~~~~~~~~~~~~~~~~~~~

.. code-block:: yaml

   tests:
     # Match pattern in file with BOM, strip BOM first
     - name: match_pattern_with_bom
       function: file_content_matches_regex
       parameter:
         dst: "/path/to/windows_file.log"
         regex: "^ERROR.*failed$"
         encoding: "utf-8"
         strip_bom: true
       description: "Match error pattern, ignoring BOM at start"

     # Auto-detect encoding and match pattern
     - name: match_pattern_auto_encoding
       function: file_content_matches_regex
       parameter:
         dst: "/path/to/unknown_file.txt"
         regex: "\\bSUCCESS\\b.*\\d{4}-\\d{2}-\\d{2}"
         encoding: "BOM"
         strip_bom: true
       description: "Auto-detect encoding and match success pattern"

Common Use Cases
----------------

**Log Analysis**
  Validate that specific events, errors, or patterns appear in log files

**Configuration Verification**
  Ensure configuration files contain expected values or settings

**Generated Content Validation**
  Verify that automated processes generate content with expected patterns

**Data Format Verification**
  Confirm that exported data follows expected formats

**Template Output Validation**
  Ensure template processing produces content matching expected patterns

**Forensic Analysis**
  Search for specific patterns in files that might indicate malicious activity

Regular Expression Tips
-----------------------

**Case Sensitivity**
  Regex matching is case-sensitive by default. Use ``(?i)`` for case-insensitive matching:

  .. code-block:: yaml

     regex: "(?i)error.*authentication"

**Multiline Matching**
  Use ``.*`` to match across lines, or specific line break patterns:

  .. code-block:: yaml

     regex: "START.*END"  # Matches across multiple lines

**Escaping Special Characters**
  Escape regex special characters with backslashes:

  .. code-block:: yaml

     regex: "\\$\\{.*\\}"  # Matches ${...} patterns

Return Values
-------------

**Success**
  Returns success when the file content matches the regular expression

**Failure**
  Returns failure when:

  - The file content does not match the regular expression
  - The file exists but is empty and the regex expects content

**Execution Error**
  Returns execution error when:

  - The file cannot be found or read
  - The regular expression pattern is invalid
  - Permission denied reading the file
  - Path resolution fails due to glob pattern ambiguity
  - Unicode decoding errors occur (try specifying correct encoding parameter)

Example Results
---------------

.. code-block:: yaml

   # Success case
   result: success
   message: "File content matches regex pattern"

   # Failure case
   result: failed
   details:
     - "file content does not match regex expression"

   # Execution error - invalid regex
   result: execution_error
   error: "re.error: unterminated character set at position 10"
   context: "Invalid regex pattern: [abc"

   # Execution error - file not found
   result: execution_error
   error: "FileNotFoundError"
   context: "file with path /missing/file.log does not exist"