cumulusci-plus 5.0.0__py3-none-any.whl

cumulusci/robotframework/tests/test_template_util.py

@@ -0,0 +1,53 @@
+from cumulusci.core import template_utils
+
+
+class TestTemplateUtils:
+    def test_string_generator(self):
+        x = 100
+        y = template_utils.StringGenerator(lambda: str(x))
+        assert str(y) == "100"
+        x = 200
+        assert str(y) == "200"
+
+    def test_faker_library(self):
+        fake = template_utils.FakerTemplateLibrary()
+        assert fake.first_name
+        assert "example.com" in fake.email(domain="example.com")
+
+    def test_faker_languages(self):
+        fake = template_utils.FakerTemplateLibrary("no_NO")
+        assert fake.first_name
+        assert "example.com" in fake.email(domain="example.com")
+
+    def test_format_str(self):
+        assert template_utils.format_str("abc") == "abc"
+        assert template_utils.format_str("{{abc}}", {"abc": 5}) == "5"
+        assert len(template_utils.format_str("{{fake.first_name}}"))
+        assert "15" in template_utils.format_str(
+            "{{fake.first_name}} {{count}}", {"count": 15}
+        )
+        assert "15" in template_utils.format_str(
+            "{{fake.first_name}} {{count}}", {"count": "15"}
+        )
+        assert (
+            template_utils.format_str("{% raw %}{}{% endraw %}", {"count": "15"})
+            == "{}"
+        )
+
+    def test_format_str_languages(self):
+        norwegian_faker = template_utils.FakerTemplateLibrary("no_NO")
+
+        val = template_utils.format_str(
+            "{{vikingfake.first_name}} {{abc}}",
+            {"abc": 5, "vikingfake": norwegian_faker},
+        )
+        assert "5" in val
+
+        def cosmopolitan_faker(language):
+            return template_utils.FakerTemplateLibrary(language)
+
+        val = template_utils.format_str(
+            "{{fakei18n('ne_NP').first_name}} {{abc}}",
+            {"abc": 5, "fakei18n": cosmopolitan_faker, "type": type},
+        )
+        assert "5" in val

cumulusci/robotframework/tests/test_utils.py

@@ -0,0 +1,106 @@
+import shutil
+import tempfile
+from pathlib import Path
+from unittest import mock
+
+import cumulusci.robotframework.utils as robot_utils
+from cumulusci.utils import touch
+
+mock_SeleniumLibrary = mock.Mock()
+
+
+class MockBuiltIn:
+    get_library_instance = mock.Mock(
+        return_value={"SeleniumLibrary": mock_SeleniumLibrary}
+    )
+
+
+robot_utils.BuiltIn = MockBuiltIn
+
+
+class TestRobotframeworkUtils:
+    def setup_method(self):
+        mock_SeleniumLibrary.reset_mock()
+
+    def test_screenshot_decorator_return(self):
+        """Verify that the decorator will return what the decorated function returns"""
+
+        @robot_utils.capture_screenshot_on_error
+        def example_function():
+            return "the return value"
+
+        result = example_function()
+
+        mock_SeleniumLibrary.capture_page_screenshot.assert_not_called()
+        assert result == "the return value"
+
+    def test_screenshot_decorator_fail(self):
+        """Verify that the decorator will capture a screenshot on keyword failure"""
+
+        @robot_utils.capture_screenshot_on_error
+        def example_function():
+            raise Exception("Danger Will Robinson!")
+
+        try:
+            example_function()
+        except Exception:
+            pass
+        mock_SeleniumLibrary.capture_page_screenshot.assert_called_once()
+
+    def test_screenshot_decorator_pass(self):
+        """Verify that decorator does NOT capture screenshot on keyword success"""
+
+        @robot_utils.capture_screenshot_on_error
+        def example_function():
+            return True
+
+        example_function()
+
+        mock_SeleniumLibrary.capture_page_screenshot.assert_not_called()
+
+
+class TestGetLocatorModule:
+    @classmethod
+    def setup_class(cls):
+        # get_locator_module uses __file__ to locate the locator
+        # module. We'll point it to a temporary directory so that
+        # we can control what files we test against.
+
+        cls.tempdir = Path(tempfile.mkdtemp())
+        # sorted alphabetically, 5 should come after 40. The
+        # code should be sorting numerically so that 5 comes
+        # before 40. That's why "locators_5.py" is here.
+        touch(Path(cls.tempdir, "locators_5.py"))
+        touch(Path(cls.tempdir, "locators_39.py"))
+        touch(Path(cls.tempdir, "locators_40.py"))
+
+        dunder_file = Path(cls.tempdir, "utils.py").absolute()
+        cls.patched_utils = mock.patch.object(robot_utils, "__file__", dunder_file)
+        cls.patched_utils.start()
+
+    @classmethod
+    def teardown_class(cls):
+        shutil.rmtree(cls.tempdir)
+        cls.patched_utils.stop()
+
+    def test_get_locator_module_name_no_version(self):
+        """Verify that we get the latest version if we don't have a version number"""
+        module_name = robot_utils.get_locator_module_name(None)
+        assert module_name == "cumulusci.robotframework.locators_40"
+
+    def test_get_locator_module_name_specific_version(self):
+        """Verify that we get the specific version we ask for"""
+        for version in (5, 39, 40):
+            actual_module_name = robot_utils.get_locator_module_name(version)
+            expected_module_name = f"cumulusci.robotframework.locators_{version}"
+            assert expected_module_name == actual_module_name
+
+    def test_get_locator_module_name_version_too_low(self):
+        """Verify that we get the latest version if version specified isn't supported"""
+        module_name = robot_utils.get_locator_module_name(37)
+        assert module_name == "cumulusci.robotframework.locators_40"
+
+    def test_get_locator_module_name_version_too_high(self):
+        """Verify that we get the latest version if version specified isn't supported"""
+        module_name = robot_utils.get_locator_module_name(41)
+        assert module_name == "cumulusci.robotframework.locators_40"

cumulusci/robotframework/utils.py

@@ -0,0 +1,283 @@
+import functools
+import re
+import time
+from pathlib import Path
+
+import robot.api as robot_api
+from robot.libraries.BuiltIn import BuiltIn
+from selenium.common.exceptions import (
+    ElementNotInteractableException,
+    NoSuchWindowException,
+    StaleElementReferenceException,
+    WebDriverException,
+)
+from selenium.webdriver.remote.command import Command
+from SeleniumLibrary.errors import ElementNotFound
+
+
+def set_pdb_trace(pm=False):  # pragma: no cover
+    """Start the Python debugger when robotframework is running.
+
+    This makes sure that pdb can use stdin/stdout even though
+    robotframework has redirected I/O.
+    """
+    import pdb
+    import sys
+
+    for attr in ("stdin", "stdout", "stderr"):
+        setattr(sys, attr, getattr(sys, "__%s__" % attr))
+    if pm:
+        # Post-mortem debugging of an exception
+        pdb.post_mortem()
+    else:
+        pdb.set_trace()
+
+
+# This is a list of user actions that are likely to trigger
+# Aura actions and/or XHRs. We'll add a step to wait for
+# in-flight XHRs to complete after these commands.
+COMMANDS_INVOKING_ACTIONS = {Command.CLICK_ELEMENT}
+
+
+# This script waits for a) Aura to be available and b)
+# any in-flight Aura XHRs to be complete.
+# We only do this if the page uses Aura, as determined by looking for
+# id="auraAppcacheProgress" in the DOM.
+# It would be nice if we could inject the function when the page loads
+# and then just call it after commands, but I was having trouble
+# getting webdriver to add it to the window scope.
+WAIT_FOR_AURA_SCRIPT = """
+done = arguments[0];
+if (document.getElementById('auraAppcacheProgress')) {
+    var waitForXHRs = function() {
+        if (window.$A && !window.$A.clientService.inFlightXHRs()) {
+            done();
+        } else {
+            setTimeout(waitForXHRs, 100);
+        }
+    }
+    setTimeout(waitForXHRs, 0);
+} else {
+    done();
+}
+"""
+
+
+ALWAYS_RETRY_EXCEPTIONS = (
+    ElementNotFound,
+    ElementNotInteractableException,
+    StaleElementReferenceException,
+    NoSuchWindowException,
+)
+
+
+class RetryingSeleniumLibraryMixin(object):
+
+    debug = False
+
+    @property
+    def selenium(self):
+        selenium = self.builtin.get_library_instance("SeleniumLibrary")
+
+        # Patch the selenium webdriver to add our own functionality
+        # to improve stability.
+        if not getattr(selenium.driver, "_cumulus_patched", False):
+            orig_execute = selenium.driver.execute
+
+            def execute(driver_command, params=None):
+                try:
+                    if self.retry_selenium:
+                        # Retry certain failed commands once
+                        result = self.selenium_execute_with_retry(
+                            orig_execute, driver_command, params
+                        )
+                    else:
+                        result = orig_execute(driver_command, params)
+                except Exception:
+                    if driver_command != Command.SCREENSHOT:
+                        safe_screenshot()
+                    if self.debug:
+                        self.selenium.log_source()
+                    raise
+
+                # Run the "wait for aura" script after commands that are
+                # likely to invoke async actions.
+                if driver_command in COMMANDS_INVOKING_ACTIONS:
+                    self.wait_for_aura()
+                return result
+
+            selenium.driver.execute = execute
+            selenium.driver._cumulus_patched = True
+
+        return selenium
+
+    def selenium_execute_with_retry(self, execute, command, params):
+        """Run a single selenium command and retry once.
+
+        The retry happens for certain errors that are likely to be resolved
+        by retrying.
+        """
+        try:
+            return execute(command, params)
+        except Exception as e:
+            if isinstance(e, ALWAYS_RETRY_EXCEPTIONS) or (
+                isinstance(e, WebDriverException)
+                and "Other element would receive the click" in str(e)
+            ):
+                # Retry
+                self.builtin.log("Retrying {} command".format(command), level="WARN")
+                time.sleep(2)
+                return execute(command, params)
+            else:
+                raise
+
+    def wait_for_aura(self):
+        """Run the WAIT_FOR_AURA_SCRIPT.
+
+        This script polls Aura via $A in Javascript to determine when
+        all in-flight XHTTP requests have completed before continuing.
+        """
+        try:
+            self.selenium.driver.execute_async_script(WAIT_FOR_AURA_SCRIPT)
+        except Exception:
+            pass
+
+
+def selenium_retry(target=None, retry=True):
+    """Decorator to turn on automatic retries of flaky selenium failures.
+
+    Decorate a robotframework library class to turn on retries for all
+    selenium calls from that library::
+
+        @selenium_retry
+        class MyLibrary(object):
+
+            # Decorate a method to turn it back off for that method
+            @selenium_retry(False)
+            def some_keyword(self):
+                self.selenium.click_button('foo')
+
+    Or turn it off by default but turn it on for some methods
+    (the class-level decorator is still required)::
+
+        @selenium_retry(False)
+        class MyLibrary(object):
+
+            @selenium_retry(True)
+            def some_keyword(self):
+                self.selenium.click_button('foo')
+    """
+
+    if isinstance(target, bool):
+        # Decorator was called with a single boolean argument
+        retry = target
+        target = None
+
+    def decorate(target):
+        if isinstance(target, type):
+            cls = target
+            # Metaclass time.
+            # We're going to generate a new subclass that:
+            # a) mixes in RetryingSeleniumLibraryMixin
+            # b) sets the initial value of `retry_selenium`
+            return type(
+                cls.__name__,
+                (cls, RetryingSeleniumLibraryMixin),
+                {"retry_selenium": retry, "__doc__": cls.__doc__},
+            )
+        func = target
+
+        @functools.wraps(func)
+        def run_with_retry(self, *args, **kwargs):
+            # Set the retry setting and run the original function.
+            old_retry = self.retry_selenium
+            self.retry = retry
+            try:
+                return func(self, *args, **kwargs)
+            finally:
+                # Restore the previous value
+                self.retry_selenium = old_retry
+
+        run_with_retry.is_selenium_retry_decorator = True
+        return run_with_retry
+
+    if target is None:
+        # Decorator is being used with arguments
+        return decorate
+    else:
+        # Decorator was used without arguments
+        return decorate(target)
+
+
+def capture_screenshot_on_error(func):
+    """Decorator for capturing a screenshot if a keyword throws an error
+
+    This decorator will work for both SeleniumLibrary and Browser.
+
+    If a screenshot cannot be taken for any reason, the screenshot error
+    will be logged before the original exception is re-raised.
+
+    For keywords using the Browser library, this will call the keyword
+    "Take screenshot".
+
+    For keywords using SeleniumLibrary, this decorator will call whatever
+    keyword SeleniumLibrary is configured to call on failure. Normally
+    that will be "Capture page screenshot".
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except Exception:
+            safe_screenshot()
+            raise
+
+    return wrapper
+
+
+def safe_screenshot():
+    """Take a screenshot, but log and then ignore errors if the screenshot fails
+
+    This function should work for both selenium and browser (playwright) libraries
+    """
+
+    libs = BuiltIn().get_library_instance(all=True)
+    try:
+        if "Browser" in libs:
+            libs["Browser"].take_screenshot()
+        elif "SeleniumLibrary" in libs:
+            libs["SeleniumLibrary"].capture_page_screenshot()
+    except Exception as e:
+        BuiltIn().log(f"unable to capture screenshot: {e}")
+
+
+def get_locator_module_name(version):
+    """Return module name of locator file for the specified version
+
+    If a file for the specified version can't be found, the locator
+    file with the highest number will be returned. Passing in None
+    effectively means "give me the latest version".
+    """
+
+    here = Path(__file__).parent
+    if Path(here, f"locators_{version}.py").exists():
+        # our work here is done.
+        locator_name = f"locators_{version}"
+    else:
+
+        def by_num(filename):
+            """Pull out the number from a filename, or return zero"""
+            nums = re.findall(r"_(\d+)", str(filename))
+            if nums:
+                return int(nums[-1])
+            return 0
+
+        files = sorted(here.glob("locators_*.py"), key=by_num)
+        locator_name = files[-1].stem
+        robot_api.logger.warn(
+            f"Locators for api {version} not found. Falling back to {locator_name} for salesforce locators"
+        )
+
+    locator_module_name = f"cumulusci.robotframework.{locator_name}"
+    return locator_module_name

cumulusci/salesforce_api/exceptions.py

@@ -0,0 +1,23 @@
+from cumulusci.core.exceptions import CumulusCIException, CumulusCIFailure
+
+
+class MetadataApiError(CumulusCIFailure):
+    def __init__(self, message, response):
+        super(MetadataApiError, self).__init__(message)
+        self.response = response
+
+
+class MetadataComponentFailure(MetadataApiError):
+    pass
+
+
+class MetadataParseError(MetadataApiError):
+    pass
+
+
+class MissingOAuthError(CumulusCIException):
+    pass
+
+
+class MissingOrgCredentialsError(CumulusCIException):
+    pass

cumulusci/salesforce_api/filterable_objects.py

@@ -0,0 +1,96 @@
+# discovered by trial and error. Usually extended with a list of
+# tooling objects. i.e. any object which is both a tooling object
+# and also a "regular" sobject will be skipped.
+OPT_IN_ONLY = [
+    "ApexClass",
+    "ApexTrigger",
+    "FeedItem",
+    "Translation",
+    "WebLinkLocalization",
+    "RecordTypeLocalization",
+    "RecordType",
+    "BrandTemplate",
+]
+
+NOT_COUNTABLE = (
+    "ContentDocumentLink",  # ContentDocumentLink requires a filter by a single Id on ContentDocumentId or LinkedEntityId
+    "ContentFolderItem",  # Implementation restriction: ContentFolderItem requires a filter by Id or ParentContentFolderId
+    "ContentFolder",  # Similar to above
+    "ContentFolderLink",  # Similar to above
+    "ContentFolderMember",  # Similar to above
+    "IdeaComment",  # you must filter using the following syntax: CommunityId = [single ID],
+    "Vote",  # you must filter using the following syntax: ParentId = [single ID],
+    "RecordActionHistory",  # Gack: 1133111327-118855 (1126216936)
+    "DashboardSnapshotResults",  # Gack: 1198622208-46932 (1126216936)
+    "RecordRecommendation",  # Implementation restriction: RecordRecommendation requires a filter on TargetSobjectType or TargetId or RecordRecommendationId
+)
+
+
+NOT_EXTRACTABLE = NOT_COUNTABLE + (
+    "%Share",
+    "%Access",
+    "%History",
+    "%Permission",
+    "%PermissionSet",
+    "%Permissions",
+    "AuthorizationFormDataUse",
+    "CustomHelpMenuSection",
+    "DataUseLegalBasis",
+    "DataUsePurpose",
+    "ExternalDataUserAuth",
+    "FieldPermissions",
+    "Group",
+    "GroupMember",
+    "PermissionSet",
+    "PermissionSetAssignment",
+    "PermissionSetGroup",
+    "PermissionSetGroupComponent",
+    "PermissionSetLicenseAssign",
+    "PermissionSetTabSetting",
+    "Profile",
+    "RecordType",
+    "User",
+    "UserAppInfo",
+    "UserAppMenuCustomization",
+    "UserCustomBadge",
+    "UserCustomBadgeLocalization",
+    "UserEmailPreferredPerson",
+    "UserListView",
+    "UserListViewCriterion",
+    "UserPackageLicense",
+    "UserPreference",
+    "UserProvAccount",
+    "UserProvAccountStaging",
+    "UserProvMockTarget",
+    "UserProvisioningConfig",
+    "UserProvisioningLog",
+    "UserProvisioningRequest",
+    "UserRole",
+)
+
+# Generated with these patterns:
+#     "%permission%",
+#     "%use%",
+#     "%access%",
+#     "group",
+#     "%share",
+#     "NetworkUserHistoryRecent",
+#     "ObjectPermissions",
+#     "OmniSupervisorConfigUser",
+#     "OutgoingEmail",
+#     "OutgoingEmailRelation",
+# )
+
+# And this code:
+#
+# patterns_to_ignore = NOT_EXTRACTABLE_WITHOUT_NOT_COUNTABLE
+
+# names = [obj["name"] for obj in sf.describe()["sobjects"] if obj["createable"]]
+
+# regexps_to_ignore = [
+#     re.compile(pat.replace("%", ".*"), re.IGNORECASE) for pat in patterns_to_ignore
+# ]
+
+# for name in names:
+#     if any(reg.match(name) for reg in regexps_to_ignore) and not ("__" in name):
+#         print(name)

cumulusci/salesforce_api/mc_soap_envelopes.py

@@ -0,0 +1,89 @@
+CREATE_SUBSCRIBER_ATTRIBUTE = """<?xml version="1.0" encoding="utf-8"?>
+<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
+<s:Header>
+  <a:Action s:mustUnderstand="1">Configure</a:Action>
+  <a:To s:mustUnderstand="1">{soap_instance_url}Service.asmx</a:To>
+  <fueloauth>{access_token}</fueloauth>
+</s:Header>
+<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+  <ConfigureRequestMsg xmlns="http://exacttarget.com/wsdl/partnerAPI">
+    <Options></Options>
+    <Action>Create</Action>
+    <Configurations>
+      <Configuration xsi:type="PropertyDefinition">
+        <PartnerKey xsi:nil="true"></PartnerKey>
+        <ObjectID xsi:nil="true"></ObjectID>
+        <Name>{attribute_name}</Name>
+        <PropertyType>string</PropertyType>
+      </Configuration>
+    </Configurations>
+  </ConfigureRequestMsg>
+</s:Body>
+</s:Envelope>"""
+
+CREATE_USER = """<?xml version="1.0" encoding="utf-8"?>
+<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
+    <s:Header>
+        <a:Action s:mustUnderstand="1">Create</a:Action>
+        <a:To s:mustUnderstand="1">{soap_instance_url}Service.asmx</a:To>
+        <fueloauth>{access_token}</fueloauth>
+    </s:Header>
+    <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+        <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
+            <Objects xsi:type="AccountUser">
+                <ObjectID xsi:nil="true"></ObjectID>
+                <!-- REQUIRED: specify the MID for Parent BU -->
+                <Client>
+                    <ID>{parent_bu_mid}</ID>
+                </Client>
+                <!-- REQUIRED: Set MID for BU to use as default (can be same as the parent) -->
+                <DefaultBusinessUnit>{default_bu_mid}</DefaultBusinessUnit>
+                <!-- Set external key for user -->
+                {external_key}
+                <!-- Set name of user -->
+                {user_name}
+                <!-- REQUIRED: Set the user email -->
+                <Email>{user_email}</Email>
+                <NotificationEmailAddress>{user_email}</NotificationEmailAddress>
+                <!-- REQUIRED: Set the user password -->
+                <Password>{user_password}</Password>
+                <!-- REQUIRED: Set the username -->
+                <UserID>{user_username}</UserID>
+                <IsAPIUser>true</IsAPIUser>
+                {active_flag}
+                <IsLocked>false</IsLocked>
+                <!-- OPTIONAL: Include this if you want to assign roles to new user -->
+                <!-- IDs for system defined roles located here: https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/setting_user_permissions_via_the_web_services_api.htm -->
+                {role_id}
+            </Objects>
+        </CreateRequest>
+    </s:Body>
+</s:Envelope>"""
+
+UPDATE_USER_ROLE = """<?xml version="1.0" encoding="utf-8"?>
+<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
+    <s:Header>
+        <a:Action s:mustUnderstand="1">Create</a:Action>
+        <a:To s:mustUnderstand="1">{soap_instance_url}Service.asmx</a:To>
+        <fueloauth>{access_token}</fueloauth>
+    </s:Header>
+    <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+        <UpdateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
+            <Objects xsi:type="AccountUser">
+                <ObjectID xsi:nil="true"></ObjectID>
+                <Client>
+                    <ID>{account_mid}</ID> <!-- Account MID -->
+                </Client>
+                {external_key} <!-- External key for user to update -->
+                <IsAPIUser>true</IsAPIUser>
+                {user_name}
+                <Email>{user_email}</Email>
+                <Password>{user_password}</Password>
+                <!-- IDs for system defined roles located here: https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/setting_user_permissions_via_the_web_services_api.htm -->
+                <UserPermissions>
+                    <ID>{role_id}</ID>
+                </UserPermissions>
+            </Objects>
+        </UpdateRequest>
+    </s:Body>
+</s:Envelope>"""