cucu 1.1.1__tar.gz → 1.2.0__tar.gz

{cucu-1.1.1 → cucu-1.2.0}/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project closely adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.2.0
+- Add - levels 2-4 to section step
+- Change - rename comment step to section step
+- Add - linting for section step
+- Change - min python to 3.10
+
+## 1.1.2
+- Add - `cucu init` command to setup new projects
+
 ## 1.1.1
 - Chore - bump coverage lib from 7.6.12 to 7.8.0
 - Chore - change CI to not use experimental COVERAGE_CORE=sysmon

{cucu-1.1.1 → cucu-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cucu
-Version: 1.1.1
+Version: 1.2.0
 Summary: Easy BDD web testing
 Project-URL: Homepage, https://github.com/dominodatalab/cucu/wiki
 Project-URL: Download, https://pypi.org/project/cucu/
@@ -16,24 +16,16 @@ 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: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Testing :: BDD
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Requires-Dist: beautifulsoup4~=4.13.3
-Requires-Dist: behave~=1.2.6
+Requires-Dist: behave==1.2.6
 Requires-Dist: chromedriver-autoinstaller~=0.6.2
-Requires-Dist: click~=8.1.7
+Requires-Dist: click~=8.2.0
 Requires-Dist: coverage[toml]~=7.8
 Requires-Dist: geckodriver-autoinstaller~=0.1.0
 Requires-Dist: humanize~=4.12.1
-Requires-Dist: importlib-metadata~=8.6.1
+Requires-Dist: importlib-metadata~=8.7.0
 Requires-Dist: jellyfish>=1.1
 Requires-Dist: jinja2~=3.1.3
 Requires-Dist: lsprotocol~=2023.0.1
@@ -90,8 +82,9 @@ to drive various underlying tools/frameworks to create real world testing scenar
 
 - [Installation](#installation)
   - [Requirements](#requirements)
-  - [Install Walkthrough](#install-walkthrough)
-- [Usage](#usage)
+  - [Setup](#setup)
+  - [Usage](#usage)
+- [Usage](#usage-1)
   - [Cucu Run](#cucu-run)
   - [Run specific browser version with docker](#run-specific-browser-version-with-docker)
 - [Extending Cucu](#extending-cucu)
@@ -103,40 +96,55 @@ to drive various underlying tools/frameworks to create real world testing scenar
   - [Install From Build](#install-from-build)
 
 # Installation
+Let's get your repo to start using the cucu framework!
+> [!NOTE] If you're not using uv, then just
+> `pip install cucu` for your repo
+
 ## Requirements
-Cucu requires
-1. python 3.9+
-2. docker (to do UI testing)
+1. Docker (for UI testing)
+2. The [uv](https://docs.astral.sh/uv/) tool
+3. A repo in a clean state
 
-## Install Walkthrough
-_Get your repo setup using cucu as a test framework_
+## Setup
+> [!NOTE] Always run cucu from your repo root folder
 
-1. install and start Docker if you haven't already
-2. install [cucu](https://pypi.org/project/cucu/)
+1. Have docker running (don't need it right now, but why not get ready for testing)
+2. Make sure you have no files to commit and a clean working tree
    ```
-   pip install cucu
+   git status
    ```
-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
+   Should report: `nothing to commit, working tree clean`
+
+3. Add [cucu](https://pypi.org/project/cucu/) to your project and activate your venv
+   ```
+   uv add cucu --dev
+   source .venv/bin/activate
+   ```
+4. Initialize cucu (copies the `init_data` folder to your repo)
+   ```
+   cucu init
+   ```
+5. Manually resolve any file conflicts
+   ```
+   git status
+   ```
+6. Run the example tests
+   ```
+   cucu run features
+   ```
+7. Done! But there is more optional stuff you can do, like:
+   1. Run with `--no-headless` mode to see the browser interaction
+   2. Run with `--generate-report` (or `-g`) to generate the html **report/** folder
+   3. Reference the exact test (i.e. scenario) with `features/example.feature:8` instead of using the `features` folder
+   ```
+   cucu run features/example.feature:8 -g --no-headless
+   ```
+
+## Usage
+> [!Note] Cucu needs to be run from your **repo root** (i.e. the parent of the `features` folder)
+
+
+1. list available cucu steps
    ```bash
    cucu steps
    ```
@@ -145,7 +153,7 @@ _Get your repo setup using cucu as a test framework_
      cucu steps | fzf
      # start typing for search
      ```
-5. **create your first cucu test**
+2. **create your first cucu test**
    - features/my_first_test.feature
      ```gherkin
      Feature: My First Cucu Test
@@ -157,7 +165,7 @@ _Get your repo setup using cucu as a test framework_
            And I click the button "Google Search"
           Then I wait to see the text "results"
      ```
-6. **run it**
+3. **run it**
    ```bash
    cucu run features/my_first_test.feature
    ```

{cucu-1.1.1 → cucu-1.2.0}/README.md

@@ -41,8 +41,9 @@ to drive various underlying tools/frameworks to create real world testing scenar
 
 - [Installation](#installation)
   - [Requirements](#requirements)
-  - [Install Walkthrough](#install-walkthrough)
-- [Usage](#usage)
+  - [Setup](#setup)
+  - [Usage](#usage)
+- [Usage](#usage-1)
   - [Cucu Run](#cucu-run)
   - [Run specific browser version with docker](#run-specific-browser-version-with-docker)
 - [Extending Cucu](#extending-cucu)
@@ -54,40 +55,55 @@ to drive various underlying tools/frameworks to create real world testing scenar
   - [Install From Build](#install-from-build)
 
 # Installation
+Let's get your repo to start using the cucu framework!
+> [!NOTE] If you're not using uv, then just
+> `pip install cucu` for your repo
+
 ## Requirements
-Cucu requires
-1. python 3.9+
-2. docker (to do UI testing)
+1. Docker (for UI testing)
+2. The [uv](https://docs.astral.sh/uv/) tool
+3. A repo in a clean state
 
-## Install Walkthrough
-_Get your repo setup using cucu as a test framework_
+## Setup
+> [!NOTE] Always run cucu from your repo root folder
 
-1. install and start Docker if you haven't already
-2. install [cucu](https://pypi.org/project/cucu/)
+1. Have docker running (don't need it right now, but why not get ready for testing)
+2. Make sure you have no files to commit and a clean working tree
    ```
-   pip install cucu
+   git status
    ```
-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
+   Should report: `nothing to commit, working tree clean`
+
+3. Add [cucu](https://pypi.org/project/cucu/) to your project and activate your venv
+   ```
+   uv add cucu --dev
+   source .venv/bin/activate
+   ```
+4. Initialize cucu (copies the `init_data` folder to your repo)
+   ```
+   cucu init
+   ```
+5. Manually resolve any file conflicts
+   ```
+   git status
+   ```
+6. Run the example tests
+   ```
+   cucu run features
+   ```
+7. Done! But there is more optional stuff you can do, like:
+   1. Run with `--no-headless` mode to see the browser interaction
+   2. Run with `--generate-report` (or `-g`) to generate the html **report/** folder
+   3. Reference the exact test (i.e. scenario) with `features/example.feature:8` instead of using the `features` folder
+   ```
+   cucu run features/example.feature:8 -g --no-headless
+   ```
+
+## Usage
+> [!Note] Cucu needs to be run from your **repo root** (i.e. the parent of the `features` folder)
+
+
+1. list available cucu steps
    ```bash
    cucu steps
    ```
@@ -96,7 +112,7 @@ _Get your repo setup using cucu as a test framework_
      cucu steps | fzf
      # start typing for search
      ```
-5. **create your first cucu test**
+2. **create your first cucu test**
    - features/my_first_test.feature
      ```gherkin
      Feature: My First Cucu Test
@@ -108,7 +124,7 @@ _Get your repo setup using cucu as a test framework_
            And I click the button "Google Search"
           Then I wait to see the text "results"
      ```
-6. **run it**
+3. **run it**
    ```bash
    cucu run features/my_first_test.feature
    ```

{cucu-1.1.1 → cucu-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cucu"
-version = "1.1.1"
+version = "1.2.0"
 description = "Easy BDD web testing"
 readme = "README.md"
 license = { text = "The Clear BSD License" }
@@ -27,30 +27,22 @@ classifiers = [
     "License :: OSI Approved :: BSD License",
     "Operating System :: OS Independent",
     "Natural Language :: English",
-    "Programming Language :: Python",
-    "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",
-    "Programming Language :: Python :: 3 :: Only",
     "Topic :: Software Development :: Testing :: BDD",
 ]
 include = [
     { path = "CHANGELOG.md", format = "sdist" },
     { path = "LICENSE", format = "sdist" },
 ]
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 dependencies = [
     "beautifulsoup4~=4.13.3",
-    "behave~=1.2.6",
+    "behave==1.2.6",
     "chromedriver-autoinstaller~=0.6.2",
-    "click~=8.1.7",
+    "click~=8.2.0",
     "coverage[toml]~=7.8",
     "geckodriver-autoinstaller~=0.1.0",
     "humanize~=4.12.1",
-    "importlib-metadata~=8.6.1",
+    "importlib-metadata~=8.7.0",
     "jellyfish>=1.1",
     "jinja2~=3.1.3",
     "lsprotocol~=2023.0.1",
@@ -76,6 +68,17 @@ cucu = "cucu.cli:main"
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/CHANGELOG.md",
+]
+exclude = [
+  "/data",
+  "/features",
+  "/tests",
+]
+
 [tool.uv]
 dev-dependencies = [
     "pre-commit>=3.8.0",

{cucu-1.1.1 → cucu-1.2.0}/src/cucu/behave_tweaks.py

@@ -3,10 +3,14 @@
 #      writing while not interfering with the way behave does its own log
 #      capturing
 #
+import os
 import sys
 import warnings
 from functools import wraps
 
+# set env var BEHAVE_STRIP_STEPS_WITH_TRAILING_COLON=yes before importing behave
+os.environ["BEHAVE_STRIP_STEPS_WITH_TRAILING_COLON"] = "yes"
+
 import behave
 from behave.__main__ import main as original_behave_main
 from behave.model import Table
@@ -62,7 +66,9 @@ def init_step_hooks(stdout, stderr):
                     # resolve variables in the table values
                     if ctx.table is not None:
                         ctx.table.original = Table(
-                            ctx.table.headings, rows=ctx.table.rows
+                            ctx.table.headings,
+                            rows=ctx.table.rows,
+                            line=ctx.table.line,
                         )
                         new_rows = []
                         for row in ctx.table.rows:
@@ -119,7 +125,9 @@ def init_step_hooks(stdout, stderr):
 
             return wrapper
 
-        behave.__dict__[decorator_name] = new_decorator
+        behave.__dict__[decorator_name.title()] = behave.__dict__[
+            decorator_name
+        ] = new_decorator
 
 
 _stdout = sys.stdout

{cucu-1.1.1 → cucu-1.2.0}/src/cucu/cli/core.py

@@ -8,6 +8,7 @@ import sys
 import time
 import xml.etree.ElementTree as ET
 from importlib.metadata import version
+from pathlib import Path
 from threading import Timer
 
 import click
@@ -468,7 +469,9 @@ def run(
                     time.sleep(1)
 
                 if timeout_reached:
-                    logger.warning("Timeout reached, send kill signal to workers")
+                    logger.warning(
+                        "Timeout reached, send kill signal to workers"
+                    )
                     kill_workers()
 
                 task_failed.update(async_results)
@@ -765,6 +768,39 @@ def vars(filepath):
     print(tabulate(variables, tablefmt="fancy_grid"))
 
 
+@main.command()
+@click.argument("filepath", default="")
+@click.option(
+    "-l",
+    "--logging-level",
+    default="INFO",
+    help="set logging level to one of debug, warn or info (default)",
+)
+def init(filepath, logging_level):
+    """
+    initialize cucu in the current directory
+
+    Copies the `init_data` directory to the current directory
+    """
+    os.environ["CUCU_LOGGING_LEVEL"] = logging_level.upper()
+    logger.init_logging(logging_level.upper())
+
+    init_data_dir = Path(__file__).parent.parent / "init_data"
+
+    logger.debug(f"cucu init: copy example directory from {init_data_dir=}")
+    repo_dir = filepath if filepath.strip() else os.path.join(os.getcwd())
+
+    features_dir = os.path.join(repo_dir, "features")
+    if os.path.exists(features_dir):
+        answer = input("Overwrite existing files? [y/N]:")
+        if answer.lower() != "y":
+            print("Aborted!")
+            return
+
+    shutil.copytree(init_data_dir, repo_dir, dirs_exist_ok=True)
+    print("You can now start writing your tests")
+
+
 @main.command()
 @click.option(
     "-b",

{cucu-1.1.1 → cucu-1.2.0}/src/cucu/cli/steps.py

@@ -47,6 +47,10 @@ def load_cucu_steps(filepath=None):
     stdout = stdout.getvalue()
     stderr = stderr.getvalue()
 
+    if stdout.startswith("USING RUNNER:"):
+        # remove the first line of the output so that linter won't error out trying to parse it as a step
+        stdout = "\n".join(stdout.split("\n")[1:])
+
     if stdout.startswith("ParserError"):
         print(stdout)
         raise RuntimeError(

{cucu-1.1.1 → cucu-1.2.0}/src/cucu/formatter/cucu.py

@@ -171,6 +171,10 @@ class CucuFormatter(Formatter):
             text = self.colorize(
                 f"{indent}{prefix}{keyword} {step.name}\n", "cyan"
             )
+        else:
+            text = self.colorize(
+                f"{indent}{prefix}{keyword} {step.name}\n", "yellow"
+            )
 
         if self.monochrome:
             self.stream.write(f"{text}")

cucu-1.2.0/src/cucu/init_data/.gitignore

@@ -0,0 +1,5 @@
+# Cucu temp files
+.monitor.png
+report/
+results/
+# /cucurc.yml # TODO: Uncomment this rule as the file should be a local only config file

cucu-1.2.0/src/cucu/init_data/README.md

@@ -0,0 +1,63 @@
+<!-- your project readme here -->
+
+# Development
+## E2E tests
+Use [cucu](https://pypi.org/project/cucu/) to run e2e-tests with the following:
+1. make sure you're in the **repo root**
+2. install the --dev dependecies
+    ```sh
+    uv sync --dev
+    ```
+3. activate it
+    ```sh
+    source .venv/bin/activate
+    ```
+4. run scenario
+    ```sh
+    cucu run features
+    ```
+
+### Other helpful commands
+
+- Show all steps
+    ```sh
+    cucu steps
+    ```
+- Run scenario by tag
+    ```sh
+    cucu run features --tag my_tag
+    ```
+- Run scenario by line number
+    ```sh
+    cucu run features/example.feature:8
+    ```
+- Generate an html report
+    ```sh
+    cucu report
+    ```
+- Run scenarios and generate report
+    ```sh
+    cucu run features -g
+    ```
+- Lint your feature files!
+    _see `/features/lint_rules` for custom rules_
+    ```sh
+    cucu lint
+    ```
+
+### Tagging Tests
+
+> [!Note] This is just an example of how use tags
+
+1. Tags are very important as they provide:
+
+   - Critical metadata for reporting and tracking
+   - Control where it runs in CI
+   - Filtering on what tests should run
+
+2. They can be at the **Feature** file level or at the **Scenario** level.
+
+3. Here's a list of some notable tags
+   | Tag       | Gist                                                                                            | Example   |
+   | --------- | ----------------------------------------------------------------------------------------------- | --------- |
+   | @sid-#### | **[Required]** The scenario (i.e. test case) id (numbers only) that is used to track and record | @sid-1234 |

cucu-1.2.0/src/cucu/init_data/cucurc.yml

@@ -0,0 +1,10 @@
+# Don't check in this file! (I mean you could, but you probably don't want to)
+
+# The config heirarchy starts with ~/.cucurc.yml, then this file, and down the folder tree.
+# Use this file for local configuration per user
+
+# This is just an example, normally you could have it as environment variables or pass it in the command line
+MY_SECRET_USERNAME: "Bob"
+MY_SECRET_PASSWORD: "123456"
+
+SOME_OTHER_SECRET: "another secret"

cucu-1.2.0/src/cucu/init_data/data/www/example.html

@@ -0,0 +1,27 @@
+<html>
+  <head>
+    <title>Some Example</title>
+    <script>
+    function update() {
+      document.querySelector("#my_status").textContent = "Welcome " + document.querySelector("#my_name").value + " !";
+      document.querySelector("#my_name").value = "";
+      document.querySelector("#my_key").value = "";
+    }
+    </script>
+  </head>
+  <body>
+
+    <h1>Some Example</h1>
+    <div id="my_status"></div>
+    <br/>
+
+    <div style="background: aliceblue;">Fake login box
+      <br/>
+      <label>username:</label><input id="my_name" type="text"></input>
+      <br/>
+      <label>The password here but use aria label to find</label><input aria-label="password" id="my_key" type="password"></input>
+      <br/>
+      <button onclick="update();">Login</button>
+    </div>
+  </body>
+</html>

cucu-1.2.0/src/cucu/init_data/features/cucurc.yml

@@ -0,0 +1,9 @@
+# Checkin this file for the repo configuration
+
+# CUCU_SECRETS is a comma-separated list of the names of the secrets (not the values)
+CUCU_SECRETS: "MY_SECRET_PASSWORD,SOME_OTHER_SECRET"
+
+CUCU_BROWSER_WINDOW_HEIGHT: 1080
+CUCU_BROWSER_WINDOW_WIDTH: 1920
+
+CUCU_BROKEN_IMAGES_PAGE_CHECK: false

cucu-1.2.0/src/cucu/init_data/features/environment.py

@@ -0,0 +1,90 @@
+# Define custom before/after hooks here
+# Warn: Don't import this file into other python files to avoid duplicating hook registers
+
+import datetime
+
+from cucu import (
+    register_custom_scenario_subheader_in_report_handling,
+    register_custom_tags_in_report_handling,
+)
+from cucu.config import CONFIG
+from cucu.environment import *  # noqa
+
+# point the `cucu lint` command to our own custom linting rules
+CONFIG["CUCU_LINT_RULES_PATH"] = "features/lint_rules"
+
+
+def make_scenario_id_clickable(tag):
+    """Example of processing a tag to open up a link to some url"""
+    scenario_id = tag.replace(r"@sid-", "")
+    return f'<a href="https://localhost/index.php?/cases/view/{scenario_id}" target="_blank">{tag}</a>'
+
+
+register_custom_tags_in_report_handling(r"@sid-.+", make_scenario_id_clickable)
+
+
+def my_example_subheader(scenario):
+    """Example of a custom subheader for the report
+
+    This may be useful if you want to link results to your log monitor system
+    """
+
+    query_time = ""
+    if (
+        "steps" in scenario
+        and len(scenario["steps"]) > 0
+        and "result" in scenario["steps"][0]
+    ):
+        one_minute = datetime.timedelta(minutes=1)
+        # get start time from first step iso timestamp
+        start_datetime = (
+            datetime.datetime.fromisoformat(
+                scenario["steps"][0]["result"]["timestamp"]
+            )
+            - one_minute
+        )
+        epoc_start_time_ms = int(start_datetime.timestamp()) * 1000
+
+        end_datetime = start_datetime + (
+            one_minute * 30
+        )  # default to start + 30 minutes
+        for step in reversed(scenario["steps"]):
+            if step.get("result", []) and step["result"].get(
+                "timestamp", None
+            ):
+                end_duration = (
+                    datetime.timedelta(
+                        seconds=step["result"].get("duration", 0)
+                    )
+                    + one_minute
+                )
+                end_datetime = (
+                    datetime.datetime.fromisoformat(
+                        step["result"]["timestamp"]
+                    )
+                    + end_duration
+                )
+                break
+
+        epoc_end_time_ms = int(end_datetime.timestamp()) * 1000
+        query_time = f"&begin={epoc_start_time_ms}&end={epoc_end_time_ms}"
+
+    account_id = "123456"
+    result = ""
+    if account_id and query_time:
+        html = "<span>Log Monitoring System: "
+        html += f'<a href="https://localhost/logger?account={account_id}{query_time}" target="_blank">Link 🔗</a> '
+        result = html
+
+    return result
+
+
+register_custom_scenario_subheader_in_report_handling(my_example_subheader)
+
+
+# TODO:
+# - add a register_page_check_hook  # to ensure the page is loaded)
+# - add a register_before_retry_hook  # when using the retry decorator on steps)
+# - add a register_custom_tags_in_report_handling
+# - add a register_custom_scenario_subheader_in_report_handling
+# - add a register_custom_variable_handling