Filewatcher

Stop polling files. Start waiting for events.

A modern Robot Framework library for event-driven filesystem testing.

robotframework-filewatcher allows Robot Framework tests to monitor file creation, modification, deletion, and file stability using native OS filesystem events powered by watchdog.

Unlike polling-based approaches, FileWatcher maintains a thread-safe event history, supports multiple concurrent waiters, and provides high-level Robot Framework keywords for waiting, querying, and validating filesystem activity.

You can find the keyword documentation here

Supports:

• Windows
• Linux
• macOS

Perfect for:

• Download verification
• Generated report validation
• Export/import workflow testing
• Batch file processing
• Background file synchronization
• Event-driven automation pipelines

---

Why FileWatcher?

Traditional Robot Framework file checks often become:

FOR    ${i}    IN RANGE    30
    File Should Exist    report.xlsx
    Sleep    1s
END

That is slow, brittle, and prone to race conditions.

With FileWatcher:

Start Watching Directory    ${DOWNLOADS}
Click Export
${event}=    Wait For File Created    report.xlsx
Log    ${event}[src_path]

No polling. No arbitrary sleeps. No flaky timing.

---

Architecture

FileWatcher is built around:

• A single shared watchdog.Observer
• DirectoryEventHandler converting OS events into file events
• A thread-safe EventStore
• Non-consuming historical event retention
• Multiple concurrent waiters and keyword consumers
• Bounded memory storage for safety

OS Events
  ↓
watchdog Observer
  ↓
DirectoryEventHandler
  ↓
EventStore
  ↓
Robot Framework Keywords

---

Feature Matrix

Category	Keywords
Watching	Start Watching Directory, Stop Watching Directory, Is Watching Directory, Get Watched Directories
Waiting	Wait For File Created, Wait For File Modified, Wait For File Deleted, Wait Until File Stable, Wait Until Directory Is Not Empty, Wait Until Directory Is Empty, Wait Until File Count Is, Wait Until File Size Is, Wait Until File Checksum Changes, File Should Not Change
Discovery	Get Latest File, Get Oldest File, Find Files Matching Pattern, Get File Count, Get File Checksum, File Checksum Should Be
Events	Get File Events, Get File Events Since, Get Current Event Id, Get Event Statistics, Get New Files Since, Get Deleted Files Since, Clear Event History, Should Have File Event

---

Implementation note:

The keyword categories above are implemented across two internal modules in the package:

• src/FileWatcher/keywords/watching.py implements the "Watching" keywords.
• src/FileWatcher/keywords/waiting.py implements the "Waiting", "Discovery", and "Events" keywords.

Quick Start

Install from PyPi

pip install robotframework-filewatcher

Install from the repository:

pip install .

Install development dependencies:

pip install -e ".[dev]"

---

Simple Example

*** Settings ***
Library    FileWatcher

*** Test Cases ***
Wait For Generated Report
    Start Watching Directory    ${DOWNLOAD_DIR}
    Click Button    Generate Report
    ${event}=    Wait For File Created    report.xlsx
    Log    Generated report path: ${event}[src_path]

---

Common Use Cases

• Wait for browser downloads to complete
• Validate generated report files
• Monitor export and import workflows
• Track batch file production
• Detect deleted files or cleanup actions
• Observe background processes writing to disk

---

Example Robot Framework Usage

*** Settings ***
Library    FileWatcher
Library    OperatingSystem

Suite Teardown    Clean Up Watches

*** Variables ***
${DOWNLOAD_DIR}    ${CURDIR}${/}downloads

*** Test Cases ***
Verify File Stability
    [Setup]    Run Keywords    Create Directory    ${DOWNLOAD_DIR}    AND    Clear Event History
    Start Watching Directory    ${DOWNLOAD_DIR}

    Create File    ${DOWNLOAD_DIR}${/}report_draft.xlsx    Initial chunk...
    ${event}=    Wait Until File Stable    report_draft.xlsx    stability_time=1.0    timeout=10.0
    Log To Console    File stabilized at path: ${event}[src_path]

    ${since_id}=    Set Variable    ${event}[id]
    Append To File    ${DOWNLOAD_DIR}${/}report_draft.xlsx    Final chunk.
    ${mod_event}=    Wait For File Modified    report_draft.xlsx    since_id=${since_id}
    Log To Console    Updated event recorded: ${mod_event}

*** Keywords ***
Clean Up Watches
    Stop Watching Directory    ${DOWNLOAD_DIR}
    Remove Directory    ${DOWNLOAD_DIR}    recursive=True

*** Example ***
File History and Checksum Validation
    [Setup]    Create Directory    ${DOWNLOAD_DIR}
    Start Watching Directory    ${DOWNLOAD_DIR}

    # Wait until a new export appears and capture its path
    ${event}=    Wait For File Created    export*.zip
    Log To Console    Export created at: ${event}[src_path]

    # Validate checksum after the file is fully written
    ${sha256}=    Get File Checksum    ${event}[src_path]
    File Checksum Should Be    ${event}[src_path]    ${sha256}

    # Use event history to discover new and deleted files
    ${checkpoint}=    Get Current Event Id
    # perform cleanup or batch export action here
    ${new_files}=    Get New Files Since    ${checkpoint}
    ${deleted_files}=    Get Deleted Files Since    ${checkpoint}
    Log To Console    New files since checkpoint: ${new_files}
    Log To Console    Deleted files since checkpoint: ${deleted_files}

---

Running Tests

pytest

PYTHONPATH=src robot tests/acceptance.robot

---

License

Apache-2.0