cucu 1.0.0__py3-none-any.whl

cucu/steps/flow_control_steps.py

@@ -0,0 +1,198 @@
+import os
+import re
+import subprocess
+import time
+
+from cucu import logger, retry, run_steps, step
+from cucu.config import CONFIG
+from cucu.hooks import register_after_this_scenario_hook
+
+
+@step('I skip this scenario if the file at "{filepath}" exists')
+def skip_scenario_if_file_exists(ctx, filepath):
+    if os.path.exists(filepath):
+        ctx.scenario.skip(
+            reason='skipping scenario since file at "{filepath}" exists'
+        )
+
+
+@step('I expect the following step to fail with "{message}"')
+def expect_the_following_step_to_fail(ctx, message):
+    try:
+        run_steps(ctx, ctx.text)
+    except Exception as exception:
+        if str(exception).find(message) == -1:
+            raise RuntimeError(
+                f'expected failure message was "{str(exception)}" not "{message}"'
+            )
+        return
+
+    raise RuntimeError("previous steps did not fail!")
+
+
+@step('I should see the previous step took less than "{seconds}" seconds')
+def should_see_previous_step_took_less_than(ctx, seconds):
+    if ctx.previous_step_duration > float(seconds):
+        raise RuntimeError(
+            f"previous step took {ctx.previous_step_duration}, which is more than {seconds}"
+        )
+
+
+@step('I should see the previous step took more than "{seconds}" seconds')
+def should_see_previous_step_took_more_than(ctx, seconds):
+    if ctx.previous_step_duration < float(seconds):
+        raise RuntimeError(
+            f"previous step took {ctx.previous_step_duration}, which is less than {seconds}"
+        )
+
+
+@step("I wait to see the following steps succeed")
+def wait_to_see_the_following_steps_suceed(ctx):
+    retry(run_steps)(ctx, ctx.text)
+
+
+@step('I wait up to "{seconds}" seconds to see the following steps succeed')
+def wait_up_to_seconds_to_see_the_following_steps_suceed(ctx, seconds):
+    retry(run_steps, wait_up_to_s=float(seconds))(ctx, ctx.text)
+
+
+def wait_for_steps_to_fail(ctx, steps, timeout=None):
+    def steps_should_fail():
+        try:
+            run_steps(ctx, steps)
+        except:  # noqa: E722
+            return
+
+        raise RuntimeError("underlying steps did not fail")
+
+    retry(steps_should_fail, wait_up_to_s=timeout)()
+
+
+@step("I wait to see the following steps fail")
+def wait_to_see_the_following_steps_fail(ctx):
+    wait_for_steps_to_fail(ctx, ctx.text)
+
+
+@step('I wait up to "{seconds}" seconds to see the following steps fail')
+def wait_up_to_seconds_to_see_the_following_steps_fail(ctx, seconds):
+    wait_for_steps_to_fail(ctx, ctx.text, timeout=float(seconds))
+
+
+def repeat_steps(ctx, steps, repeat, variable=None):
+    for index in range(0, repeat):
+        if variable is not None:
+            CONFIG[variable] = index + 1
+
+        run_steps(ctx, steps)
+
+
+@step('I repeat "{repeat}" times the following steps')
+def repeat_n_times_the_following_steps(ctx, repeat):
+    repeat_steps(ctx, ctx.text, int(repeat))
+
+
+@step(
+    'I repeat "{repeat}" times the following steps with iteration variable "{variable}"'
+)
+def repeat_n_times_the_following_steps_with_variable(ctx, repeat, variable):
+    repeat_steps(ctx, ctx.text, int(repeat), variable=variable)
+
+
+@step('I run the following steps if the file at "{filepath}" does not exist')
+def run_steps_if_file_does_not_exist(ctx, filepath):
+    if not os.path.exists(filepath):
+        run_steps(ctx, ctx.text)
+
+
+@step('I run the following steps if the file at "{filepath}" exists')
+def run_steps_if_file_exists(ctx, filepath):
+    if os.path.exists(filepath):
+        run_steps(ctx, ctx.text)
+
+
+@step('I run the following timed steps as "{name}"')
+def run_and_measure_the_following_steps(ctx, name):
+    start = time.time()
+    run_steps(ctx, ctx.text)
+    duration = round(time.time() - start, 3)
+    logger.info(f'"{name}" timer took {duration}s')
+
+
+@step('I start the timer "{name}"')
+def start_the_timer(ctx, name):
+    ctx.step_timers[name] = time.time()
+
+
+@step('I stop the timer "{name}"')
+def stop_the_timer(ctx, name):
+    if name not in ctx.step_timers:
+        raise RuntimeError(f'no previously started timer with name "{name}"')
+    start = ctx.step_timers[name]
+    del ctx.step_timers[name]
+
+    duration = round(time.time() - start, 3)
+    logger.info(f'"{name}" timer took {duration}s')
+
+
+def run_feature(ctx, filepath, results):
+    command = f"cucu run {filepath} --results {results}"
+    process = subprocess.run(command, shell=True)  # nosec
+
+    return_code = process.returncode
+    if return_code != 0:
+        raise RuntimeError(
+            f'"{command}" exited with {return_code}, see above for details'
+        )
+
+
+@step(
+    'I run the feature at "{feature_filepath}" with results at "{results_filepath}"'
+)
+def run_feature_at(ctx, feature_filepath, results_filepath):
+    run_feature(ctx, feature_filepath, results_filepath)
+
+
+@step(
+    'I run the feature at "{feature_filepath}" with results at "{results_filepath}" if the file at "{filepath}" does not exist'
+)
+def run_feature_if_file_does_not_exist(
+    ctx, feature_filepath, results_filepath, filepath
+):
+    if not os.path.exists(filepath):
+        run_feature(ctx, feature_filepath, results_filepath)
+
+
+@step(
+    'I run the feature at "{feature_filepath}" with results at "{results_filepath}" if the file at "{filepath}" exists'
+)
+def run_feature_if_file_exists(
+    ctx, feature_filepath, results_filepath, filepath
+):
+    if os.path.exists(filepath):
+        run_feature(ctx, feature_filepath, results_filepath)
+
+
+@step("I run the following steps at the end of the current scenario")
+def run_the_following_steps_at_end_of_scenario(ctx):
+    steps = ctx.text
+
+    def run_final_steps(ctx):
+        run_steps(ctx, steps)
+
+    register_after_this_scenario_hook(run_final_steps)
+
+
+for operation, operator in {
+    "is equal to": lambda x, y: x == y,
+    "is not equal to": lambda x, y: x != y,
+    "contains": lambda x, y: y in x,
+    "does not contain": lambda x, y: y not in x,
+    "matches": lambda x, y: re.match(y, x),
+    "does not match": lambda x, y: not (re.match(y, x)),
+}.items():
+    # the operator keyword below is used to scope the value of the operator
+    # value to the correct value at runtime when creating the various steps
+    @step('I run the following steps if "{this}" ' + operation + ' "{that}"')
+    def run_steps_if_this_operator_that(ctx, this, that, operator=operator):
+        if operator(this, that):
+            run_steps(ctx, ctx.text)

cucu/steps/image_steps.py

@@ -0,0 +1,37 @@
+from cucu import helpers
+from cucu.utils import take_saw_element_screenshot
+
+
+def find_image(ctx, name, index=0):
+    """
+    find an input on screen by fuzzy matching on the name provided and the
+    target element:
+
+        * <img>
+
+    parameters:
+      ctx(object): behave context object used to share data between steps
+      name(str):   name that identifies the desired image on screen
+      index(str):  the index of the image if there are duplicates
+
+    returns:
+        the WebElement that matches the provided arguments.
+    """
+    ctx.check_browser_initialized()
+
+    name = name.replace('"', '\\"')
+    images = ctx.browser.css_find_elements(f'img[alt="{name}"')
+
+    if index >= len(images):
+        return None
+
+    element = images[index]
+
+    take_saw_element_screenshot(ctx, "image", name, index, element)
+
+    return element
+
+
+helpers.define_should_see_thing_with_name_steps(
+    "image with the alt text", find_image
+)

cucu/steps/input_steps.py

@@ -0,0 +1,301 @@
+import sys
+
+import humanize
+
+# XXX: this would have to be generalized to other browser abstractions
+from selenium.webdriver.common.keys import Keys
+
+from cucu import fuzzy, helpers, retry, step
+from cucu.utils import take_saw_element_screenshot
+
+from . import base_steps
+
+
+def find_input(ctx, name, index=0):
+    """
+    find an input on screen by fuzzy matching on the name and index provided.
+
+        * <input>
+        * <textarea>
+
+    parameters:
+      ctx(object): behave context object used to share data between steps
+      name(str):   name that identifies the desired input on screen
+      index(str):  the index of the input if there are a few with the same name.
+
+    returns:
+        the WebElement that matches the provided arguments.
+
+    raises:
+        a RuntimeError if the input isn't found
+    """
+    ctx.check_browser_initialized()
+
+    element = fuzzy.find(
+        ctx.browser,
+        name,
+        [
+            # we can only write into things that do not have the type:
+            # button, checkbox, radio, color, hidden, range, reset
+            "input[type!=button][type!=checkbox][type!=radio][button!=color][button!=hidden][button!=range][button!=reset]",
+            "textarea",
+        ],
+        index=index,
+    )
+
+    prefix = "" if index == 0 else f"{humanize.ordinal(index)} "
+
+    take_saw_element_screenshot(ctx, "input", name, index, element)
+
+    if element is None:
+        raise RuntimeError(f'unable to find the {prefix}input "{name}"')
+
+    return element
+
+
+def click_input(ctx, input_):
+    """
+    internal method used to simply click a input element
+    """
+    ctx.check_browser_initialized()
+
+    if base_steps.is_disabled(input_):
+        raise RuntimeError("unable to click the input, as it is disabled")
+
+    ctx.browser.click(input_)
+
+
+def clear_input(input_):
+    """
+    internal method used to clear inputs and make sure they clear correctly
+    """
+    # Keys.CONTROL works on the Selenium grid (when running in CI)
+    #  - it stopped working on laptop after the upgrade in antd version (Feb 2023)
+    # Keys.COMMAND works on laptop, but not on Selenium grid,
+    # and actually causes an active session on the grid to hang.
+    if "darwin" in sys.platform:
+        input_.send_keys(Keys.COMMAND, "a")
+    else:
+        input_.send_keys(Keys.CONTROL, "a")
+    input_.send_keys(Keys.BACKSPACE)
+
+
+def find_n_write(ctx, name, value, index=0, clear_existing=True):
+    """
+    find the input with the name provided and write the value provided into it.
+
+    parameters:
+      ctx(object): behave context object used to share data between steps
+      name(str):   name that identifies the desired input on screen
+      index(str):  the index of the input if there are a few with the same name.
+      clear_existing(bool): if clearing the existing content before writing
+
+    raises:
+        an error if the desired input is not found
+    """
+    ctx.check_browser_initialized()
+
+    input_ = find_input(ctx, name, index=index)
+
+    if base_steps.is_disabled(input_):
+        raise RuntimeError("unable to write into the input, as it is disabled")
+
+    if clear_existing:
+        clear_input(input_)
+
+    if len(value) > 512:
+        #
+        # to avoid various bugs with writing large chunks of text into
+        # inputs/textareas using send_keys we can just put the text into the
+        # @value attribute and simulate a keystroke so other UI related events
+        # fire, list of some bugs:
+        #
+        #  * https://github.com/seleniumhq/selenium-google-code-issue-archive/issues/4469
+        #  * various stackoverflow articles on this matter
+        #
+        ctx.browser.execute(
+            "arguments[0].value = arguments[1];", input_, value
+        )
+        input_.send_keys(" ")
+        input_.send_keys(Keys.BACKSPACE)
+
+    else:
+        input_.send_keys(value)
+
+
+def find_n_clear(ctx, name, index=0):
+    """
+    find the input with the name provided and clear whatever value it has.
+
+    parameters:
+      ctx(object): behave context object used to share data between steps
+      name(str):   name that identifies the desired input on screen
+      index(str):  the index of the input if there are a few with the same name.
+
+    raises:
+        an error if the desired input is not found
+    """
+    ctx.check_browser_initialized()
+
+    input_ = find_input(ctx, name, index=index)
+
+    if base_steps.is_disabled(input_):
+        raise RuntimeError("unable to clear the input, as it is disabled")
+
+    clear_input(input_)
+
+
+def assert_input_value(ctx, name, value, index=0):
+    """
+    assert the input with the name provided has the value specified, unless the
+    value is None which then means to verify there is not value set.
+
+    Params:
+        ctx(object):   behave context used to share information between steps
+        name(string):  name of the input to find and assert is visible
+        value(string): value to assert the input has, when set to None we verify
+                       the input currently has no value.
+        index(int):    index of the input to assert when there are multiple
+                       inputs have the same name.
+    """
+    input_ = find_input(ctx, name, index=index)
+    actual = input_.get_attribute("value")
+    prefix = "" if index == 0 else f"{humanize.ordinal(index)} "
+
+    if value is None:
+        if actual != "":
+            raise RuntimeError(
+                f'the {prefix}input "{name}" has value "{actual}"'
+            )
+
+    elif actual != value:
+        raise RuntimeError(f'the {prefix}input "{name}" has value "{actual}"')
+
+
+helpers.define_should_see_thing_with_name_steps("input", find_input)
+helpers.define_thing_with_name_in_state_steps(
+    "input", "disabled", find_input, base_steps.is_disabled
+)
+helpers.define_thing_with_name_in_state_steps(
+    "input", "not disabled", find_input, base_steps.is_not_disabled
+)
+helpers.define_run_steps_if_I_can_see_element_with_name_steps(
+    "input", find_input
+)
+helpers.define_action_on_thing_with_name_steps(
+    "input", "click", find_input, click_input, with_nth=True
+)
+
+
+@step('I write "{value}" into the input "{name}"')
+def writes_into_input(ctx, value, name):
+    find_n_write(ctx, name, value)
+
+
+@step('I wait to write "{value}" into the input "{name}"')
+def wait_to_write_into_input(ctx, value, name):
+    retry(find_n_write)(ctx, name, value)
+
+
+@step(
+    'I wait up to "{seconds}" seconds to write "{value}" into the input "{name}"'
+)
+def wait_up_to_write_into_input(ctx, seconds, value, name):
+    retry(find_n_write, wait_up_to_s=float(seconds))(ctx, name, value)
+
+
+@step('I write the following into the input "{name}"')
+def writes_multi_lines_into_input(ctx, name):
+    find_n_write(ctx, name, ctx.text)
+
+
+@step('I wait to write the following into the input "{name}"')
+def wait_to_write_multi_lines_into_input(ctx, name):
+    retry(find_n_write)(ctx, name, ctx.text)
+
+
+@step(
+    'I wait up to "{seconds}" to write the following into the input "{name}"'
+)
+def wait_up_to_write_multi_lines_into_input(ctx, seconds, name):
+    retry(find_n_write, wait_up_to_s=float(seconds))(ctx, name, ctx.text)
+
+
+@step('I send the "{key}" key to the input "{name}"')
+def send_keys_to_input(ctx, key, name):
+    find_n_write(ctx, name, Keys.__dict__[key.upper()], clear_existing=False)
+
+
+@step('I clear the input "{name}"')
+def clear_the_input(ctx, name):
+    find_n_clear(ctx, name)
+
+
+@step('I wait to clear the input "{name}"')
+def wait_to_clear_input(ctx, name):
+    retry(find_n_clear)(ctx, name)
+
+
+@step('I wait up to "{seconds}" seconds to clear the input "{name}"')
+def wait_up_to_clear_input(ctx, seconds, name):
+    retry(find_n_clear, wait_up_to_s=float(seconds))(ctx, name)
+
+
+@step('I should see the input "{name}" is empty')
+def should_see_the_input_is_empty(ctx, name):
+    assert_input_value(ctx, name, None)
+
+
+@step('I should see "{value}" in the input "{name}"')
+def should_see_the_input_with_value(ctx, value, name):
+    assert_input_value(ctx, name, value)
+
+
+@step('I wait to see the value "{value}" in the input "{name}"')
+def wait_to_see_the_input_with_value(ctx, value, name):
+    retry(assert_input_value)(ctx, name, value)
+
+
+@step('I should see the following in the input "{name}"')
+def should_see_the_following_input_with_value(ctx, name):
+    assert_input_value(ctx, name, ctx.text)
+
+
+@step('I wait to see the following in the input "{name}"')
+def wait_to_see_the_following_input_with_value(ctx, name):
+    retry(assert_input_value)(ctx, name, ctx.text)
+
+
+@step('I should see no value in the input "{name}"')
+def should_to_see_the_input_with_no_value(ctx, name):
+    assert_input_value(ctx, name, None)
+
+
+@step('I write "{value}" into the "{nth:nth}" input "{name}"')
+def write_into_the_nth_input(ctx, value, nth, name):
+    find_n_write(ctx, name, value, index=nth)
+
+
+@step('I wait to write "{value}" into the "{nth:nth}" input "{name}"')
+def wait_to_write_into_the_nth_input(ctx, value, nth, name):
+    retry(find_n_write)(ctx, name, value, index=nth)
+
+
+@step('I wait to see the "{nth:nth}" input "{name}"')
+def wait_to_see_the_nth_input(ctx, nth, name):
+    retry(find_input)(ctx, name, index=nth)
+
+
+@step('I should see "{value}" in the "{nth:nth}" input "{name}"')
+def should_see_the_nth_input_with_value(ctx, value, nth, name):
+    assert_input_value(ctx, name, value, index=nth)
+
+
+@step('I wait to see the value "{value}" in the "{nth:nth}" input "{name}"')
+def wait_to_see_the_nth_input_with_value(ctx, value, nth, name):
+    retry(assert_input_value)(ctx, name, value, index=nth)
+
+
+@step('I should see no value in the "{nth:nth}: input "{name}"')
+def should_see_the_nth_input_with_no_value(ctx, nth, name):
+    assert_input_value(ctx, name, None, index=nth)

cucu/steps/link_steps.py

@@ -0,0 +1,63 @@
+from cucu import fuzzy, helpers
+from cucu.utils import take_saw_element_screenshot
+
+from . import base_steps
+
+
+def find_link(ctx, name, index=0):
+    """
+    find a link on screen by fuzzy matching on the name provided and the target
+    element:
+
+        * <a>
+        * <* role="link">
+
+    parameters:
+      ctx(object): behave context object used to share data between steps
+      name(str):   name that identifies the desired link on screen
+      index(str):  the index of the link if there are duplicates
+
+    returns:
+        the WebElement that matches the provided arguments.
+    """
+    ctx.check_browser_initialized()
+    element = fuzzy.find(
+        ctx.browser, name, ["a", '*[role="link"]'], index=index
+    )
+
+    take_saw_element_screenshot(ctx, "link", name, index, element)
+
+    return element
+
+
+def click_link(ctx, link):
+    """
+    internal method to click a link
+    """
+    ctx.check_browser_initialized()
+
+    if base_steps.is_disabled(link):
+        raise RuntimeError("unable to click the link, as it is disabled")
+
+    ctx.browser.click(link)
+
+
+helpers.define_should_see_thing_with_name_steps(
+    "link", find_link, with_nth=True
+)
+helpers.define_action_on_thing_with_name_steps(
+    "link", "click", find_link, click_link, with_nth=True
+)
+helpers.define_thing_with_name_in_state_steps(
+    "link", "disabled", find_link, base_steps.is_disabled, with_nth=True
+)
+helpers.define_thing_with_name_in_state_steps(
+    "link",
+    "not disabled",
+    find_link,
+    base_steps.is_not_disabled,
+    with_nth=True,
+)
+helpers.define_run_steps_if_I_can_see_element_with_name_steps(
+    "link", find_link
+)

cucu/steps/menuitem_steps.py

@@ -0,0 +1,39 @@
+#
+# menuitem steps
+# https://www.w3.org/TR/wai-aria-1.1/#menuitem
+#
+from cucu import fuzzy, helpers
+from cucu.utils import take_saw_element_screenshot
+
+from . import base_steps
+
+
+def find_menuitem(ctx, name, index=0):
+    """
+    find a menuitem containing the menuitem provide.
+
+    parameters:
+      ctx(object): behave context object used to share data between steps
+      name(str):   name that identifies the desired menuitem on screen
+      index(str):  the index of the menuitem if there are duplicates
+
+    returns:
+        the WebElement that matches the provided arguments.
+    """
+    ctx.check_browser_initialized()
+    element = fuzzy.find(
+        ctx.browser, name, ['*[role="menuitem"]'], index=index
+    )
+
+    take_saw_element_screenshot(ctx, "menuitem", name, index, element)
+
+    return element
+
+
+helpers.define_should_see_thing_with_name_steps("menu item", find_menuitem)
+helpers.define_thing_with_name_in_state_steps(
+    "menu item", "disabled", find_menuitem, base_steps.is_disabled
+)
+helpers.define_thing_with_name_in_state_steps(
+    "menu item", "not disabled", find_menuitem, base_steps.is_not_disabled
+)

cucu/steps/platform_steps.py

@@ -0,0 +1,29 @@
+import sys
+
+from cucu import run_steps, step
+
+
+@step("I skip this scenario if not on mac")
+def skip_scenario_if_on_mac(ctx):
+    if "darwin" not in sys.platform:
+        ctx.scenario.skip(reason="skipping scenario since we're not on a mac")
+
+
+@step("I skip this scenario if not on linux")
+def skip_scenario_if_on_linuxc(ctx):
+    if "linux" not in sys.platform:
+        ctx.scenario.skip(
+            reason="skipping scenario since we're not on a linux"
+        )
+
+
+@step("I run the following steps if on mac")
+def run_steps_if_on_mac(ctx):
+    if "darwin" in sys.platform:
+        run_steps(ctx, ctx.text)
+
+
+@step("I run the following steps if on linux")
+def run_steps_if_on_linux(ctx):
+    if "linux" in sys.platform:
+        run_steps(ctx, ctx.text)