robotframework-parallelrunner 0.2.0__tar.gz

robotframework_parallelrunner-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cristian Garcia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

robotframework_parallelrunner-0.2.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: robotframework-parallelrunner
+Version: 0.2.0
+Summary: Run a keyword in parallel inside a single Robot Framework test case, with one clean, ordered log.html.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: robotframework,robot-framework,parallel,threading,testing,automation
+Author: Cristian Garcia
+Author-email: cristian.garcia.vd@gmail.com
+Requires-Python: >=3.9
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Robot Framework
+Classifier: Framework :: Robot Framework :: Library
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Provides-Extra: playwright-example
+Requires-Dist: playwright (>=1.40) ; extra == "playwright-example"
+Requires-Dist: robotframework (>=5.0)
+Project-URL: Changelog, https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://cristiangarciavd.github.io/robotframework-parallelrunner/ParallelRunner.html
+Project-URL: Homepage, https://github.com/cristiangarciavd/robotframework-parallelrunner
+Project-URL: Issues, https://github.com/cristiangarciavd/robotframework-parallelrunner/issues
+Project-URL: Repository, https://github.com/cristiangarciavd/robotframework-parallelrunner
+Description-Content-Type: text/markdown
+
+# ParallelRunner
+
+[![PyPI](https://img.shields.io/pypi/v/robotframework-parallelrunner)](https://pypi.org/project/robotframework-parallelrunner/)
+[![Python versions](https://img.shields.io/pypi/pyversions/robotframework-parallelrunner)](https://pypi.org/project/robotframework-parallelrunner/)
+[![Tests](https://github.com/cristiangarciavd/robotframework-parallelrunner/actions/workflows/tests.yml/badge.svg)](https://github.com/cristiangarciavd/robotframework-parallelrunner/actions/workflows/tests.yml)
+
+**Run a loop inside a single Robot Framework test case in parallel — with one clean `log.html`, not a merge of many.**
+
+ParallelRunner is a small Robot Framework library that lets you fan a
+keyword out across a thread pool from *within* a test case — e.g. hit 100
+API endpoints, or repeat one check N times — and get back a single,
+correctly ordered `log.html` plus a structured list of per-item results.
+
+**Keyword documentation:** <https://cristiangarciavd.github.io/robotframework-parallelrunner/ParallelRunner.html>
+
+## Installation
+
+```bash
+pip install robotframework-parallelrunner
+```
+
+Requires Python 3.9+ and Robot Framework 5.0+ (installed automatically).
+See [docs/INSTALLATION.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/docs/INSTALLATION.md) for development installs
+and upgrading from the pre-release import path.
+
+## Quickstart
+
+The keyword you want to parallelize is a method of a Python library. It
+receives the current item first, and an injected `_logger` it should log
+through (so logs from different threads never interleave):
+
+```python
+# my_library.py
+class MyLibrary:
+    def verify_agent_data(self, agent_id, _logger=None, **kwargs):
+        _logger(f"Checking agent {agent_id}")
+        ...
+        return result
+```
+
+```robot
+*** Settings ***
+Library    ParallelRunner
+Library    my_library.MyLibrary
+
+*** Test Cases ***
+Verify Agents In Parallel
+    ${agents}=    Create List    1    2    3    4    5
+    ${results}=    Run Parallel Scenarios
+    ...    keyword=Verify Agent Data
+    ...    library=my_library.MyLibrary
+    ...    for_loop_iterable=${agents}
+```
+
+```bash
+robot --pythonpath . my_suite.robot
+```
+
+See [docs/QUICKSTART.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/docs/QUICKSTART.md) for a full walkthrough and
+[docs/API_REFERENCE.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/docs/API_REFERENCE.md) for every parameter of
+`Run Parallel Scenarios`. For the internal design (log buffering, thread
+safety), see [ARCHITECTURE.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/ARCHITECTURE.md).
+
+## Why This Works
+
+**Thread safety.** We avoid `BuiltIn().run_keyword()` inside threads, which is
+the main cause of crashes in multi-threaded Robot Framework. We call the
+underlying Python methods directly instead.
+
+**No log interleaving.** Each worker thread buffers its own log messages in
+memory. Once every task finishes, the main thread replays all buffered logs
+sequentially into Robot Framework's real logger (`_replay_logs`). The result:
+`log.html` shows logs grouped cleanly by item, even though the work happened
+concurrently.
+
+**Encapsulation.** Callers only ever see `Run Parallel Scenarios` — the
+threading, buffering, and replay logic stay out of your `.robot` files.
+
+## Summary of Benefits
+
+- **Speed.** Validating 100 APIs that take 1s each takes roughly 10s (with 10
+  workers) instead of 100s.
+- **Integrity.** Your `log.html` remains the single source of truth — no
+  broken XML tags from concurrent writes.
+- **Flexibility.** Pass `repeat=10` to stress-test a single endpoint, or
+  `for_loop_iterable=${items}` for batch validation of a whole list.
+- **Ergonomics.** Results come back in call order (not completion order), so
+  `${results}[0]` is always the first call. Add `return_values_only=True` to
+  skip the status/logs envelope entirely and unpack each call's return value
+  straight into its own variable — e.g. `${id1}    ${id2}    ${id3}=    Run Parallel Scenarios    ...    repeat=3    return_values_only=True`
+  when seeding N independent fixture rows.
+
+## How Is This Different From pabot?
+
+[pabot](https://github.com/mkorpela/pabot) is the standard tool for parallel
+execution in the Robot Framework ecosystem, and this project is not a
+replacement for it — the two solve different problems and compose well
+together.
+
+| | **pabot** | **ParallelRunner** |
+|---|---|---|
+| Parallelizes at the level of | Suites / test cases | A loop (or repeated call) **inside one test case** |
+| Execution model | Separate **processes** | **Threads** in the same process |
+| Result merging | Runs each suite separately, then merges multiple `output.xml` files with `rebot` | Nothing to merge — logs are buffered per item and replayed into the *same* `log.html` in order |
+| Best suited for | Running many independent suites/tests concurrently, across cores or machines | Fanning out inside a single test case (e.g. one test that validates 100 endpoints) |
+| Workload type | Any (process isolation means CPU-bound work scales too) | I/O-bound work (HTTP calls, DB/network waits) — Python's GIL limits benefit for CPU-bound work |
+
+Concretely:
+
+- **pabot** takes your existing suites/tests, runs several of them at once as
+  separate OS processes (so they don't share memory or a GIL), and then stitches
+  the independent `output.xml` results back into one report. It answers: "I
+  have many independent tests, how do I run them all faster?"
+- **ParallelRunner** answers a different question: "I have *one* test case
+  that needs to do the same kind of work many times (loop over a list of IDs,
+  or repeat something N times) — how do I parallelize the body of that loop
+  without corrupting the log or needing to merge anything?" It uses a
+  `ThreadPoolExecutor` inside a single process, and produces one
+  already-merged, already-ordered log for that test case.
+- Because ParallelRunner uses **threads**, not processes, it shares memory and
+  is subject to the GIL — it is a good fit for **I/O-bound** work (network
+  calls, waiting on APIs/databases) where threads spend most of their time
+  blocked on I/O, not a good fit for CPU-bound number crunching.
+- The two are **complementary**: you can use pabot to run many suites in
+  parallel across processes, where individual test cases *within* those suites
+  use ParallelRunner to parallelize their own inner loops across threads.
+
+If you need to speed up "run these 50 independent test files faster," reach
+for pabot. If you need to speed up "this one test case loops over 100 items
+and I want a single readable log instead of 100 sequential HTTP round trips
+(or 100 merged `output.xml` files)," that's what ParallelRunner is for.
+
+## When Not To Use This
+
+- **CPU-bound work.** Threads share Python's GIL — number crunching won't
+  get faster this way. Use `multiprocessing`, or pabot (separate processes),
+  instead.
+- **Your keyword mutates shared state without synchronization.** Logging is
+  made thread-safe for you; your own keyword's side effects are not. If it
+  writes to a shared variable, file, or object without a lock, running it
+  concurrently can race the same way any multi-threaded code can.
+- **You need per-item retries or a timeout.** Not implemented yet (see
+  [ROADMAP.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/ROADMAP.md)) — one hung call currently blocks the whole batch
+  from returning.
+- **You need process-level isolation** (a crash in one call shouldn't be
+  able to affect another) or cross-machine parallelism — that's pabot's
+  domain, not this library's.
+
+## Project Structure
+
+```
+ParallelRunner/
+├── src/ParallelRunner/     # The installable library (core, do not depend on internals prefixed with `_`)
+├── examples/               # Example "business logic" libraries used by the test suites
+├── atest/            # Robot Framework acceptance suites
+├── docs/                   # INSTALLATION, QUICKSTART, API_REFERENCE
+└── ARCHITECTURE.md         # Technical deep dive
+```
+
+See [ARCHITECTURE.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/ARCHITECTURE.md) for the full breakdown and design
+principles.
+
+### Optional: UI automation with Playwright
+
+The same thread-pool approach applies to browser automation, not just HTTP
+calls — see [examples/playwright_ui/](https://github.com/cristiangarciavd/robotframework-parallelrunner/tree/main/examples/playwright_ui/) for a
+worked example using Playwright's official `sync_api`. It's kept out of
+the default install and CI (heavy dependency, real browser download), so
+it's opt-in: read that folder's README before installing anything.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/CODE_OF_CONDUCT.md).
+For what's done and what's planned, see [ROADMAP.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/ROADMAP.md) and
+[CHANGELOG.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/CHANGELOG.md).
+
+## License
+
+MIT — see [LICENSE](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/LICENSE).
+

robotframework_parallelrunner-0.2.0/README.md

@@ -0,0 +1,179 @@
+# ParallelRunner
+
+[![PyPI](https://img.shields.io/pypi/v/robotframework-parallelrunner)](https://pypi.org/project/robotframework-parallelrunner/)
+[![Python versions](https://img.shields.io/pypi/pyversions/robotframework-parallelrunner)](https://pypi.org/project/robotframework-parallelrunner/)
+[![Tests](https://github.com/cristiangarciavd/robotframework-parallelrunner/actions/workflows/tests.yml/badge.svg)](https://github.com/cristiangarciavd/robotframework-parallelrunner/actions/workflows/tests.yml)
+
+**Run a loop inside a single Robot Framework test case in parallel — with one clean `log.html`, not a merge of many.**
+
+ParallelRunner is a small Robot Framework library that lets you fan a
+keyword out across a thread pool from *within* a test case — e.g. hit 100
+API endpoints, or repeat one check N times — and get back a single,
+correctly ordered `log.html` plus a structured list of per-item results.
+
+**Keyword documentation:** <https://cristiangarciavd.github.io/robotframework-parallelrunner/ParallelRunner.html>
+
+## Installation
+
+```bash
+pip install robotframework-parallelrunner
+```
+
+Requires Python 3.9+ and Robot Framework 5.0+ (installed automatically).
+See [docs/INSTALLATION.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/docs/INSTALLATION.md) for development installs
+and upgrading from the pre-release import path.
+
+## Quickstart
+
+The keyword you want to parallelize is a method of a Python library. It
+receives the current item first, and an injected `_logger` it should log
+through (so logs from different threads never interleave):
+
+```python
+# my_library.py
+class MyLibrary:
+    def verify_agent_data(self, agent_id, _logger=None, **kwargs):
+        _logger(f"Checking agent {agent_id}")
+        ...
+        return result
+```
+
+```robot
+*** Settings ***
+Library    ParallelRunner
+Library    my_library.MyLibrary
+
+*** Test Cases ***
+Verify Agents In Parallel
+    ${agents}=    Create List    1    2    3    4    5
+    ${results}=    Run Parallel Scenarios
+    ...    keyword=Verify Agent Data
+    ...    library=my_library.MyLibrary
+    ...    for_loop_iterable=${agents}
+```
+
+```bash
+robot --pythonpath . my_suite.robot
+```
+
+See [docs/QUICKSTART.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/docs/QUICKSTART.md) for a full walkthrough and
+[docs/API_REFERENCE.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/docs/API_REFERENCE.md) for every parameter of
+`Run Parallel Scenarios`. For the internal design (log buffering, thread
+safety), see [ARCHITECTURE.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/ARCHITECTURE.md).
+
+## Why This Works
+
+**Thread safety.** We avoid `BuiltIn().run_keyword()` inside threads, which is
+the main cause of crashes in multi-threaded Robot Framework. We call the
+underlying Python methods directly instead.
+
+**No log interleaving.** Each worker thread buffers its own log messages in
+memory. Once every task finishes, the main thread replays all buffered logs
+sequentially into Robot Framework's real logger (`_replay_logs`). The result:
+`log.html` shows logs grouped cleanly by item, even though the work happened
+concurrently.
+
+**Encapsulation.** Callers only ever see `Run Parallel Scenarios` — the
+threading, buffering, and replay logic stay out of your `.robot` files.
+
+## Summary of Benefits
+
+- **Speed.** Validating 100 APIs that take 1s each takes roughly 10s (with 10
+  workers) instead of 100s.
+- **Integrity.** Your `log.html` remains the single source of truth — no
+  broken XML tags from concurrent writes.
+- **Flexibility.** Pass `repeat=10` to stress-test a single endpoint, or
+  `for_loop_iterable=${items}` for batch validation of a whole list.
+- **Ergonomics.** Results come back in call order (not completion order), so
+  `${results}[0]` is always the first call. Add `return_values_only=True` to
+  skip the status/logs envelope entirely and unpack each call's return value
+  straight into its own variable — e.g. `${id1}    ${id2}    ${id3}=    Run Parallel Scenarios    ...    repeat=3    return_values_only=True`
+  when seeding N independent fixture rows.
+
+## How Is This Different From pabot?
+
+[pabot](https://github.com/mkorpela/pabot) is the standard tool for parallel
+execution in the Robot Framework ecosystem, and this project is not a
+replacement for it — the two solve different problems and compose well
+together.
+
+| | **pabot** | **ParallelRunner** |
+|---|---|---|
+| Parallelizes at the level of | Suites / test cases | A loop (or repeated call) **inside one test case** |
+| Execution model | Separate **processes** | **Threads** in the same process |
+| Result merging | Runs each suite separately, then merges multiple `output.xml` files with `rebot` | Nothing to merge — logs are buffered per item and replayed into the *same* `log.html` in order |
+| Best suited for | Running many independent suites/tests concurrently, across cores or machines | Fanning out inside a single test case (e.g. one test that validates 100 endpoints) |
+| Workload type | Any (process isolation means CPU-bound work scales too) | I/O-bound work (HTTP calls, DB/network waits) — Python's GIL limits benefit for CPU-bound work |
+
+Concretely:
+
+- **pabot** takes your existing suites/tests, runs several of them at once as
+  separate OS processes (so they don't share memory or a GIL), and then stitches
+  the independent `output.xml` results back into one report. It answers: "I
+  have many independent tests, how do I run them all faster?"
+- **ParallelRunner** answers a different question: "I have *one* test case
+  that needs to do the same kind of work many times (loop over a list of IDs,
+  or repeat something N times) — how do I parallelize the body of that loop
+  without corrupting the log or needing to merge anything?" It uses a
+  `ThreadPoolExecutor` inside a single process, and produces one
+  already-merged, already-ordered log for that test case.
+- Because ParallelRunner uses **threads**, not processes, it shares memory and
+  is subject to the GIL — it is a good fit for **I/O-bound** work (network
+  calls, waiting on APIs/databases) where threads spend most of their time
+  blocked on I/O, not a good fit for CPU-bound number crunching.
+- The two are **complementary**: you can use pabot to run many suites in
+  parallel across processes, where individual test cases *within* those suites
+  use ParallelRunner to parallelize their own inner loops across threads.
+
+If you need to speed up "run these 50 independent test files faster," reach
+for pabot. If you need to speed up "this one test case loops over 100 items
+and I want a single readable log instead of 100 sequential HTTP round trips
+(or 100 merged `output.xml` files)," that's what ParallelRunner is for.
+
+## When Not To Use This
+
+- **CPU-bound work.** Threads share Python's GIL — number crunching won't
+  get faster this way. Use `multiprocessing`, or pabot (separate processes),
+  instead.
+- **Your keyword mutates shared state without synchronization.** Logging is
+  made thread-safe for you; your own keyword's side effects are not. If it
+  writes to a shared variable, file, or object without a lock, running it
+  concurrently can race the same way any multi-threaded code can.
+- **You need per-item retries or a timeout.** Not implemented yet (see
+  [ROADMAP.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/ROADMAP.md)) — one hung call currently blocks the whole batch
+  from returning.
+- **You need process-level isolation** (a crash in one call shouldn't be
+  able to affect another) or cross-machine parallelism — that's pabot's
+  domain, not this library's.
+
+## Project Structure
+
+```
+ParallelRunner/
+├── src/ParallelRunner/     # The installable library (core, do not depend on internals prefixed with `_`)
+├── examples/               # Example "business logic" libraries used by the test suites
+├── atest/            # Robot Framework acceptance suites
+├── docs/                   # INSTALLATION, QUICKSTART, API_REFERENCE
+└── ARCHITECTURE.md         # Technical deep dive
+```
+
+See [ARCHITECTURE.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/ARCHITECTURE.md) for the full breakdown and design
+principles.
+
+### Optional: UI automation with Playwright
+
+The same thread-pool approach applies to browser automation, not just HTTP
+calls — see [examples/playwright_ui/](https://github.com/cristiangarciavd/robotframework-parallelrunner/tree/main/examples/playwright_ui/) for a
+worked example using Playwright's official `sync_api`. It's kept out of
+the default install and CI (heavy dependency, real browser download), so
+it's opt-in: read that folder's README before installing anything.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/CODE_OF_CONDUCT.md).
+For what's done and what's planned, see [ROADMAP.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/ROADMAP.md) and
+[CHANGELOG.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/CHANGELOG.md).
+
+## License
+
+MIT — see [LICENSE](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/LICENSE).

robotframework_parallelrunner-0.2.0/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[project]
+name = "robotframework-parallelrunner"
+# Single source of truth for the version: bump with `poetry version patch|minor|major`.
+# ParallelRunner.__version__ / ROBOT_LIBRARY_VERSION read it back from the installed metadata.
+version = "0.2.0"
+description = "Run a keyword in parallel inside a single Robot Framework test case, with one clean, ordered log.html."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [
+    { name = "Cristian Garcia", email = "cristian.garcia.vd@gmail.com" },
+]
+keywords = [
+    "robotframework",
+    "robot-framework",
+    "parallel",
+    "threading",
+    "testing",
+    "automation",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: Robot Framework",
+    "Framework :: Robot Framework :: Library",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "robotframework>=5.0",
+]
+
+[project.optional-dependencies]
+# Optional, opt-in only: powers examples/playwright_ui/, not part of CI.
+# See examples/playwright_ui/README.md - also run `playwright install chromium` after installing.
+playwright-example = [
+    "playwright>=1.40",
+]
+
+[project.urls]
+Homepage = "https://github.com/cristiangarciavd/robotframework-parallelrunner"
+Documentation = "https://cristiangarciavd.github.io/robotframework-parallelrunner/ParallelRunner.html"
+Repository = "https://github.com/cristiangarciavd/robotframework-parallelrunner"
+Issues = "https://github.com/cristiangarciavd/robotframework-parallelrunner/issues"
+Changelog = "https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/CHANGELOG.md"
+
+[tool.poetry]
+# Distribution name (pip install robotframework-parallelrunner) differs from
+# the import name (Library    ParallelRunner), so the packages are listed explicitly.
+# `parallelrunner` is a deprecated single-file shim for the old import path.
+packages = [
+    { include = "ParallelRunner", from = "src" },
+    { include = "parallelrunner.py", from = "src" },
+]
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=7.0"
+coverage = ">=7.0"
+invoke = ">=2.0"
+# Used by the example libraries the acceptance tests run against (examples/).
+requests = ">=2.25"
+
+[tool.pytest.ini_options]
+testpaths = ["utest"]
+pythonpath = ["src", "."]

robotframework_parallelrunner-0.2.0/src/ParallelRunner/__init__.py

@@ -0,0 +1,19 @@
+"""
+ParallelRunner - Thread-based parallel execution for Robot Framework test cases.
+
+Lets a single test case fan out a keyword (or Python method) across a thread
+pool while keeping log.html clean via a buffer-and-replay mechanism.
+
+Typical usage in a Robot Framework suite::
+
+    *** Settings ***
+    Library    ParallelRunner
+
+Keyword documentation:
+https://cristiangarciavd.github.io/robotframework-parallelrunner/ParallelRunner.html
+"""
+
+from .parallel_library import ParallelLibrary, ParallelRunner, ParallelTaskError
+from .version import __version__
+
+__all__ = ["ParallelRunner", "ParallelLibrary", "ParallelTaskError", "__version__"]

robotframework_parallelrunner-0.2.0/src/ParallelRunner/parallel_library.py

@@ -0,0 +1,327 @@
+import os
+import concurrent.futures
+from typing import Iterable, Any, List, Dict, Optional, Tuple, Union
+from robot.api import logger
+from robot.libraries.BuiltIn import BuiltIn
+
+from .version import __version__
+
+
+class ParallelTaskError(RuntimeError):
+    """
+    Raised when at least one parallel task failed and there is no meaningful
+    return value to hand back for it - by ``get_result_values``, and by
+    ``run_parallel_scenarios`` when called with ``return_values_only=True``.
+
+    Silently substituting `None` for a failed task's value would let a test
+    keep going with bad data instead of failing for the right reason, so
+    this is raised instead.
+
+    Attributes:
+        failures: the subset of result dicts with ``status == "FAIL"``,
+            in the same order they appear in the full result list.
+    """
+
+    def __init__(self, failures: List[Dict[str, Any]], total: int):
+        self.failures = failures
+        detail = "; ".join(f"item={entry['item']!r}: {entry['error']}" for entry in failures)
+        super().__init__(f"{len(failures)} of {total} parallel task(s) failed: {detail}")
+
+
+class ParallelRunner:
+    """
+    ParallelRunner runs a keyword many times *inside a single test case*,
+    concurrently on a thread pool, and still produces one clean, ordered
+    ``log.html``.
+
+    Typical uses: validate 100 API endpoints in one test, or repeat one
+    call N times (seed N fixture rows, a light concurrent load check) -
+    I/O-bound work where most of the time is spent waiting on the network
+    or a database.
+
+    = Table of contents =
+
+    %TOC%
+
+    = How it works =
+
+    - Each call runs on a worker thread of a ``ThreadPoolExecutor``.
+      ``BuiltIn().run_keyword`` is *not* used inside threads (it is not
+      thread-safe); the underlying Python method of the target library is
+      called directly instead.
+    - Every thread buffers its log messages in memory. When all tasks have
+      finished, the logs are replayed sequentially into the real Robot
+      Framework logger, grouped per item and in call order - so concurrent
+      work never interleaves or corrupts ``log.html``.
+    - Results come back in *call order*, not completion order: entry ``i``
+      always belongs to the ``i``-th item / repetition.
+
+    = Writing a parallel-ready keyword =
+
+    The target keyword must be a method of a Python library that is already
+    imported in the suite. It receives the current item (or the repeat
+    index) as its first argument and an injected ``_logger`` callable that
+    it should use instead of ``robot.api.logger``:
+
+    | from robot.api import logger
+    |
+    | class MyLibrary:
+    |     def verify_agent(self, agent_id, _logger=None, **kwargs):
+    |         log = _logger or (lambda msg, level="INFO": logger.write(msg, level))
+    |         log(f"Checking agent {agent_id}")
+    |         ...
+    |         return result
+
+    ``_logger(msg, level)`` accepts the levels ``INFO``, ``WARN``, ``ERROR``
+    and ``IGNORE`` (dropped). Any extra named argument given to
+    `Run Parallel Scenarios` is forwarded to every call as ``**kwargs``.
+
+    Logging is made thread-safe for you; your keyword's own side effects are
+    not. Protect shared state (files, shared objects) with a lock.
+
+    = Result format =
+
+    `Run Parallel Scenarios` returns a list with one dictionary per call:
+
+    | =Key=    | =Description= |
+    | status   | ``PASS`` or ``FAIL``. |
+    | item     | The item (or repeat index) the call received. |
+    | logs     | List of ``(level, message)`` tuples captured during the call. |
+    | result   | The return value of the call (only when ``status`` is ``PASS``). |
+    | error    | The error message (only when ``status`` is ``FAIL``). |
+
+    A failing call does *not* fail the keyword; check ``status`` yourself,
+    or use ``return_values_only=True`` / `Get Result Values`, which fail
+    if any call failed.
+
+    = Environment variables =
+
+    | =Variable=             | =Description= |
+    | ROBOT_THREAD_WORKERS   | Number of worker threads. Read when the library is imported. Default ``4``. |
+    | ROBOT_LOGGER_MAPPER    | Default ``logger_mapper`` as a ``module.function`` path, used when the argument is not given. |
+
+    = When not to use it =
+
+    - CPU-bound work: threads share Python's GIL. Use
+      [https://github.com/mkorpela/pabot|pabot] or ``multiprocessing``.
+    - Running many independent suites/tests faster: that is what pabot is
+      for. Both tools compose well together.
+    """
+    ROBOT_LIBRARY_SCOPE = 'GLOBAL'
+    ROBOT_LIBRARY_VERSION = __version__
+    ROBOT_LIBRARY_DOC_FORMAT = 'ROBOT'
+
+    def __init__(self):
+        # Workers count from Env Var or default to 4
+        self.max_workers = int(os.getenv("ROBOT_THREAD_WORKERS", "4"))
+
+    def run_parallel_scenarios(
+        self,
+        keyword: str,
+        library: str,
+        for_loop_iterable: Optional[Iterable[Any]] = None,
+        repeat: Optional[int] = None,
+        remove_passing_logs: bool = False,
+        thread_log_level: str = "INFO",
+        logger_mapper: Optional[Any] = None,
+        return_values_only: bool = False,
+        **kwargs
+    ) -> Union[List[Dict[str, Any]], Tuple[Any, ...]]:
+        """Runs ``keyword`` from ``library`` concurrently, once per item or N times.
+
+        Arguments:
+        - ``keyword``: Name of the keyword to run, e.g. ``Verify Agent Data``.
+          It must be implemented as a Python method of ``library`` (see
+          `Writing a parallel-ready keyword`).
+        - ``library``: Name of the library that owns the keyword, exactly as
+          it was imported in the suite (e.g. ``my_package.MyLibrary``).
+        - ``for_loop_iterable``: Items to iterate over, like a parallel FOR
+          loop. Each call receives one item as its first argument. Takes
+          precedence over ``repeat``.
+        - ``repeat``: Run the keyword this many times; each call receives its
+          repeat index (``0`` .. ``N-1``). ``repeat=0`` runs it zero times.
+          If neither ``for_loop_iterable`` nor ``repeat`` is given, the
+          keyword runs once.
+        - ``remove_passing_logs``: If true, logs of passing calls are not
+          replayed into ``log.html``; only failed calls are shown.
+        - ``thread_log_level``: Minimum level replayed from the threads:
+          ``INFO`` (default), ``WARN`` or ``ERROR``.
+        - ``logger_mapper``: Optional callable ``mapper(msg, level)`` - or a
+          ``module.function`` path to one - injected as ``_logger`` instead of
+          the default buffering logger, to route logs to a custom logging
+          system. Falls back to the ``ROBOT_LOGGER_MAPPER`` environment
+          variable.
+        - ``return_values_only``: If true, return a plain tuple of each call's
+          return value (in call order) instead of the result dictionaries.
+          Fails with ``ParallelTaskError`` if any call failed. Same as calling
+          `Get Result Values` on the default return value.
+        - ``**kwargs``: Any other named argument is passed to every call.
+
+        Returns a list of result dictionaries (see `Result format`), in call
+        order: entry ``i`` belongs to ``for_loop_iterable[i]`` / repeat
+        index ``i``, regardless of which thread finished first.
+
+        Examples:
+        | ${agents}=    | Create List            | 1                         | 2                       | 3 |
+        | ${results}=   | Run Parallel Scenarios | keyword=Verify Agent Data | library=MyLibrary       | for_loop_iterable=${agents} |
+        | ${results}=   | Run Parallel Scenarios | keyword=Check Health      | library=MyLibrary       | repeat=8 | agent_id=1 |
+        | ${id1}    ${id2}    ${id3}= | Run Parallel Scenarios | keyword=Seed Record | library=MyLibrary | repeat=3 | return_values_only=True |
+        """
+        # Determine items to process. NOTE: `repeat or 1` would be wrong here -
+        # 0 is falsy in Python, so an explicit repeat=0 would silently fall
+        # back to running once instead of zero times. Only a missing (None)
+        # repeat should default to 1.
+        if for_loop_iterable is not None:
+            items = for_loop_iterable
+        else:
+            items = range(1 if repeat is None else repeat)
+
+        # Resolve mapper: it might be a callable or a string path
+        effective_mapper = self._resolve_mapper(logger_mapper)
+
+        # If not resolved from parameter, try environment
+        if effective_mapper is None:
+            effective_mapper = self._load_mapper_from_environment()
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=self.max_workers) as executor:
+            # We map the execution.
+            # Note: We must call the underlying Python method, not BuiltIn().run_keyword
+            # because run_keyword is not thread-safe.
+            lib_instance = self._get_library_instance_owning_keyword(keyword, library)
+            method = getattr(lib_instance, keyword.replace(" ", "_").lower())
+
+            # Submit every task up front so they all start running concurrently,
+            # then collect results in submission order (NOT as_completed order) -
+            # tasks[i].result() blocks only until the i-th task finishes, it
+            # doesn't force tasks to run one at a time.
+            tasks = [
+                executor.submit(self._execute_and_capture, method, item, effective_mapper, **kwargs)
+                for item in items
+            ]
+            results = [task.result() for task in tasks]
+
+        # Step: Re-play logs into Robot Framework sequentially
+        self._replay_logs(results, remove_passing_logs, thread_log_level)
+
+        if return_values_only:
+            return self.get_result_values(results)
+        return results
+
+    def get_result_values(self, results: List[Dict[str, Any]]) -> Tuple[Any, ...]:
+        """Returns the return value of every call in ``results``, as a tuple in call order.
+
+        ``results`` is the list returned by `Run Parallel Scenarios`.
+        ``results[i]`` becomes tuple index ``i``.
+
+        Passing ``return_values_only=True`` to `Run Parallel Scenarios` does
+        the same in one step; use this keyword when you want to inspect the
+        full results first (e.g. assert on ``status`` or ``logs``).
+
+        Fails with ``ParallelTaskError`` if any entry has status ``FAIL`` -
+        a failed call has no return value to put in its slot.
+
+        Example:
+        | ${results}=                 | Run Parallel Scenarios | keyword=Seed Record | library=MyLibrary | repeat=3 |
+        | ${id1}    ${id2}    ${id3}= | Get Result Values      | ${results}          |
+        """
+        failures = [entry for entry in results if entry.get("status") == "FAIL"]
+        if failures:
+            raise ParallelTaskError(failures, len(results))
+        return tuple(entry["result"] for entry in results)
+
+    def _resolve_mapper(self, mapper: Optional[Any]) -> Optional[Any]:
+        """
+        Resolve a mapper which might be a callable or a string path to a module function.
+        
+        Args:
+            mapper: Callable or string path (e.g., "examples.custom_logger.custom_logging_mapper.custom_logger_adapter")
+        
+        Returns:
+            Callable: The mapper function if successfully resolved, None otherwise.
+        """
+        if mapper is None:
+            return None
+        
+        # If already callable, return it
+        if callable(mapper):
+            return mapper
+        
+        # If it's a string, try to import it
+        if isinstance(mapper, str):
+            try:
+                parts = mapper.rsplit(".", 1)
+                if len(parts) == 2:
+                    module_name, func_name = parts
+                    module = __import__(module_name, fromlist=[func_name])
+                    resolved = getattr(module, func_name, None)
+                    if callable(resolved):
+                        return resolved
+            except (ImportError, AttributeError):
+                pass
+        
+        return None
+
+    def _load_mapper_from_environment(self) -> Optional[Any]:
+        """
+        Load custom logger mapper from ROBOT_LOGGER_MAPPER environment variable.
+        Supports both registered mapper names and module.function paths.
+        
+        Returns:
+            Callable: The mapper function if found, None otherwise.
+        """
+        mapper_name = os.getenv("ROBOT_LOGGER_MAPPER")
+        if not mapper_name:
+            return None
+        
+        # Use _resolve_mapper to handle the string path
+        return self._resolve_mapper(mapper_name)
+
+    def _get_library_instance_owning_keyword(self, keyword_name: str, library: str) -> Any:
+        method_name = keyword_name.replace(" ", "_").lower()
+        lib_instance = BuiltIn().get_library_instance(library)
+        if hasattr(lib_instance, method_name):
+            return lib_instance
+        raise ValueError(f"Keyword '{keyword_name}' not found in library '{library}'")
+
+    def _execute_and_capture(self, method, item, logger_mapper: Optional[Any] = None, **kwargs) -> Dict[str, Any]:
+        """Worker wrapper to capture logs and results."""
+        log_buffer = []
+        
+        # Injection of a custom logger into the thread
+        def thread_log(msg, level="INFO"):
+            # Filter out IGNORE (sv=0) level logs
+            if level != "IGNORE":
+                log_buffer.append((level, msg))
+        
+        # Use mapper if provided, otherwise use thread_log
+        effective_logger = logger_mapper if logger_mapper else thread_log
+
+        try:
+            # We pass the custom logger as an extra kwarg if the method supports it
+            # or rely on the method returning its own logs.
+            result = method(item, _logger=effective_logger, **kwargs)
+            return {"status": "PASS", "item": item, "logs": log_buffer, "result": result}
+        except Exception as e:
+            thread_log(f"Thread failed for item {item}: {str(e)}", "ERROR")
+            return {"status": "FAIL", "item": item, "logs": log_buffer, "error": str(e)}
+
+    def _replay_logs(self, results: List[Dict[str, Any]], remove_passing_logs: bool = False, thread_log_level: str = "INFO"):
+        """Sequential dump to the real RF Logger. Filters out IGNORE level logs."""
+        level_order = {"INFO": 1, "WARN": 2, "ERROR": 3}
+        min_level = level_order.get(thread_log_level, 1)
+        for entry in results:
+            if remove_passing_logs and entry['status'] == 'PASS':
+                continue
+            logger.info(f"--- Logs for Item: {entry['item']} ---")
+            for level, msg in entry['logs']:
+                # Skip IGNORE level and logs below minimum level
+                if level == "IGNORE" or level_order.get(level, 1) < min_level:
+                    continue
+                if level == "INFO": logger.info(msg)
+                elif level == "WARN": logger.warn(msg)
+                elif level == "ERROR": logger.error(msg)
+            logger.info(f"Status: {entry['status']}")
+
+# Backwards-compatible name: the class was called ParallelLibrary before the
+# package was renamed to ParallelRunner (imported as `Library    ParallelRunner`).
+ParallelLibrary = ParallelRunner

robotframework_parallelrunner-0.2.0/src/ParallelRunner/version.py

@@ -0,0 +1,16 @@
+"""Single source of truth for the library version.
+
+The version lives only in ``pyproject.toml`` (bump it with ``poetry version
+patch|minor|major``). At runtime it is read back from the installed
+distribution's metadata, so ``__version__`` / ``ROBOT_LIBRARY_VERSION`` can
+never drift from what was published to PyPI.
+"""
+
+from importlib.metadata import PackageNotFoundError, version as _dist_version
+
+DISTRIBUTION_NAME = "robotframework-parallelrunner"
+
+try:
+    __version__ = _dist_version(DISTRIBUTION_NAME)
+except PackageNotFoundError:  # running from a source checkout that was never installed
+    __version__ = "0.0.0+unknown"

robotframework_parallelrunner-0.2.0/src/parallelrunner.py

@@ -0,0 +1,34 @@
+"""
+Deprecated compatibility shim for the pre-0.2.0 import paths.
+
+Old style (still works, emits a DeprecationWarning)::
+
+    Library    parallelrunner.parallel_library.ParallelLibrary
+
+New style::
+
+    Library    ParallelRunner
+
+Why a single-file module instead of a ``parallelrunner/`` package: Windows and
+macOS filesystems are case-insensitive by default, so a ``parallelrunner/``
+directory cannot live next to ``ParallelRunner/``. Registering the submodule
+in ``sys.modules`` makes ``parallelrunner.parallel_library`` importable anyway.
+"""
+
+import sys
+import warnings
+
+from ParallelRunner import ParallelLibrary, ParallelRunner, ParallelTaskError, __version__
+from ParallelRunner import parallel_library
+
+warnings.warn(
+    "Importing 'parallelrunner' is deprecated and will be removed in a future "
+    "release; use 'Library    ParallelRunner' (or 'from ParallelRunner import "
+    "ParallelRunner') instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+sys.modules[__name__ + ".parallel_library"] = parallel_library
+
+__all__ = ["ParallelRunner", "ParallelLibrary", "ParallelTaskError", "__version__", "parallel_library"]