cumulusci-plus 5.0.0__py3-none-any.whl

cumulusci/robotframework/SalesforcePlaywright.py

@@ -0,0 +1,220 @@
+import re
+import time
+
+from Browser import SupportedBrowsers
+from Browser.utils.data_types import KeyAction, PageLoadStates
+from robot.utils import timestr_to_secs
+
+from cumulusci.robotframework.base_library import BaseLibrary
+from cumulusci.robotframework.faker_mixin import FakerMixin
+from cumulusci.robotframework.utils import (
+    WAIT_FOR_AURA_SCRIPT,
+    capture_screenshot_on_error,
+)
+
+
+class SalesforcePlaywright(FakerMixin, BaseLibrary):
+    ROBOT_LIBRARY_SCOPE = "Suite"
+
+    def __init__(self):
+        super().__init__()
+        self._browser = None
+
+    @property
+    def browser(self):
+        if self._browser is None:
+            self._browser = self.builtin.get_library_instance("Browser")
+        return self._browser
+
+    def get_current_record_id(self):
+        """Parses the current url to get the object id of the current record.
+        This expects the url to contain an id that matches [a-zA-Z0-9]{15,18}
+        """
+        OID_REGEX = r"^(%2F)?([a-zA-Z0-9]{15,18})$"
+        url = self.browser.evaluate_javascript(None, "window.location.href")
+        for part in url.split("/"):
+            oid_match = re.match(OID_REGEX, part)
+            if oid_match is not None:
+                return oid_match[2]
+        raise AssertionError(f"Could not parse record id from url: {url}")
+
+    def go_to_record_home(self, obj_id):
+        """Navigates to the Home view of a Salesforce Object
+
+        After navigating, this will wait until the slds-page-header_record-home
+        div can be found on the page.
+        """
+        url = self.cumulusci.org.lightning_base_url
+        url = f"{url}/lightning/r/{obj_id}/view"
+        self.browser.go_to(url)
+        self.wait_until_loading_is_complete("div.slds-page-header_record-home")
+
+    def delete_records_and_close_browser(self):
+        """This will close all open browser windows and then delete
+        all records that were created with the Salesforce API during
+        this testing session.
+        """
+        self.browser.close_browser("ALL")
+        self.salesforce_api.delete_session_records()
+
+    def open_test_browser(
+        self, size=None, useralias=None, wait=True, record_video=None
+    ):
+        """Open a new Playwright browser, context, and page to the default org.
+
+        The return value is a tuple of the browser id, context id, and page details
+        returned by the Playwright keywords New Browser, New Context, and New Page.
+
+        This provides the most common environment for testing. For more control,
+        you can create your own browser environment with the Browser library
+        keywords `Create Browser`, `Create Context`, and `Create Page`.
+
+        To record a video of the session, set `record_video` to True. The video
+        (*.webm) will be viewable in the log.html file at the point where this
+        keyword is logged.
+
+        This keyword automatically calls the browser keyword `Wait until network is idle`.
+        """
+
+        wait = self.builtin.convert_to_boolean(wait)
+        default_size = self.builtin.get_variable_value(
+            "${DEFAULT BROWSER SIZE}", "1280x1024"
+        )
+        size = size or default_size
+
+        browser = self.builtin.get_variable_value("${BROWSER}", "chrome")
+        headless = browser.startswith("headless")
+        browser_type = browser[8:] if headless else browser
+        browser_type = "chromium" if browser_type == "chrome" else browser_type
+        browser_enum = getattr(SupportedBrowsers, browser_type, None)
+
+        # Note: we can't just pass alias=useralias in the case of useralias being None.
+        # That value gets passed to a salesforce query which barfs if the value
+        # is None.
+        login_url = (
+            self.cumulusci.login_url(alias=useralias)
+            if useralias
+            else self.cumulusci.login_url()
+        )
+
+        if record_video:
+            # ugh. the "dir" value must be non-empty, and will be treated as
+            # a folder name under the browser/video folder. using "../video"
+            # seems to be the only way to get the videos to go directly in
+            # the video folder. Also, using "." doesn't work :-/
+            record_video = {"dir": "../video"}
+        width, height = size.split("x", 1)
+
+        browser_id = self.browser.new_browser(browser=browser_enum, headless=headless)
+        context_id = self.browser.new_context(
+            viewport={"width": width, "height": height}, recordVideo=record_video
+        )
+        self.browser.set_browser_timeout("15 seconds")
+        page_details = self.browser.new_page(login_url)
+
+        if wait:
+            self.wait_until_salesforce_is_ready(login_url)
+        return browser_id, context_id, page_details
+
+    @capture_screenshot_on_error
+    def wait_until_loading_is_complete(self, locator=None, timeout="15 seconds"):
+        """Wait for a lightning page to load.
+
+        By default this keyword will wait for any element with the
+        class 'slds-template__container', but a different locator can
+        be provided.
+
+        In addition to waiting for the element, it will also wait for
+        any pending aura events to finish.
+
+        """
+        locator = (
+            "//div[contains(@class, 'slds-template__container')]/*"
+            if locator is None
+            else locator
+        )
+        self.browser.get_elements(locator)
+
+        self.browser.evaluate_javascript(None, WAIT_FOR_AURA_SCRIPT)
+        # An old knowledge article recommends waiting a second. I don't
+        # like it, but it seems to help. We should do a wait instead,
+        # but I can't figure out what to wait on.
+        time.sleep(1)
+
+    @capture_screenshot_on_error
+    def wait_until_salesforce_is_ready(
+        self, login_url, locator=None, timeout="30 seconds"
+    ):
+        """Attempt to wait until we land on a lightning page
+
+        In addition to waiting for a lightning page, this keyword will
+        also attempt to wait until there are no more pending ajax
+        requests.
+
+        The timeout parameter is taken as a rough guideline. This
+        keyword will actually wait for half of the timeout before
+        starting checks for edge cases.
+
+        """
+
+        timeout_seconds = timestr_to_secs(timeout)
+        start_time = time.time()
+
+        locator = locator or "div.slds-template__container"
+        expected_url = rf"/{self.cumulusci.org.lightning_base_url}\/lightning\/.*/"
+
+        while True:
+            try:
+                # only wait for half of the timeout before doing some additional
+                # checks. This seems to work better than one long timeout.
+                self.browser.wait_for_navigation(
+                    expected_url, timeout_seconds // 2, PageLoadStates.networkidle
+                )
+                self.wait_until_loading_is_complete(locator)
+                # No errors? We're golden.
+                break
+
+            except Exception as exc:
+                # dang. Maybe we landed somewhere unexpected?
+                if self._check_for_classic():
+                    continue
+
+                if time.time() - start_time > timeout_seconds:
+                    self.browser.take_screenshot()
+                    raise Exception("Timed out waiting for a lightning page") from exc
+
+            # If at first you don't succeed, ...
+            self.browser.go_to(login_url)
+
+    def _check_for_classic(self):
+        """Switch to lightning if we land on a classic page
+
+        This seems to happen randomly, causing tests to fail
+        catastrophically. The idea is to detect such a case and
+        auto-click the "switch to lightning" link
+
+        """
+        try:
+            self.browser.get_element("a.switch-to-lightning")
+            self.builtin.log(
+                "It appears we are on a classic page; attempting to switch to lightning",
+                "WARN",
+            )
+            # just in case there's a modal present we'll try simulating
+            # the escape key. Then, click on the switch-to-lightning link
+            self.browser.keyboard_key(KeyAction.press, "Escape")
+            self.builtin.sleep("1 second")
+            self.browser.click("a.switch-to-lightning")
+            return True
+
+        except (AssertionError):
+            return False
+
+    def breakpoint(self):
+        """Serves as a breakpoint for the robot debugger
+
+        Note: this keyword is a no-op unless the ``robot_debug`` option for
+        the task has been set to ``true``. Unless the option has been
+        set, this keyword will have no effect on a running test.
+        """
+        return None

cumulusci/robotframework/SalesforcePlaywright.robot

@@ -0,0 +1,40 @@
+*** Settings ***
+Documentation
+...  This resource file contains no keywords, but can be used to import
+...  the most common libraries used for writing browser tests that use
+...  the robotframework Browser library, based upon Playwright.
+...
+...  Note: when using this library, you cannot also use Salesforce.robot
+...  or Salesforce.py since those are based on Selenium rather than Playwright.
+...
+...  Libraries imported by this resource file:
+...
+...  - Browser
+...  - Collections
+...  - OperatingSystem
+...  - String
+...  - cumulusci.robotframework.CumulusCI
+...  - cumulusci.robotframework.SalesforcePlaywright
+...  - cumulusci.robotframework.SalesforceAPI
+...  - cumulusci.robotframework.Performance
+...
+...  This resource file also defines the following variables, which can all be
+...  overridden on the command line with the --vars option
+...
+...  | =Variable Name=          | = Default Value = |
+...  | ${DEFAULT BROWSER SIZE}  | 1280x1024         |
+...  | ${BROWSER}               | chrome            |
+
+*** Variables ***
+${DEFAULT BROWSER SIZE}  1280x1024
+${BROWSER}               chrome
+
+*** Settings ***
+Library        Browser  jsextension=${CURDIR}/javascript/cci_init.js
+Library        Collections
+Library        OperatingSystem
+Library        String
+Library        cumulusci.robotframework.CumulusCI  ${ORG}
+Library        cumulusci.robotframework.SalesforcePlaywright
+Library        cumulusci.robotframework.SalesforceAPI
+Library        cumulusci.robotframework.Performance

cumulusci/robotframework/__init__.py

@@ -0,0 +1,2 @@
+from .pageobjects import pageobject  # noqa: F401
+from .pageobjects import BasePage, PageObjects  # noqa: F401

cumulusci/robotframework/base_library.py

@@ -0,0 +1,39 @@
+from robot.libraries.BuiltIn import BuiltIn
+
+
+class BaseLibrary:
+    def __init__(self):
+        self._builtin = None
+        self._cumulusci = None
+        self._salesforce_api = None
+        self._salesforce = None
+
+    @property
+    def salesforce(self):
+        if getattr(self, "_salesforce", None) is None:
+            self._salesforce = self.builtin.get_library_instance(
+                "cumulusci.robotframework.Salesforce"
+            )
+        return self._salesforce
+
+    @property
+    def salesforce_api(self):
+        if getattr(self, "_salesforce_api", None) is None:
+            self._salesforce_api = self.builtin.get_library_instance(
+                "cumulusci.robotframework.SalesforceAPI"
+            )
+        return self._salesforce_api
+
+    @property
+    def builtin(self):
+        if getattr(self, "_builtin", None) is None:
+            self._builtin = BuiltIn()
+        return self._builtin
+
+    @property
+    def cumulusci(self):
+        if getattr(self, "_cumulusci", None) is None:
+            self._cumulusci = self.builtin.get_library_instance(
+                "cumulusci.robotframework.CumulusCI"
+            )
+        return self._cumulusci

cumulusci/robotframework/faker_mixin.py

@@ -0,0 +1,89 @@
+import faker
+from robot.libraries.BuiltIn import RobotNotRunningError
+
+
+class FakerMixin:
+    """Mixin class which provides support for the faker library"""
+
+    def __init__(self):
+        super().__init__()
+        self._faker = faker.Faker("en_US")
+        try:
+            self.builtin.set_global_variable("${faker}", self._faker)
+        except RobotNotRunningError:
+            # this only happens during unit tests, and we don't care.
+            pass
+
+    def set_faker_locale(self, locale):
+        """Set the locale for fake data
+
+        This sets the locale for all calls to the ``Faker`` keyword
+        and ``${faker}`` variable. The default is en_US
+
+        For a list of supported locales see
+        [https://faker.readthedocs.io/en/master/locales.html|Localized Providers]
+        in the Faker documentation.
+
+        Example
+
+        | Set Faker Locale    fr_FR
+        | ${french_address}=  Faker  address
+
+        """
+        try:
+            self._faker = faker.Faker(locale)
+        except AttributeError:
+            raise Exception(f"Unknown locale for fake data: '{locale}'")
+
+    def get_fake_data(self, fake, *args, **kwargs):
+        """Return fake data
+
+        This uses the [https://faker.readthedocs.io/en/master/|Faker]
+        library to provide fake data in a variety of formats (names,
+        addresses, credit card numbers, dates, phone numbers, etc) and
+        locales (en_US, fr_FR, etc).
+
+        The _fake_ argument is the name of a faker property such as
+        ``first_name``, ``address``, ``lorem``, etc. Additional
+        arguments depend on type of data requested. For a
+        comprehensive list of the types of fake data that can be
+        generated see
+        [https://faker.readthedocs.io/en/master/providers.html|Faker
+        providers] in the Faker documentation.
+
+        The return value is typically a string, though in some cases
+        some other type of object will be returned. For example, the
+        ``date_between`` fake returns a
+        [https://docs.python.org/3/library/datetime.html#date-objects|datetime.date
+        object]. Each time a piece of fake data is requested it will
+        be regenerated, so that multiple calls will usually return
+        different data.
+
+        This keyword can also be called using robot's extended variable
+        syntax using the variable ``${faker}``. In such a case, the
+        data being asked for is a method call and arguments must be
+        enclosed in parentheses and be quoted. Arguments should not be
+        quoted when using the keyword.
+
+        To generate fake data for a locale other than en_US, use
+        the keyword ``Set Faker Locale`` prior to calling this keyword.
+
+        Examples
+
+        | # Generate a fake first name
+        | ${first_name}=  Get fake data  first_name
+
+        | # Generate a fake date in the default format
+        | ${date}=  Get fake data  date
+
+        | # Generate a fake date with an explicit format
+        | ${date}=  Get fake data  date  pattern=%Y-%m-%d
+
+        | # Generate a fake date using extended variable syntax
+        | Input text  //input  ${faker.date(pattern='%Y-%m-%d')}
+
+        """
+        try:
+            return self._faker.format(fake, *args, **kwargs)
+        except AttributeError:
+            raise Exception(f"Unknown fake data request: '{fake}'")

cumulusci/robotframework/form_handlers.py

@@ -0,0 +1,222 @@
+import abc
+
+from robot.libraries.BuiltIn import BuiltIn
+from selenium.common.exceptions import TimeoutException
+
+from cumulusci.utils.classutils import get_all_subclasses
+
+"""
+FIXME: Something that still needs to be resolved is what to do about
+name clashes. What if a project imports two different libraries and
+each library implements a handler for the same tag and/or a handler
+for which a built-in handler already exists. How do we decide what
+takes precedence. Is this even something we have to worry about?
+
+So, the idea is to find an element, then do something like
+BaseFormHandler.get_handler(element, locator).set("foo")
+
+"""
+
+
+def get_form_handler(element, locator):
+    """Return an instance of handler for the given element
+
+    This will search all subclasses of BaseFormHandler, looking
+    for a class that supports the tag_name of the given element
+    """
+    tag = element.tag_name
+    for subclass in get_all_subclasses(BaseFormHandler):
+        if tag in subclass.tags:
+            # first one wins, but is that the right algorithm? Do
+            # we want to give precedence to external handlers
+            # over our built-in ones?
+            return subclass(element, locator)
+    return None
+
+
+class BaseFormHandler(abc.ABC):
+    """Base class for all form handlers
+
+    The goal is to have each handler implement the methods 'get',
+    'set', 'focus', and 'clear'. However, at present we're only using
+    'set' externally. 'focus' is the one method that will probably
+    have the same implementation for every handler so it's defined in
+    the base class. The others are abstract methods which each handler
+    should define.
+
+    """
+
+    def __init__(self, element, locator):
+        # concrete element to be handled
+        self.element = element
+
+        # the locator used to get the element, which we use for error
+        # handling.
+        self.locator = locator
+
+    @property
+    def selenium(self):
+        return BuiltIn().get_library_instance("SeleniumLibrary")
+
+    @property
+    def input_element(self):
+        """Returns the first <input> or <textarea> element inside the element"""
+        elements = self.element.find_elements_by_xpath(
+            ".//*[self::input or self::textarea]"
+        )
+        return elements[0] if elements else None
+
+    @abc.abstractmethod
+    def set(self, value):
+        pass
+
+    @abc.abstractmethod
+    def get(self):
+        pass
+
+    @abc.abstractmethod
+    def clear(self):
+        pass
+
+    def focus(self):
+        """Set focus to the element
+
+        In addition to merely setting the focus via selenium, we click
+        on the element in case there are functions tied to that event.
+        """
+        self.selenium.set_focus_to_element(self.element)
+        self.element.click()
+
+
+class HTMLInputHandler(BaseFormHandler):
+    """An input handler for non-lightning input and textarea form fields
+
+    This is the fallback handler for when we can't find a lightning component.
+    """
+
+    tags = ["input", "textarea"]
+
+    def set(self, value):
+        if self.element.get_attribute("type") == "checkbox":
+            value = value.lower()
+            checked = self.element.is_selected()
+            if (checked and value != "checked") or (not checked and value == "checked"):
+                self.element.click()
+
+        elif self.element.get_attribute("type") == "radio":
+            if value.strip().lower() != "selected":
+                raise Exception("value must be 'selected'")
+            self.element.send_keys(" ")
+
+        else:
+            self.clear()
+            self.element.send_keys(value)
+
+    def get(self, value):
+        # not currently being used
+        pass  # pragma: no cover
+
+    def clear(self):
+        # Salesforce.py has a crazy amount of code for clearing
+        # a field; for now these handlers seem to be working without it.
+        self.selenium.driver.execute_script("arguments[0].value = '';", self.element)
+
+
+class LightningComboboxHandler(BaseFormHandler):
+    """An input handler for comboboxes"""
+
+    tags = ["lightning-combobox"]
+
+    @property
+    def input_element(self):
+        """Returns the base form element (input or button) that the combobox is based on"""
+        elements = self.element.find_elements_by_xpath(
+            ".//*[contains(@class, 'slds-combobox__input')]"
+        )
+        return elements[0] if elements else None
+
+    def set(self, value):
+        value_locator = f'//lightning-base-combobox-item[.="{value}"]'
+        wait = 5
+        try:
+            # at this point, self.input_element is None
+            self.input_element.click()
+            self.selenium.wait_until_element_is_visible(value_locator, wait)
+            self.selenium.click_element(value_locator)
+        except Exception:
+            raise TimeoutException(
+                f"Dropdown value '{value}' for '{self.locator}' not found after {wait} seconds"
+            )
+
+    def get(self, value):
+        # not currently being used
+        pass  # pragma: no cover
+
+    def clear(self):
+        # not currently being used
+        pass  # pragma: no cover
+
+
+class LightningInputHandler(BaseFormHandler):
+    """An input handler for components that can be treated as an input or textarea"""
+
+    tags = [
+        "lightning-primitive-input-checkbox",
+        "lightning-primitive-input-simple",
+        "lightning-textarea",
+        "lightning-datepicker",
+    ]
+
+    def set(self, value):
+        self.focus()
+        if self.input_element.get_attribute("type") == "checkbox":
+            # lightning-input elements are used for checkboxes
+            # as well as free text input.
+            checked = self.element.get_attribute("checked")
+            if (checked and value != "checked") or (not checked and value == "checked"):
+                self.input_element.send_keys(" ")
+
+        elif self.input_element.get_attribute("type") == "radio":
+            if value.strip().lower() != "selected":
+                raise Exception("value must be 'selected'")
+            self.input_element.send_keys(" ")
+
+        else:
+            self.clear()
+            self.input_element.send_keys(value)
+
+    def get(self, value):
+        # not currently being used
+        pass  # pragma: no cover
+
+    def clear(self):
+        # Salesforce.py has a crazy amount of code for clearing
+        # a field; for now these handlers seem to be working without it.
+        self.selenium.driver.execute_script("arguments[0].value = '';", self.element)
+
+
+class LightningLookupHandler(BaseFormHandler):
+    tags = ["lightning-lookup", "lightning-grouped-combobox"]
+
+    def set(self, value):
+        wait = 10
+        # I wonder if I should/could anchor this to the element
+        # instead of searching the whole document?
+        value_locator = f'//lightning-base-combobox-formatted-text[@title="{value}"]'
+        self.element.click()
+        self.input_element.send_keys(value)
+        try:
+            self.selenium.wait_until_element_is_visible(value_locator, wait)
+            self.selenium.click_element(value_locator)
+        except Exception:
+            raise TimeoutException(
+                f"Lookup value '{value}' for '{self.locator}' not found after {wait} seconds"
+            )
+
+    def get(self, value):
+        # not currently being used
+        pass  # pragma: no cover
+
+    def clear(self):
+        # this is not currently being used
+        pass  # pragma: no cover

cumulusci/robotframework/javascript/cci_init.js

@@ -0,0 +1,34 @@
+/* This is passed to the Browser library via the jsextension
+   parameter when the library is imported.
+
+   This file will import all modules in the robot/<project
+   name>/javascript folder. The code in this file is dependent on an
+   environment variable named CCI_CONTEXT, which is initialized by the
+   robot task.
+*/
+
+const fs = require("fs");
+
+let cumulusci = require("cumulusci");
+let cci_context = JSON.parse(process.env.CCI_CONTEXT);
+cumulusci.project_config = cci_context.project_config;
+cumulusci.org = cci_context.org;
+
+// This is where each project should store their keywords.
+// Maybe in the future this should be configurable, but for
+// now it's not.
+let javascript_dir = `${cci_context.project_config.repo_root}/robot/${cci_context.project_config.repo_name}/javascript`;
+
+if (fs.existsSync(javascript_dir)) {
+    // Should I put this in a try/catch? If I don't, we get a slightly
+    // useful stacktrace in the log, though it's a python stacktrace
+    // rather than a javascript one.
+    exports.__esModule = true;
+    module.exports = {
+        ...require(javascript_dir),
+        ...require("cumulusci"),
+    };
+} else {
+    // this will show up in playwright-log.txt, alongside log.html
+    console.info(`no javascript keyword folder found: ${javascript_dir}`);
+}

cumulusci/robotframework/javascript/cumulusci.js

@@ -0,0 +1,4 @@
+// This structure will be filled in when SalesforcePlaywright.py is
+// loaded by the robot task
+module.exports = { project_config: {}, org: {} };
+exports.__esModule = true;