From 2dcf4ba22052f0fb6554fd84361ccacf9d62b736 Mon Sep 17 00:00:00 2001 From: Kostiantyn Goloveshko Date: Sun, 8 Sep 2024 00:37:00 +0300 Subject: [PATCH] Document comparison between pytest-bdd and pytest-bdd-ng --- DOCUMENTATION.rst | 20 +++++++++++++++++++ README.rst | 49 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 69 insertions(+) diff --git a/DOCUMENTATION.rst b/DOCUMENTATION.rst index 12e68a5d..d3eb15f7 100644 --- a/DOCUMENTATION.rst +++ b/DOCUMENTATION.rst @@ -1,6 +1,8 @@ Scenario decorator ------------------ +.. _pytest-bdd: https://github.com/pytest-dev/pytest-bdd + Feature files auto-collection could be disabled by use `--disable-feature-autoload` cli option or `disable_feature_autoload` `pytest.ini` option. In this case there mechanism to use features from `test_*.py` pytest files: functions decorated with the `scenario` decorator behave like a normal test function, @@ -33,6 +35,9 @@ And even more, there are several types of step parameter parsers at your disposa **heuristic** (default) Tries to select right parser between string, cucumber_expression, cfparse and re. Any object that supports `__str__` interface and does not support parser interface will be wrapped with this parser + +.. NOTE:: Important difference from pytest-bdd_ + **parse** (based on: pypi_parse_) Provides a simple parser that replaces regular expressions for step parameters with a readable syntax like ``{param:Type}``. @@ -266,6 +271,9 @@ This behavior is same to: def step(foo, bar, fizz, buzz): ... + +.. NOTE:: Important difference from pytest-bdd_ + But this behavior could be changed; For example you want to rename some parameters and left other as-is. `Ellipsis `_ instance means all present attributes, but not listed directly. @@ -387,6 +395,8 @@ Also it's possible to override multiple fixtures in one step using `target_fixtu Loading whole feature files --------------------------- +.. NOTE:: Important difference from pytest-bdd_ + If you have relatively large set of feature files, it's boring to manually bind scenarios to the tests using the scenario decorator(in case if you don't want use feature auto-load). Of course with the manual approach you get all the power to be able to additionally parametrize the test, give the test function a nice name, document it, etc, @@ -479,6 +489,8 @@ Note that if you use pytest `--strict` option, all bdd tags mentioned in the fea `markers` setting of the `pytest.ini` config. Also for tags please use names which are python-compatible variable names, eg starts with a non-number, underscore alphanumeric, etc. That way you can safely use tags for tests filtering. +.. NOTE:: Important difference from pytest-bdd_ + You can customize how tags are converted to pytest marks by implementing the ``pytest_bdd_convert_tag_to_marks`` hook and returning list of resulting marks from it: @@ -625,6 +637,8 @@ then Feature file paths ------------------ +.. NOTE:: Important difference from pytest-bdd_ + By default, pytest-bdd-ng will use current module's path as base path for finding feature files, but this behaviour can be changed in the pytest configuration file (i.e. `pytest.ini`, `tox.ini` or `setup.cfg`) by declaring the new base path in the `bdd_features_base_dir` key. The path is interpreted as relative to the pytest root directory. @@ -664,12 +678,16 @@ The `features_base_dir` parameter can also be passed to the `@scenario` decorato Localization ------------ +.. NOTE:: Important difference from pytest-bdd_ + pytest-bdd-ng supports all localizations which Gherkin `does `_ Hooks ----- +.. NOTE:: Important difference from pytest-bdd_ + pytest-bdd-ng exposes several `pytest hooks `_ which might be helpful building useful reporting, visualization, etc on top of it: @@ -694,6 +712,8 @@ which might be helpful building useful reporting, visualization, etc on top of i Fixtures -------- +.. NOTE:: Important difference from pytest-bdd_ + pytest-bdd-ng exposes several plugin fixtures to give more testing flexibility * bdd_example - The current scenario outline parametrization. diff --git a/README.rst b/README.rst index 5db9d0cb..a66ff3bc 100644 --- a/README.rst +++ b/README.rst @@ -36,6 +36,55 @@ Why ``NG`` ? The current pytest plugin for cucumber is pytest-bdd_ , a popular project with 1.2k stars and used in 3k public repos and maintained by the pytest community. The upstream open-cucumber project does not have an official python release, so the current cucumber specs include features not available in pytest-bdd_ . This project is an effort to bridge the gap and also make it easier for pytest users to access new cucumber features. +.. list-table:: + :widths: 30 10 10 50 + :header-rows: 1 + + * - Feature + - original + - NG + - Description + * - `Official parser support `_ + - \- + - \+ + - All features of Feature files are supported from the "box" (localisation, Rules, Examples, Data tables, etc.) + * - Steps definitions via `Cucumber expressions `_ + - \- + - \+ + - Easy migration between implementations + * - Reporting using `Messages `_ + - \- + - \+ + - Possible to use all collection of Cucumber community tools for reporting + * - `Pickles `_ internal protocol + - \- + - \+ + - Allows to implement parsers based on other file types/principles + * - Heuristic step matching + - \-/+ + - \+ + - Steps ease of use / amount of needed boilerplate code + * - Step execution context. Step types and variants of definition + - \-/+ + - \+ + - Dispatching steps by kind. Steps injecting multiple fixtures. Default injecting behaviors. Steps could be used on import automatically. It's possible to define default values for step variables. + * - Automatic collection of Feature files + - \- + - \+ + - No boilerplate code / No mix between steps definition and feature files + * - Stability and bugfixes + - \+ + - \+/- + - + * - Supported python/pytest versions + - \+/- + - \+ + - NG supports wider and elder pytest&python version. Tested also for PyPy + * - Active community + - \+ + - \-/+ + - + Install pytest-bdd-ng ---------------------