Simple Login Test
*****************

This package provides a ready-to-use scenario to test a simple login flow:
:class:`balderhub.auth.scenarios.ScenarioSimpleLogin`. You can use this scenario for almost all login environments
independent of their specific implementation or how it can be controlled.

.. note::
    **Testing Websites?** Have a look at the
    `contrib/auth guide at the balderhub-html Documentation <https://hub.balder.dev/projects/html/en/latest/contrib/auth.html>`_.


Login: In General
=================

The scenario looks like shown below:

.. code-block:: python

    class ScenarioSimpleLogin(balder.Scenario):

        class Client(balder.Device):
            role = UserRoleFeature()
            login = UserLoginFeature()


It needs a user role with :class:`balderhub.auth.lib.scenario_features.role.UserRoleFeature` and an implementation of
the :class:`balderhub.auth.lib.scenario_features.UserLoginFeature`:

.. code-block:: python

    import balder

    # module `balderhub.auth.lib.scenario_features`

    class YourImplementationOfUserLoginFeature(balder.Feature):
        """
        This login feature can be assigned to devices that do provide a basic login handling.
        """

        def insert_username(self, username: str) -> None:
            """
            Inserts the username for login

            :param username: the username to insert
            """
            raise NotImplementedError

        def insert_password(self, password: str) -> None:
            """
            Inserts the password for login

            :param password: the password to insert
            """
            raise NotImplementedError

        def submit_login(self) -> None:
            """
            Executes the login
            """
            raise NotImplementedError

        def is_already_logged_in(self):
            """
            :return: returns True if someone is already logged in, otherwise False
            """
            raise NotImplementedError


Just provide an implementation for them and create a setup like shown below and the test can be executed.

.. code-block:: python

    # file `setups/setup_office.py`

    import balder
    import balderhub.auth.lib.scenario_features.role
    ...

    class UserConfig(balderhub.auth.lib.scenario_features.role.UserRoleFeature):

        username = 'admin'
        password = 'secret'

    class SetupExample(balder.Setup):

        class DeviceToLogin(balder.Device):
            user = UserConfig()
            login = YourImplementationOfUserLoginFeature()

Login: For Websites
===================

If you want to use the :class:`balderhub.auth.scenarios.ScenarioSimpleLogin` within websites, you can use the contrib
feature implementation :class:`balderhub.auth.contrib.html.setup_features.UserLoginFeature`.

This feature needs an implementation of the page :class:`balderhub.auth.contrib.html.pages.LoginPage`, like it is
shown below:

.. code-block:: python

    # file `lib/pages.py`

    import balderhub.auth.contrib.html.pages
    from balderhub.html.lib.utils import Selector
    from balderhub.url.lib.utils import Url
    import balderhub.html.lib.utils.components as html


    class LoginPage(balderhub.auth.contrib.html.pages.LoginPage):

        url = Url('https://example.com')

        # Overwrite abstract property
        @property
        def input_username(self):
            return html.inputs.HtmlTextInput.by_selector(self.driver, Selector.by_name('user'))

        @property
        def input_password(self):
            return html.inputs.HtmlPasswordInput.by_selector(self.driver, Selector.by_name('user'))

        @property
        def btn_login(self):
            return html.HtmlButtonElement.by_selector(self.driver, Selector.by_id('submit-button'))

In you setup you only need to add these both features:

.. code-block:: python

    # file `setups/setup_office.py`

    import balder
    import balderhub.auth.lib.scenario_features.role
    from balderhub.auth.contrib.html.setup_features import UserLoginFeature
    from lib.pages import MyWebsiteMain, LoginPage

    class UserConfig(balderhub.auth.lib.scenario_features.role.UserRoleFeature):

        username = 'admin'
        password = 'secret'

    class SetupOffice(balder.Setup):

        class Browser(balder.Device):
            user = UserConfig()
            login = UserLoginFeature()
            page_login = LoginPage()