cucu 1.0.0__py3-none-any.whl

cucu/utils.py

@@ -0,0 +1,269 @@
+"""
+various cucu utilities can be placed here and then exposed publicly through
+the src/cucu/__init__.py
+"""
+
+import logging
+import os
+import pkgutil
+import shutil
+
+import humanize
+from tabulate import DataRow, TableFormat, tabulate
+from tenacity import (
+    before_sleep_log,
+    retry_if_not_exception_type,
+    stop_after_delay,
+    wait_fixed,
+)
+from tenacity import retry as retrying
+
+from cucu import logger
+from cucu.browser.core import Browser
+from cucu.config import CONFIG
+
+GHERKIN_TABLEFORMAT = TableFormat(
+    lineabove=None,
+    linebelowheader=None,
+    linebetweenrows=None,
+    linebelow=None,
+    headerrow=DataRow("|", "|", "|"),
+    datarow=DataRow("|", "|", "|"),
+    padding=1,
+    with_header_hide=["lineabove"],
+)
+
+
+class StopRetryException(Exception):
+    pass
+
+
+def format_gherkin_table(table, headings=[], prefix=""):
+    formatted = tabulate(table, headings, tablefmt=GHERKIN_TABLEFORMAT)
+    if prefix == "":
+        return formatted
+
+    return prefix + formatted.replace("\n", f"\n{prefix}")
+
+
+#
+# code below adapted from:
+# https://github.com/behave/behave/blob/994dbfe30e2a372182ea613333e06f069ab97d4b/behave/runner.py#L385
+# so we can have the sub steps printed in the console logs
+#
+def run_steps(ctx, steps_text):
+    """
+    run sub steps within an existing step definition but also log their output
+    so that its easy to see what is happening.
+    """
+
+    # -- PREPARE: Save original ctx data for current step.
+    # Needed if step definition that called this method uses .table/.text
+    original_table = getattr(ctx, "table", None)
+    original_text = getattr(ctx, "text", None)
+
+    # first time a given step calls substeps we want to move the step_index
+    # so it starts the followings steps the right point.
+    if not ctx.current_step.has_substeps:
+        ctx.step_index += 1
+
+    ctx.current_step.has_substeps = True
+
+    ctx.feature.parser.variant = "steps"
+    steps = ctx.feature.parser.parse_steps(steps_text)
+
+    current_step = ctx.current_step
+    current_step_start_time = ctx.start_time
+
+    # XXX: I want to get back to this and find a slightly better way to handle
+    #      these substeps without mucking around with so much state in behave
+    #      but for now this works correctly and existing tests work as expected.
+    try:
+        with ctx._use_with_behave_mode():
+            for step in steps:
+                for formatter in ctx._runner.formatters:
+                    step.is_substep = True
+                    formatter.insert_step(step, index=ctx.step_index)
+
+                passed = step.run(ctx._runner, quiet=False, capture=False)
+
+                if not passed:
+                    if "StopRetryException" in step.error_message:
+                        raise StopRetryException(step.error_message)
+                    else:
+                        raise RuntimeError(step.error_message)
+
+            # -- FINALLY: Restore original ctx data for current step.
+            ctx.table = original_table
+            ctx.text = original_text
+    finally:
+        ctx.current_step = current_step
+        ctx.start_time = current_step_start_time
+
+    return True
+
+
+def retry(func, wait_up_to_s=None, retry_after_s=None):
+    """
+    utility retry function that can retry the provided `func` for the maximum
+    amount of seconds specified by `wait_up_to_s` and wait the number of seconds
+    specified in `retry_after_s`
+    """
+    if wait_up_to_s is None:
+        wait_up_to_s = float(CONFIG["CUCU_STEP_WAIT_TIMEOUT_S"])
+
+    if retry_after_s is None:
+        retry_after_s = float(CONFIG["CUCU_STEP_RETRY_AFTER_S"])
+
+    @retrying(
+        stop=stop_after_delay(wait_up_to_s),
+        wait=wait_fixed(retry_after_s),
+        retry=retry_if_not_exception_type(StopRetryException),
+        before_sleep=before_sleep_log(logger, logging.DEBUG),
+    )
+    def new_decorator(*args, **kwargs):
+        ctx = CONFIG["__CUCU_CTX"]
+
+        for hook in CONFIG["__CUCU_BEFORE_RETRY_HOOKS"]:
+            hook(ctx)
+
+        return func(*args, **kwargs)
+
+    return new_decorator
+
+
+def load_jquery_lib():
+    """
+    load jquery library
+    """
+    jquery_lib = pkgutil.get_data(
+        "cucu", "external/jquery/jquery-3.5.1.min.js"
+    )
+    return jquery_lib.decode("utf8")
+
+
+def text_in_current_frame(browser: Browser) -> str:
+    """
+    Utility to get all the visible text of the current frame.
+
+    Args:
+        browser (Browser): the browser session switched to the desired frame
+    """
+    script = "return window.jqCucu && jqCucu.fn.jquery;"
+    jquery_version = browser.execute(script)
+    if not jquery_version:
+        browser.execute(load_jquery_lib())
+        browser.execute("window.jqCucu = jQuery.noConflict(true);")
+    text = browser.execute(
+        'return jqCucu("body").children(":visible").text();'
+    )
+    return text
+
+
+def ellipsize_filename(raw_filename):
+    max_filename = 100
+    new_raw_filename = normalize_filename(raw_filename)
+    if len(new_raw_filename) < max_filename:
+        return new_raw_filename
+
+    ellipsis = "..."
+    # save the last chars, as the ending is often important
+    end_count = 40
+    front_count = max_filename - (len(ellipsis) + end_count)
+    ellipsized_filename = (
+        new_raw_filename[:front_count]
+        + ellipsis
+        + new_raw_filename[-1 * end_count :]
+    )
+    return ellipsized_filename
+
+
+def normalize_filename(raw_filename):
+    normalized_filename = (
+        raw_filename.replace('"', "")
+        .replace("{", "")
+        .replace("}", "")
+        .replace("#", "")
+        .replace("&", "")
+    )
+    return normalized_filename
+
+
+def get_step_image_dir(step_index, step_name):
+    """
+    generate .png image file name that meets these criteria:
+     - hides secrets
+     - escaped
+     - filename does not exceed 255 chars (OS limitation)
+     - uniqueness comes from step number
+    """
+    escaped_step_name = CONFIG.hide_secrets(step_name).replace("/", "_")
+    unabridged_dirname = f"{step_index:0>4} - {escaped_step_name}"
+    dirname = ellipsize_filename(unabridged_dirname)
+
+    return dirname
+
+
+def take_saw_element_screenshot(ctx, thing, name, index, element=None):
+    observed = "saw" if element else "did not see"
+    prefix = "" if index == 0 else f"{humanize.ordinal(index)} "
+
+    take_screenshot(
+        ctx,
+        ctx.current_step.name,
+        label=f'{observed} {prefix}{thing} "{name}"',
+        element=element,
+    )
+
+
+def take_screenshot(ctx, step_name, label="", element=None):
+    screenshot_dir = os.path.join(
+        ctx.scenario_dir, get_step_image_dir(ctx.step_index, step_name)
+    )
+    if not os.path.exists(screenshot_dir):
+        os.mkdir(screenshot_dir)
+
+    if len(label) > 0:
+        label = f" - {CONFIG.hide_secrets(label).replace('/', '_')}"
+    filename = f"{CONFIG['__STEP_SCREENSHOT_COUNT']:0>4}{label}.png"
+    filename = ellipsize_filename(filename)
+    filepath = os.path.join(screenshot_dir, filename)
+
+    if CONFIG["CUCU_SKIP_HIGHLIGHT_BORDER"] or not element:
+        ctx.browser.screenshot(filepath)
+    else:
+        location = element.location
+        border_width = 4
+        x, y = location["x"] - border_width, location["y"] - border_width
+        size = element.size
+        width, height = size["width"], size["height"]
+
+        position_css = f"position: absolute; top: {y}px; left: {x}px; width: {width}px; height: {height}px; z-index: 9001;"
+        visual_css = "border-radius: 4px; border: 4px solid #ff00ff1c; background: #ff00ff05; filter: drop-shadow(magenta 0 0 10px);"
+
+        script = f"""
+            (function() {{ // double curly-brace to escape python f-string
+                var body = document.querySelector('body');
+                var cucu_border = document.createElement('div');
+                cucu_border.setAttribute('id', 'cucu_border');
+                cucu_border.setAttribute('style', '{position_css} {visual_css}');
+                body.append(cucu_border);
+            }})();
+        """
+        ctx.browser.execute(script)
+
+        ctx.browser.screenshot(filepath)
+
+        clear_highlight = """
+            (function() {
+                var body = document.querySelector('body');
+                var cucu_border = document.getElementById('cucu_border');
+                body.removeChild(cucu_border);
+            })();
+        """
+        ctx.browser.execute(clear_highlight, element)
+
+    if CONFIG["CUCU_MONITOR_PNG"]:
+        shutil.copyfile(filepath, CONFIG["CUCU_MONITOR_PNG"])
+
+    CONFIG["__STEP_SCREENSHOT_COUNT"] += 1

cucu-1.0.0.dist-info/METADATA

@@ -0,0 +1,424 @@
+Metadata-Version: 2.3
+Name: cucu
+Version: 1.0.0
+Summary: Easy BDD web testing
+Author-email: Domino Data Lab <open-source@dominodatalab.com>
+License: The Clear BSD License
+License-File: LICENSE
+Keywords: behave,cucumber,selenium
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Software Development :: Testing :: BDD
+Requires-Python: >=3.9
+Requires-Dist: beautifulsoup4~=4.12.2
+Requires-Dist: behave~=1.2.6
+Requires-Dist: chromedriver-autoinstaller~=0.6.2
+Requires-Dist: click~=8.1.7
+Requires-Dist: coverage[toml]~=7.4.3
+Requires-Dist: geckodriver-autoinstaller~=0.1.0
+Requires-Dist: humanize~=4.8.0
+Requires-Dist: importlib-metadata~=8.0.0
+Requires-Dist: ipdb~=0.13.13
+Requires-Dist: jellyfish~=1.0.1
+Requires-Dist: jinja2~=3.1.3
+Requires-Dist: lsprotocol~=2023.0.1
+Requires-Dist: mpire~=2.10.2
+Requires-Dist: psutil~=6.0.0
+Requires-Dist: pygls~=1.3.1
+Requires-Dist: pyyaml~=6.0.1
+Requires-Dist: requests~=2.31.0
+Requires-Dist: selenium~=4.15
+Requires-Dist: tabulate~=0.9.0
+Requires-Dist: tenacity~=9.0.0
+Description-Content-Type: text/markdown
+
+# ![Cucu Logo](logo.png) **CUCU** - Easy BDD web testing
+
+End-to-end testing framework that uses [gherkin](https://cucumber.io/docs/gherkin/)
+to drive various underlying tools/frameworks to create real world testing scenarios.
+
+[![CircleCI](https://dl.circleci.com/status-badge/img/gh/dominodatalab/cucu/tree/main.svg?style=svg&circle-token=CCIPRJ_FnyZPtQ9odT5vmGW3CmZNU_bf0cfd776a09729ca4225a2860d9b59c4dae88af)](https://dl.circleci.com/status-badge/redirect/gh/dominodatalab/cucu/tree/main)
+
+## Why cucu?
+1. Cucu avoids unnecessary abstractions (i.e. no Page Objects!) while keeping scenarios readable.
+    ```gherkin
+    Feature: My First Cucu Test
+      We want to be sure the user get search results using the landing page
+
+      Scenario: User can get search results
+        Given I open a browser at the url "https://www.google.com/search"
+         When I wait to write "google" into the input "Search"
+          And I click the button "Google Search"
+         Then I wait to see the text "results"
+    ```
+2. Designed to be run **locally** and in **CI**
+3. Runs a selenium container for you OR you can bring your own browser / container
+4. Does fuzzy matching to approximate actions of a real user
+5. Provides many steps out of the box
+6. Makes it easy to create **customized** steps
+7. Enables hierarchical configuration and env var and **CLI arg overrides**
+8. Comes with a linter that is **customizable**
+
+## Supporting docs
+1. [CHANGELOG.md](CHANGELOG.md) - for latest news
+2. [CONTRIBUTING.md](CONTRIBUTING.md) - how we develop and test the library
+3. [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+4. [CONTRIBUTORS.md](CONTRIBUTORS.md)
+5. [LICENSE](LICENSE)
+
+# Table of Contents
+
+- [ **CUCU** - Easy BDD web testing](#-cucu---easy-bdd-web-testing)
+  - [Why cucu?](#why-cucu)
+  - [Supporting docs](#supporting-docs)
+- [Table of Contents](#table-of-contents)
+- [Installation](#installation)
+  - [Requirements](#requirements)
+  - [Install Walkthrough](#install-walkthrough)
+- [Usage](#usage)
+  - [Cucu Run](#cucu-run)
+  - [Run specific browser version with docker](#run-specific-browser-version-with-docker)
+- [Extending Cucu](#extending-cucu)
+  - [Fuzzy matching](#fuzzy-matching)
+  - [Custom steps](#custom-steps)
+  - [Before / After hooks](#before--after-hooks)
+  - [Custom lint rules](#custom-lint-rules)
+- [More Ways To Install Cucu](#more-ways-to-install-cucu)
+  - [Install From Build](#install-from-build)
+
+# Installation
+## Requirements
+Cucu requires
+1. python 3.9+
+2. docker (to do UI testing)
+
+## Install Walkthrough
+_Get your repo setup using cucu as a test framework_
+
+1. install and start Docker if you haven't already
+2. install [cucu](https://pypi.org/project/cucu/)
+   ```
+   pip install cucu
+   ```
+3. create the folder structure and files with content:
+    _Cucu uses the [behave framework](https://github.com/behave/behave) which expects the `features/steps` directories_
+   - features/
+      - steps/
+      - `__init__.py` # enables cucu and custom steps
+        ```python
+        # import all of the steps from cucu
+        from cucu.steps import *  # noqa: F403, F401
+
+        # import individual sub-modules here (i.e. module names of your custom step py files)
+        # Example: For file features/steps/ui/login.py
+        # import steps.ui.login_steps
+        ```
+   - environment.py - enables before/after hooks
+     ```python
+     # flake8: noqa
+     from cucu.environment import *
+
+     # Define custom before/after hooks here
+     ```
+4. list available cucu steps
+   ```bash
+   cucu steps
+   ```
+   - if you have `brew install fzf` then you can fuzzy find steps
+     ```bash
+     cucu steps | fzf
+     # start typing for search
+     ```
+5. **create your first cucu test**
+   - features/my_first_test.feature
+     ```gherkin
+     Feature: My First Cucu Test
+       We want to be sure the user get search results using the landing page
+
+       Scenario: User can get search results
+         Given I open a browser at the url "https://www.google.com/search"
+          When I wait to write "google" into the input "Search"
+           And I click the button "Google Search"
+          Then I wait to see the text "results"
+     ```
+6. **run it**
+   ```bash
+   cucu run features/my_first_test.feature
+   ```
+
+# Usage
+## Cucu Run
+The command `cucu run` is used to run a given test or set of tests and in its
+simplest form you can use it like so:
+```bash
+cucu run features/my_first_test.feature
+```
+
+That would simply run the "google search for the word google" and once it's
+finished executing you can use the `cucu report` command to generate an easy
+to navigate and read HTML test report which includes the steps and screenshots
+from that previous test run.
+
+*NOTE:*
+By default we'll simply use the `Google Chrome` you have installed and there's
+a python package that'll handle downloading chromedriver that matches your
+specific local Google Chrome version.
+
+## Run specific browser version with docker
+
+[docker hub](https://hub.docker.com/) has easy to use docker containers for
+running specific versions of chrome, edge and firefox browsers for testing that
+you can spin up manually in standalone mode like so:
+
+```bash
+docker run -d -p 4444:4444 selenium/standalone-chrome:latest
+```
+
+If you are using ARM64 CPU architecture (Mac M1 or M2), you must use seleniarm
+container.
+
+```bash
+docker run -d -p 4444:4444 seleniarm/standalone-chromium:latest
+```
+
+And can choose a specific version replacing the `latest` with any tag from
+[here](https://hub.docker.com/r/selenium/standalone-chrome/tags). You can find
+browser tags for `standalone-edge` and `standalone-firefox` the same way. Once
+you run the command you will see with `docker  ps -a` that the container
+is running and listening on port `4444`:
+
+Specific tags for seleniarm:
+[here](https://hub.docker.com/r/seleniarm/standalone-chromium/tags)
+
+```bash
+> docker ps -a
+CONTAINER ID ... PORTS                                                NAMES
+7c719f4bee29 ... 0.0.0.0:4444->4444/tcp, :::4444->4444/tcp, 5900/tcp  wizardly_haslett
+```
+
+*NOTE:* For seleniarm containers, the available browsers are chromium and firefox.
+The reason for this is because Google and Microsoft have not released binaries
+for their respective browsers (Chrome and Edge).
+
+Now when running `cucu run some.feature` you can provide
+`--selenium-remote-url http://localhost:4444` and this way you'll run a very
+specific version of chrome on any setup you run this on.
+
+You can also create a docker hub setup with all 3 browser nodes connected using
+the utilty script at `./bin/start_selenium_hub.sh` and you can point your tests
+at `http://localhost:4444` and then specify the `--browser` to be `chrome`,
+`firefox` or `edge` and use that specific browser for testing.
+
+The docker hub setup for seleniarm: `./bin/start_seleniarm_hub.sh`
+*NOTE:* `edge` cannot be selected as a specific browser for testing
+
+To ease using various custom settings you can also set most of the command line
+options in a local `cucurc.yml` or in a more global place at `~/.cucurc.yml`
+the same settings. For the remote url above you'd simply have the following
+in your `cucurc.yml`:
+
+```bash
+CUCU_SELENIUM_REMOTE_URL: http://localhost:4444
+```
+
+Then you can simply run `cucu run path/to/some.feature` and `cucu` would load
+the local `cucurc.yml` or `~/.cucurc.yml` settings and use those.
+
+# Extending Cucu
+
+## Fuzzy matching
+
+`cucu` uses selenium to interact with the browser but on top of that we've
+developed a fuzzy matching set of rules that allow the framework to find
+elements on the page by having a label and a type of element we're searching for.
+
+The principal is simple you want to `click the button "Foo"` so we know you want
+to find a button which can be one of a few different kind of HTML elements:
+
+  * `<a>`
+  * `<button>`
+  * `<input type="button">`
+  * `<* role="button">`
+  * etc
+
+We also know that it has the name you provided labeling it and that can be
+done using any of the following rules:
+
+  * `<thing>name</thing>`
+  * `<*>name</*><thing></thing>`
+  * `<thing attribute="name"></thing>`
+  * `<*>name</*>...<thing>...`
+
+Where `thing` is any of the previously identified element types. With the above
+rules we created a simple method method that uses the those rules to find a set
+of elements labeled with the name you provide and type of elements you're
+looking for. We currently use [swizzle](https://github.com/jquery/sizzle) as
+the underlying element query language as its highly portable and has a bit
+useful features than basic CSS gives us.
+
+## Custom steps
+It's easy to create custom steps, for example:
+1. create a new python file in your repo `features/steps/ui/weird_button_steps.py`
+    ```python
+    from cucu import fuzzy, retry, step
+
+    # make this step available for scenarios and listed in `cucu steps`
+    @step('I open the wierd menu item "{menu_item}"')
+    def open_jupyter_menu(ctx, menu_item):
+        # using fuzzy.find
+        dropdown_item = fuzzy.find(ctx.browser, menu_item, ["li a"])
+        dropdown_item.click()
+
+    # example using retry
+    def click_that_weird_button(ctx):
+        # using selenium's css_find_elements
+        ctx.browser.css_find_elements("button[custom_thing='painful-id']")[0].click()
+
+    @step("I wait to click this button that isn't aria compliant on my page")
+    def wait_to_click_that_weird_button(ctx):
+        # makes this retry with the default wait timeout
+        retry(click_that_weird_button)(ctx)  # remember to call the returned function `(ctx)` at the end
+    ```
+2. then update the magic `features/steps/__init__.py` file (this one file only!)
+
+   _Yeah I know that this is kind of odd, but work with me here😅_
+    ```python
+    # import all of the steps from cucu
+    from cucu.steps import *  # noqa: F403, F401
+
+    # import individual sub-modules here (i.e. module names of your custom step py files)
+    # Example: For file features/steps/ui/login.py
+    # import steps.ui.login_steps
+    import steps.ui.weird_button_steps
+    ```
+3. profit!
+
+## Before / After hooks
+
+There are several hooks you can access, here's a few:
+```python
+register_before_retry_hook,
+register_before_scenario_hook,
+register_custom_junit_failure_handler,
+register_custom_tags_in_report_handling,
+register_custom_scenario_subheader_in_report_handling,
+register_custom_variable_handling,
+register_page_check_hook,
+```
+
+And here's an example:
+1. add your function def to `features/environment.py`
+   ```python
+    import logging
+
+    from cucu import (
+        fuzzy,
+        logger,
+        register_page_check_hook,
+        retry,
+    )
+    from cucu.config import CONFIG
+    from cucu.environment import *
+
+    def print_elements(elements):
+        """
+        given a list of selenium web elements we print their outerHTML
+        representation to the logs
+        """
+        for element in elements:
+            logger.debug(f"found element: {element.get_attribute('outerHTML')}")
+
+    def wait_for_my_loading_indicators(browser):
+       # aria-label="loading"
+       def should_not_see_aria_label_equals_loading():
+          # ignore the checks on the my-page page as there are these silly
+          # spinners that have aria-label=loading and probably shouldn't
+          if "my-page" not in browser.get_current_url():
+             elements = browser.css_find_elements("[aria-label='loading'")
+             if elements:
+                   print_elements(elements)
+                   raise RuntimeError("aria-label='loading', see above for details")
+
+       retry(should_not_see_aria_label_equals_loading)()
+
+       # my-attr contains "loading"
+       def should_not_see_data_test_contains_loading():
+          elements = browser.css_find_elements("[my-attr*='loading'")
+          if elements:
+             print_elements(elements)
+             raise RuntimeError("my-attr*='loading', see above for details")
+
+       retry(should_not_see_data_test_contains_loading)()
+
+       # class contains "my-spinner"
+       def should_not_see_class_contains_my_spinner():
+          elements = browser.css_find_elements("[class*='my-spinner'")
+          if elements:
+             print_elements(elements)
+             raise RuntimeError("class*='my-spinner', see above for details")
+
+       retry(should_not_see_class_contains_my_spinner)()
+
+
+    register_page_check_hook("my loading indicators", wait_for_my_loading_indicators)
+   ```
+2. done!
+
+## Custom lint rules
+
+You can easily extend the `cucu lint` linting rules by setting the variable
+`CUCU_LINT_RULES_PATH` and pointing it to a directory in your features source
+that has `.yaml` files that are structured like so:
+
+```yaml
+[unique_rule_identifier]:
+  message: [the message to provide the end user explaining the violation]
+  type: [warning|error] # I or W  will be printed when reporting the violation
+  current_line:
+    match: [regex]
+  previous_line:
+    match: [regex]
+  next_line:
+    match: [regex]
+  fix:
+    match: [regex]
+    replace: [regex]
+    -- or --
+    delete: true
+```
+
+The `current_line`, `previous_line` and `next_line` sections are used to match
+on a specific set of lines so that you can then "fix" the current line a way
+specified by the `fix` block. When there is no `fix` block provided then
+`cucu lint` will notify the end user it can not fix the violation.
+
+In the `fix` section one can choose to do `match` and `replace` or to simply
+`delete` the violating line.
+
+# More Ways To Install Cucu
+
+## Install From Build
+
+Within the cucu directory you can run `uv build` and that will produce some
+output like so:
+
+```bash
+Building source distribution...
+Building wheel from source distribution...
+Successfully built dist/cucu-0.207.0.tar.gz and dist/cucu-0.207.0-py3-none-any.whl
+```
+
+At this point you can install the file `dist/cucu-0.1.0.tar.gz` using
+`pip install .../cucu/dist/cucu-*.tar.gz` anywhere you'd like and have the `cucu` tool ready to
+run.