Metadata-Version: 2.4
Name: robotframework-filewatcher
Version: 0.1.0
Summary: A Robot Framework library for file system monitoring using watchdog.
Author-email: Deekshith Poojary <deekshithpoojary355@gmail.com>
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/deekshith-poojary98/robotframework-filewatcher
Project-URL: Bug Tracker, https://github.com/deekshith-poojary98/robotframework-filewatcher/issues
Project-URL: Documentation, https://github.com/deekshith-poojary98/robotframework-filewatcher#readme
Keywords: robotframework,filesystem,monitoring,watchdog,testing,automation
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Robot Framework
Classifier: Framework :: Robot Framework :: Library
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: robotframework>=7.0.0
Requires-Dist: watchdog>=4.0.0
Requires-Dist: robotframework-pythonlibcore>=4.3.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: types-setuptools; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Dynamic: license-file

<div align="center">

<h1>Filewatcher</h1>

<h3>Stop polling files. Start waiting for events.</h3>

<p>
<i>A modern Robot Framework library for event-driven filesystem testing.</i>
</p>

<br>

<a href="https://badge.fury.io/py/robotframework-filewatcher">
    <img src="https://badge.fury.io/py/robotframework-filewatcher.svg" alt="PyPI version">
</a>

<img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+">

<img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License">

<a href="https://github.com/deekshith-poojary98/robotframework-filewatcher/actions/workflows/code-checks.yml">
    <img src="https://github.com/deekshith-poojary98/robotframework-filewatcher/actions/workflows/code-checks.yml/badge.svg" alt="CI Tests">
</a>

<a href="https://github.com/deekshith-poojary98/robotframework-filewatcher/actions/workflows/generate-docs.yml">
    <img src="https://github.com/deekshith-poojary98/robotframework-filewatcher/actions/workflows/generate-docs.yml/badge.svg" alt="Docs Build">
</a>

</div>
<br>


`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](https://deekshith-poojary98.github.io/robotframework-filewatcher/)

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:

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

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

With FileWatcher:

```robot
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 File Count Is` |
| Discovery | `Get Latest File`, `Find Files Matching Pattern`, `Get File Count` |
| Events | `Get File Events`, `Get File Events Since`, `Get Current Event Id`, `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 

Install from the repository:

```bash
pip install .
```

Install development dependencies:

```bash
pip install -e ".[dev]"
```

---

## Simple Example

```robot
*** 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

```robot
*** 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
```

---

## Running Tests

```bash
pytest
```

```bash
PYTHONPATH=src robot tests/acceptance.robot
```

---

## License

Apache-2.0
