cumulusci-plus 5.0.0__py3-none-any.whl

cumulusci/robotframework/pageobjects/PageObjectLibrary.py

@@ -0,0 +1,45 @@
+import inspect
+
+
+class _PageObjectLibrary(object):
+    """
+    This uses robot's hybrid library API to create a keyword library
+    from any object. All of the methods in the object will be exposed
+    as keywords, except for a method named 'get_keyword_names'
+
+    For example, the following code will create an instance of this class
+    with the _obj parameter set to the instance of SomeKeywordClass():
+
+        keywords = SomeKeywordClass()
+        BuiltIn().import_library("PageObjectLibrary", keywords)
+
+    This isn't designed to be called from test suites. It's for internal
+    use only.
+    """
+
+    ROBOT_LIBRARY_SCOPE = "TEST SUITE"
+
+    def __init__(self, obj, libname=None):
+        self._obj = obj
+        self._libname = libname if libname is not None else obj.__class__.__name__
+
+        self._keyword_names = sorted(
+            [
+                member[0]
+                for member in inspect.getmembers(obj, inspect.isroutine)
+                if (not member[0].startswith("_")) and member[0] != "get_keyword_names"
+            ]
+        )
+
+    def get_keyword_names(self):
+        return self._keyword_names
+
+    def __repr__(self):
+        return "<{} obj={}>".format(
+            self.__class__.__name__, self._obj.__class__.__name__
+        )
+
+    def __getattr__(self, item):
+        if hasattr(self._obj, item):
+            return getattr(self._obj, item)
+        raise AttributeError(item)

cumulusci/robotframework/pageobjects/PageObjects.py

@@ -0,0 +1,351 @@
+import inspect
+import sys
+from pathlib import Path
+
+import robot.utils
+from robot.api import logger
+from robot.libraries.BuiltIn import BuiltIn, RobotNotRunningError
+
+from cumulusci.robotframework.pageobjects.baseobjects import BasePage
+from cumulusci.robotframework.utils import capture_screenshot_on_error
+
+
+def get_keyword_names(obj):
+    """Returns a list of method names for the given object
+
+    This excludes methods that begin with an underscore, and
+    also excludes the special method `get_keyword_names`.
+    """
+    names = [
+        member[0]
+        for member in inspect.getmembers(obj, inspect.isroutine)
+        if (not member[0].startswith("_")) and member[0] != "get_keyword_names"
+    ]
+    return names
+
+
+def pageobject(page_type, object_name=None):
+    """A decorator to designate a class as a page object"""
+    BuiltIn().log("importing page object {} {}".format(page_type, object_name), "DEBUG")
+
+    def wrapper(cls):
+        key = (page_type, object_name if object_name else "")
+        PageObjects.registry[key] = cls
+        cls._page_type = page_type
+        if getattr(cls, "_object_name", None) is None:
+            cls._object_name = object_name
+        else:
+            # this page object uses an alias for the object (ie: the name
+            # and _object_name do not match). Let's add this object name
+            # into the registry so it can be called with either the alias
+            # or the actual object name
+            alias_key = (page_type, cls._object_name)
+            PageObjects.registry[alias_key] = cls
+        return cls
+
+    return wrapper
+
+
+class PageObjects(object):
+    """Keyword library for importing and using page objects
+
+    When importing, you can include one or more paths to python
+    files that define page objects. For example, if you have a set
+    of classes in robot/HEDA/resources/PageObjects.py, you can import
+    this library into a test case like this:
+
+    | Library  cumulusci.robotframework.PageObjects
+    | ...  robot/HEDA/resources/PageObjects.py
+
+    Page object classes need to use the @pageobject decorator from
+    cumulusci.robotframework.pageobjects. The decorator takes two
+    parameters: page_type and object_name. Both are arbitrary strings,
+    but together should uniquely identify a collection of keywords for
+    a page or objects on a page.
+
+    Examples of page_type are Listing, Home, Detail, etc. Object types
+    can be actual object types (Contact), custom object
+    (Custom_object__c) or a logical name for a type of page (eg:
+    AppointmentManager).
+
+    Example:
+
+    | from cumulusci.robotframework.pageobjects import BasePage
+    | from cumulusci.robotframework.pageobjects import pageobject
+    | ...
+    | @pageobject(page_type="Detail", object_name="Custom__c")
+    | class CustomDetailPage(BasePage):
+    |     ...
+    """
+
+    ROBOT_LIBRARY_SCOPE = "TEST SUITE"
+    registry = {}
+
+    def __init__(self, *args):
+        self.builtin = BuiltIn()
+        logger.debug("initializing PageObjects...")
+        importer = robot.utils.Importer()
+
+        for file_path in args:
+            path = self._find_file_in_pythonpath(file_path)
+            if path:
+                try:
+                    importer.import_class_or_module_by_path(str(path.resolve()))
+                    logger.debug(f"imported page object from {path}")
+                except Exception as e:
+                    raise ImportError(
+                        f"Unable to import page object '{file_path}': ({e})", path=path
+                    )
+
+            else:
+                raise ImportError(f"Unable to find page object file '{file_path}'")
+
+        self.current_page_object = None
+
+        # Start with this library at the front of the library search order;
+        # that may change as page objects are loaded.
+        try:
+            self.builtin.set_library_search_order("PageObjects")
+        except RobotNotRunningError:
+            # this should only happen when trying to load this library
+            # via the robot_libdoc task, in which case we don't care
+            # whether this throws an error or not.
+            pass
+
+    def _find_file_in_pythonpath(self, filename):
+        for directory in sys.path:
+            path = Path(directory) / filename
+            if path.exists():
+                return path
+        return None
+
+    @classmethod
+    def _reset(cls):
+        """Reset the internal data structures used to manage page objects
+
+        This is to aid testing. It probably shouldn't be used at any other time.
+        """
+        for pobj in cls.registry.values():
+            if pobj.__module__ in sys.modules:
+                del sys.modules[pobj.__module__]
+        cls.registry = {}
+
+    @property
+    def selenium(self):
+        return self.builtin.get_library_instance("SeleniumLibrary")
+
+    def __getattr__(self, name):
+        """Return the keyword from the current page object
+
+        This method is required by robot's dynamic library api
+        """
+        if self.current_page_object is None:
+            raise AttributeError(name)
+        return getattr(self.current_page_object, name)
+
+    def get_keyword_names(self):
+        """
+        This method is required by robot's dynamic library api
+        """
+        names = get_keyword_names(self)
+        if self.current_page_object is not None:
+            names = names + get_keyword_names(self.current_page_object)
+        return names
+
+    def log_page_object_keywords(self):
+        """Logs page objects and their keywords for all page objects
+        which have been imported into the current suite.
+        """
+        for key in sorted(self.registry.keys()):
+            pobj = self.registry[key]
+            keywords = get_keyword_names(pobj)
+            logger.info("{}: {}".format(key, ", ".join(keywords)))
+
+    def get_page_object(self, page_type, object_name):
+        """Return an instance of a page object
+
+        This is useful if you want to call a single page object method
+        from some other keyword without having to go to another page
+        or load the page object into a page.
+
+        This works a lot like robot's built-in "get library instance"
+        keyword, but you can specify the page object by page type
+        and object name rather than the library name, and it will
+        autoload the appropriate library (assuming its module has
+        been imported).
+        """
+
+        if (page_type, object_name) in self.registry:
+            cls = self.registry[(page_type, object_name)]
+            logger.debug(f"using page object class {cls}")
+            instance = cls()
+            instance._libname = instance.__class__.__name__
+
+        else:
+            # Page object has not been registered. Try to find
+            # an appropriate generic class. For example, if
+            # the requested page is "Listing", "Contact", look
+            # for a "ListingPage" class. If we find it, we'll
+            # create a library named "ContactListingPage"
+            instance = None
+            for subclass in BasePage.__subclasses__():
+                if getattr(subclass, "_page_type", None) == page_type:
+                    instance = subclass(object_name)
+                    instance._libname = "{}{}Page".format(
+                        object_name, page_type
+                    )  # eg: ContactListingPageObject
+                    break
+
+            if instance is None:
+                raise Exception(
+                    "Unable to find a page object for '{} {}'".format(
+                        page_type, object_name
+                    )
+                )
+
+        try:
+            pobj = self.builtin.get_library_instance(instance._libname)
+
+        except Exception:
+            # Hasn't been imported. Attempt to import it with the given name
+            # for the given object; If this fails, just let it bubble up
+            # because there's nothing else we can do.
+            self.builtin.import_library(
+                "cumulusci.robotframework.pageobjects._PageObjectLibrary",
+                instance,
+                instance._libname,
+                "WITH NAME",
+                instance._libname,
+            )
+            # sure would be nice if import_library returned the instance. Just sayin'.
+            pobj = self.builtin.get_library_instance(instance._libname)
+
+        return pobj
+
+    @capture_screenshot_on_error
+    def go_to_page(self, page_type, object_name, *args, **kwargs):
+        """Go to the page of the given page object.
+
+        The URL will be computed from the page_type and object_name
+        associated with the object, plus possibly additional arguments.
+
+        Different pages support different additional arguments. For
+        example, a Listing page supports the keyword argument `filter_name`,
+        and a Detail page can be given an object id, or parameters for
+        looking up the object id.
+
+        If this keyword is able to navigate to a page, the keyword
+        `load page object` will automatically be called to load the keywords
+        for the page.
+
+        Custom page objects may define the function `_go_to_page`,
+        which will be passed in all of the keyword arguments from this
+        keyword. This allows each page object to define its own URL
+        mapping using whatever algorithm it chooses.  The only
+        requirement of the function is that it should compute an
+        appropriate url and then call `self.selenium.go_to` with the
+        URL.
+
+        It is also recommended that the keyword wait until it knows
+        that the page has finished rendering before returning (eg: by
+        calling `self.salesforce.wait_until_loading_is_complete()`)
+        """
+        pobj = self.get_page_object(page_type, object_name)
+        pobj._go_to_page(*args, **kwargs)
+        self._set_current_page_object(pobj)
+
+    @capture_screenshot_on_error
+    def current_page_should_be(self, page_type, object_name, **kwargs):
+        """Verifies that the page appears to be the requested page
+
+        If the page matches the given page object or contains the
+        given page object, the keyword will pass.a
+
+        When this keyword is called, it will try to get the page
+        object for the given page_tyope and object_name, and call the
+        method `_is_current_page`.
+
+        Custom page objects may define this function in whatever
+        manner is necessary to determine that the current page is or
+        contains the given page object. The only requirement is that
+        this function raise an exception if it determines the current
+        page either doesn't represent the page object or doesn't
+        contain the page object.
+
+        The default implementation of the function uses the page URL
+        and compares it to a pattern based off of the page_type and
+        object_name.
+
+        """
+        pobj = self.get_page_object(page_type, object_name)
+        pobj._is_current_page(**kwargs)
+        self.load_page_object(page_type, object_name)
+
+    def load_page_object(self, page_type, object_name=None):
+        """Load the keywords for the page object identified by the type and object name
+
+        The page type / object name pair must have been registered
+        using the cumulusci.robotframework.pageobject decorator.
+        """
+        pobj = self.get_page_object(page_type, object_name)
+        self._set_current_page_object(pobj)
+        return pobj
+
+    @capture_screenshot_on_error
+    def wait_for_modal(self, page_type, object_name, expected_heading=None, **kwargs):
+        """Wait for the given page object modal to appear.
+
+        This will wait for modal to appear. If an expected heading
+        is provided, it will also validate that the modal has the
+        expected heading.
+
+        Example:
+
+        | Wait for modal to appear    New    Contact   expected_heading=New Contact
+
+        """
+        pobj = self.get_page_object(page_type, object_name)
+        pobj._wait_to_appear(expected_heading=expected_heading)
+        self._set_current_page_object(pobj)
+        # Ideally we would wait for something, but I can't figure out
+        # what that would be. A knowledge article simply suggests
+        # to wait a second.
+        # https://help.salesforce.com/articleView?id=000352057&language=en_US&mode=1&type=1
+
+        self.builtin.sleep("1 second")
+        return pobj
+
+    @capture_screenshot_on_error
+    def wait_for_page_object(self, page_type, object_name, **kwargs):
+        """Wait for an element represented by a page object to appear on the page.
+
+        The associated page object will be loaded after the element appears.
+
+        page_type represents the page type (Home, Details, etc)) and
+        object_name represents the name of an object (Contact,
+        Organization, etc)
+
+        """
+        pobj = self.get_page_object(page_type, object_name)
+        pobj._wait_to_appear()
+        self._set_current_page_object(pobj)
+        return pobj
+
+    def _set_current_page_object(self, pobj):
+        """This does the work of importing the keywords for the given page object
+
+        Multiple page objects may be loaded. Each page object will be added
+        to the front of robot's library search order. Note: this search order
+        gets reset at the start of every suite.
+        """
+
+        self.current_page_object = pobj
+        libname = pobj._libname
+
+        old_order = list(self.builtin.set_library_search_order())
+        if libname in old_order:
+            old_order.remove(libname)
+        new_order = [libname] + old_order
+        self.builtin.log("new search order: {}".format(new_order), "DEBUG")
+        self.builtin.set_library_search_order(*new_order)
+        return pobj

cumulusci/robotframework/pageobjects/__init__.py

@@ -0,0 +1,12 @@
+from .PageObjects import PageObjects  # noqa: F401
+from .baseobjects import BasePage  # noqa: F401
+from .PageObjectLibrary import _PageObjectLibrary  # noqa: F401
+from .PageObjects import pageobject  # noqa: F401
+from .BasePageObjects import (  # noqa: F401
+    ListingPage,
+    HomePage,
+    DetailPage,
+    NewModal,
+    EditModal,
+)
+from .ObjectManagerPageObject import ObjectManagerPage  # noqa: F401

cumulusci/robotframework/pageobjects/baseobjects.py

@@ -0,0 +1,120 @@
+from contextlib import contextmanager
+
+from cumulusci.robotframework.base_library import BaseLibrary
+
+
+class BasePage(BaseLibrary):
+    _object_name = None
+
+    def __init__(self, object_name=None):
+        super().__init__()
+        if object_name:
+            self._object_name = object_name
+
+    @contextmanager
+    def _no_implicit_wait(self):
+        """Context manager for running selenium commands without an implicit wait"""
+        current_wait = self.selenium.set_selenium_implicit_wait(0)
+        try:
+            yield
+        finally:
+            self.selenium.set_selenium_implicit_wait(current_wait)
+
+    def _wait_to_appear(self, *args, timeout="15s"):
+        """This is the concrete implementation for the 'Wait for page object' keyword
+
+        It can be overridden by a subclass to do whatever is necessary to
+        wait for itself to appear.
+        """
+
+        try:
+            self.selenium.wait_for_condition(
+                "return (document.readyState == 'complete')"
+            )
+            self.salesforce.wait_for_aura()
+            self.builtin.wait_until_keyword_succeeds(
+                timeout,
+                "2s",
+                "Current page should be",
+                self._page_type,
+                self._object_name,
+            )
+        except Exception as e:
+            self.builtin.log(e, "DEBUG")
+            raise Exception(
+                f"Page object {self._page_type} {self._object_name} did not appear before timeout ({timeout}) expired."
+            )
+
+    def _remove_from_library_search_order(self):
+        """Remove the current page object from robot's library search order
+
+        Note: robot doesn't provide a way to completely unload a
+        library during execution. However, this at least makes sure that
+        all other libraries will have priority over this one.
+        """
+        order = list(self.builtin.set_library_search_order())
+        if self._libname in order:
+            order.remove(self._libname)
+            self.builtin.set_library_search_order(*order)
+            self.builtin.log("new search order: {}".format(order), "DEBUG")
+
+    @property
+    def object_name(self):
+        object_name = self._object_name
+
+        # the length check is to skip objects from a different namespace
+        # like foobar__otherpackageobject__c
+        if object_name is not None:
+            parts = object_name.split("__")
+            if len(parts) == 2 and parts[-1] == "c":
+                # get_namespace_prefix already takes care of returning an actual
+                # prefix or an empty string depending on whether the package is managed
+                object_name = "{}{}".format(
+                    self.cumulusci.get_namespace_prefix(), object_name
+                )
+        return object_name
+
+    @property
+    def selenium(self):
+        """Returns the instance of the imported SeleniumLibrary library"""
+        return self.builtin.get_library_instance("SeleniumLibrary")
+
+    def _get_object(self, **kwargs):
+        """Get the object associated with the given keyword arguments.
+
+        This performs a salesforce query. It will raise an exception unless
+        exactly one result is returned from the query.
+        """
+        results = self.salesforce_api.salesforce_query(self.object_name, **kwargs)
+        if len(results) == 0:
+            human_friendly_args = ", ".join(
+                ["{}={}".format(key, kwargs[key]) for key in kwargs]
+            )
+            raise Exception(
+                "no {} matches {}".format(self.object_name, human_friendly_args)
+            )
+        elif len(results) > 1:
+            raise Exception("Query returned {} objects".format(len(results)))
+        else:
+            return results[0]
+
+    def log_current_page_object(self):
+        """Logs the name of the current page object
+
+        The current page object is also returned as an object
+        """
+        polib = self.builtin.get_library_instance(
+            "cumulusci.robotframework.PageObjects"
+        )
+        if polib.current_page_object is None:
+            # this should not be possible, since this keyword is only available
+            # if you've loaded a page object. Still, better safe then sorry.
+            self.builtin.log("no page object has been loaded")
+            return None
+        else:
+            pobj = polib.current_page_object
+
+            self.builtin.log(
+                "current page object: {}".format(polib.current_page_object)
+            )
+            return pobj

cumulusci/robotframework/perftests/short/collection_perf.robot

@@ -0,0 +1,105 @@
+*** Settings ***
+Documentation   Tests of collections of records based on Jess Lopez's recommendations
+...             Note that keywords referenced in Setup are NOT performance measured.
+Library         DateTime
+Resource        cumulusci/robotframework/Salesforce.robot
+# Suite Teardown  Delete Session Records
+Force Tags      api200
+
+*** Keywords ***
+Insert 200 Contacts
+    [Documentation]  Create 200 Contacts in CONTACTS suite variable
+    @{objects}=  Generate Test Data  Contact  200  
+        ...  FirstName=User {{number}}
+        ...  LastName={{fake.last_name}}
+    Salesforce Collection Insert  ${objects}
+    Set Suite Variable      @{CONTACTS}      @{objects}
+    [return]    ${objects}
+
+Create Accounts If Necessary
+    [Documentation]  Create 200 Accounts corresponding to CONTACTS suite variable
+    ...              and update the contacts to connect to them
+    ${idlist} =     Evaluate    ",".join([f"'{contact['id']}'" for contact in $CONTACTS])
+    ${query} =      Set Variable   SELECT id FROM Contact WHERE AccountId=null AND id in (${idlist})
+    ${query_results} =   SOQL Query    ${query}
+    ${contacts_without_accounts} =    Set Variable    ${query_results}[records]
+    ${numobjects} =    Get Length     ${contacts_without_accounts}
+    ${newobjects} =     Generate Test Data     Account    ${numobjects} 
+        ...                                          Name={{fake.name}}
+
+    ${created_records}=     Salesforce Collection Insert  ${newobjects}
+
+    FOR     ${index}  IN RANGE    ${numobjects}
+        ${contact} =   Set Variable    ${contacts_without_accounts}[${index}]
+        ${account_id} =    Set Variable    ${created_records}[${index}][id]
+        Set To Dictionary   ${contact}    'AccountId'     ${account_id}
+    END
+
+    Salesforce Collection Update  ${CONTACTS}
+
+
+Insert 200 Prospecting Opportunities
+    [Documentation]  Create 200 Opportunities in OPPORTUNITIES suite variable
+    ...             Associate with accounts queried from Salesforce
+    ...             These may have been created by ``Create Accounts If Necessary``
+    ...             or may have been created automatically by a package like NPSP.
+    Create Accounts If Necessary
+    @{accounts}=    Salesforce Query    Account
+
+    ${date}=    Get Current Date     result_format=%Y-%m-%d
+    @{objects}=  Generate Test Data  Opportunity  200  
+        ...  Name=Opp {{number}}
+        ...  StageName=Prospecting
+        ...  Amount={{1000 + number}}
+        ...  CloseDate=${date}
+    ${numobjects}=  Get Length     ${objects}
+    FOR     ${index}   IN RANGE   ${numobjects}
+        ${object}=  Set Variable    ${objects}[${index}]
+        ${account}=     Set Variable    ${accounts}[${index}]
+        ${account_id}=  Set Variable    ${account}[Id]
+        set to dictionary   ${object}   AccountId   ${account_id}
+    END
+
+    Salesforce Collection Insert  ${objects}
+    Set Suite Variable      @{OPPORTUNITIES}      @{objects}
+
+*** Test Cases ***
+
+Perftest - Insert 200 Contacts
+    Start Performance Timer
+    Insert 200 Contacts
+    Stop Performance Timer
+
+Perftest - Insert 200 Contacts With Addresses
+    Start Performance Timer
+    @{objects}=  Generate Test Data  Contact  200  
+        ...  FirstName={{fake.first_name}}
+        ...  LastName={{fake.last_name}}
+        ...  MailingStreet={{fake.street_address}}
+        ...  MailingCity=New York
+        ...  MailingState=NY
+        ...  MailingPostalCode=12345
+        ...  Email={{fake.email(domain="salesforce.com")}}
+    Salesforce Collection Insert  ${objects}
+    Stop Performance Timer
+
+Perftest - Insert 200 Prospecting Opportunities
+    Start Performance Timer
+    [Setup]   Run Keywords
+    ...             Insert 200 Contacts
+    ...     AND     Create Accounts If Necessary
+    Insert 200 Prospecting Opportunities
+    Stop Performance Timer
+
+Perftest - Change 200 Opportunity States to Closed-Won
+    Start Performance Timer
+    [Setup]   Run Keywords
+    ...             Insert 200 Contacts
+    ...     AND     Create Accounts If Necessary
+    ...     AND     Insert 200 Prospecting Opportunities
+
+    FOR     ${record}   IN  @{OPPORTUNITIES}
+        Set To Dictionary   ${record}   StageName   Closed Won
+    END
+    Salesforce Collection Update    ${OPPORTUNITIES}
+    Stop Performance Timer

cumulusci/robotframework/tests/CustomObjectTestPage.py

@@ -0,0 +1,10 @@
+"""
+This class is used by test_pageobjects
+"""
+from cumulusci.robotframework.pageobjects import ListingPage, pageobject
+
+
+# The point of this class is to test out using an alias
+@pageobject(page_type="Listing", object_name="Custom Object")
+class CustomObjectListingPage(ListingPage):
+    _object_name = "CustomObject__c"

cumulusci/robotframework/tests/FooTestPage.py

@@ -0,0 +1,8 @@
+from cumulusci.robotframework.pageobjects import BasePage, pageobject
+
+
+@pageobject(page_type="Test", object_name="Foo__c")
+class FooTestPage(BasePage):
+    def foo_keyword_1(self, message):
+        self.builtin.log(message)
+        return "foo keyword 1: {}".format(message)