file_content_contains¶

Status:: ● Tested
Category:: File System
Function Name:: file_content_contains

Tests if file content contains specified string or byte pattern.

This test function reads a file and checks if it contains the specified content. It supports both string-based and byte-based pattern matching, making it versatile for text files and binary files.

Parameters¶

Parameter	Type	Description
`dst`	string	Required. The file path to read and test. Supports glob patterns for dynamic path resolution.
`content`	string	Required. The content to search for within the file.
`content_type`	string	Optional. Either “string” (default) or “bytes”. Determines how content is interpreted.
`encoding`	string	Optional. Text encoding to use when reading the file for string content (default: “utf-8”). Ignored for byte content. 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 searching (default: false). Only applies to string content type. Useful for Windows files that include BOM.

Usage Example¶

Text Content Search¶

tests:
  - name: verify_error_in_log
    function: file_content_contains
    parameter:
      dst: "/var/log/application.log"
      content: "Authentication failed for user"
      content_type: "string"
    description: "Verify authentication error appears in log"

Binary Content Search¶

tests:
  - name: check_binary_signature
    function: file_content_contains
    parameter:
      dst: "/tmp/generated_file.bin"
      content: "\\x50\\x4B\\x03\\x04"  # ZIP file signature
      content_type: "bytes"
    description: "Verify file contains ZIP signature"

Log Monitoring¶

actions:
  - click:
      target:
        text: "Process Data"

tests:
  - name: verify_processing_logged
    function: file_content_contains
    parameter:
      dst: "/var/log/processor.log"
      content: "Data processing completed successfully"
    description: "Verify processing completion was logged"

Windows UTF-16 Log Analysis¶

tests:
  - name: check_windows_event_log
    function: file_content_contains
    parameter:
      dst: "C:\\Windows\\Logs\\application.log"
      content: "Service started successfully"
      content_type: "string"
      encoding: "utf-16"
    description: "Search for service start message in UTF-16 encoded log"

BOM Handling Examples¶

tests:
  # Search in file with BOM, automatically strip BOM
  - name: search_in_bom_file
    function: file_content_contains
    parameter:
      dst: "/path/to/windows_file.txt"
      content: "Error occurred"
      content_type: "string"
      encoding: "utf-8"
      strip_bom: true
    description: "Search for error message, ignoring BOM"

  # Auto-detect encoding and search
  - name: search_unknown_encoding
    function: file_content_contains
    parameter:
      dst: "/path/to/unknown_file.txt"
      content: "SUCCESS"
      content_type: "string"
      encoding: "BOM"
      strip_bom: true
    description: "Auto-detect encoding from BOM and search"

Common Use Cases¶

Log File Analysis: Search for specific events, errors, or messages in log files
Configuration Validation: Verify that configuration files contain required settings or values
Generated Content Verification: Ensure generated files contain expected content or markers
Error Detection: Monitor files for error messages or failure indicators
Binary File Analysis: Search for specific byte patterns or signatures in binary files
Process Monitoring: Verify that processes write expected status or completion messages
Forensic Analysis: Search for specific patterns that might indicate malicious activity or data presence

Content Type Details¶

String Content (default)

File is read as text using the specified encoding (default: UTF-8) with error handling
Search is performed on the decoded string content
Suitable for text files, logs, configuration files
Use the encoding parameter to handle different character encodings
BOM can be automatically detected and optionally stripped before searching

Byte Content

File is read in binary mode
Content parameter is parsed for escape sequences (\x41, \n, \t, etc.)
Search is performed on raw byte data
Suitable for binary files, executables, or specific byte pattern detection

Escape Sequence Examples¶

When using content_type: "bytes", you can use Python-style escape sequences:

# Search for null-terminated string
content: "admin\\x00"

# Search for newline patterns
content: "\\r\\n\\r\\n"

# Search for specific hex patterns
content: "\\xFF\\xFE"

Return Values¶

Success

Returns success when the specified content is found within the file

Failure

Returns failure when:

The specified content is not found in the file
File is empty and content is expected

Execution Error

Returns execution error when:

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

Example Results¶

# Success case - string content
result: success
details:
  - "string content found in file"

# Success case - byte content
result: success
details:
  - "byte pattern found in file"

# Failure case
result: failed
details:
  - "string content not found in file"

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