Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/davidemoro/pypom_form

PyPOM based page object model for schema based forms
https://github.com/davidemoro/pypom_form

pytest python python-3 qa selenium test-automation testing

Last synced: about 1 month ago
JSON representation

PyPOM based page object model for schema based forms

Awesome Lists containing this project

README 

        
pypom_form

**********



.. image:: https://travis-ci.org/davidemoro/pypom_form.svg?branch=develop

       :target: https://travis-ci.org/davidemoro/pypom_form



.. image:: https://readthedocs.org/projects/pypom_form/badge/?version=latest

       :target: http://pypom_form.readthedocs.io



.. image:: https://codecov.io/gh/davidemoro/pypom_form/branch/develop/graph/badge.svg

       :target: https://codecov.io/gh/davidemoro/pypom_form



.. image:: https://api.codacy.com/project/badge/Grade/0698c7aa2e164ee996518737aad7d6f4

       :target: https://www.codacy.com/app/davide-moro/pypom_form?utm_source=github.com&utm_medium=referral&utm_content=davidemoro/pypom_form&utm_campaign=Badge_Grade

       

.. image:: https://pyup.io/repos/github/davidemoro/pypom_form/python-3-shield.svg

     :target: https://pyup.io/repos/github/davidemoro/pypom_form/

     :alt: Python 3



``pypom_form`` is a PyPOM based package that provides declarative schema based form interaction for page objects.



pypom_form aims to improve the developer experience for UI, E2E test automation when you

have to interact with page object containing forms thanks to declarative schema models.



If you come from past experience with frameworks like `SQLAlchemy`_, Dexterity (`Plone`_) or the old Archetypes (`Plone`_)

you should be already familiar with this pattern: you simply define a model with a schema and you will be able to

interact with your model saving or retrieving data.

Same happens with pypom_form where the model is the page.



pypom_form it is internally based on:



* `PyPOM`_

* `colander`_

* `Splinter`_



How does it work?

=================



Whith pypom_form you have just to:



* instanciate a page object instance whose class inherits from BaseFormPage provided by pypom_form

* declare the schema model



And you will be ready for interacting with your page driving the browser with your form just typing::



    page.title = 'the title'

    page.title



assuming that you have a ``title`` field in your form.



Main concepts

-------------



You might think about the ``schema`` concept as a set of named attributes (``fields``) that will be

available on the ``model`` as regular properties.



Each ``field`` on the schema is defined with a ``type`` (eg: string, int, float, datetime, date, bool, etc)

that defines the data type for the given field on the application domain level.



Fields has a reference to a ``widget`` defined imperatively or assigned by default depending on the field

type.

The inner implementation of widgets provided by pypom_form is based on PyPOM's Regions, so ``widget regions``

wraps and manage a DOM containing the widget.



Basically the widget translates data from the applicative domain to the browser domain and vice versa

through serialization and deserialization.



You might thing about a widget as how you have to driver your browser when you set ``True`` to a boolean

property or get the actual value on the form: basically it depends on the widget implementation. For example

you might have a checkbox, yes/no radio buttons or combo select, etc and if you want to set ``True`` the

way you drive the browser changes. Same for date widgets and so on.



You might have to deal with complex widgets too like:



* reference widgets (eg: hierarchical content navigation with search, filtering, etc)

* advanced multi selection widgets

* dictionary widgets (key value mapping)

* etc



For example, assuming you are dealing with a pretend advanced single selection choice field you can

access to advanced logics provided by the ``widget region``::



    page.getWidgetRegion('state').filter('virg').select('Virginia')



or access to validation error messages, label text, etc.



Why pypom_form

--------------



Obviously you can drive your browser in automated tests with plain selenium/splinter or with a traditional

plain page object model pattern but with pypom_form you have the following advantages:



* write once and reusable approach, very useful if you are testing CMS framework

* separation of concerns for page and widget logics

* declarative schema approach

* reusable schema and widgets, no code repetition

* widgets can be shared with other projects using pypom_form

* simple API based on auto generated getter and setters

* interact with advanced widget logics thanks to PyPOM based region widgets

* widget isolation. All element queries run against the root region, not the page root

* simpler input elements selectors, they are relative to the region widget root

* schema forms improves how you document page containing forms (attributes names, type, widgets,

  allowed vocabularies, etc). All you need to know is defined at schema level with the whole picture

  available at a glance

* reuse of existing schemas if you are going to test a colander/deform based application (probably

  you are testing a Pylons `Pyramid`_ Python based web application)

* page and schema inheritance supported as well

* easy test multi skin web applications with same data model, same or different selectors or widget

  types. So you can reuse all your page object classes as they are defined, it changes only the schema

  widget selector adn widget types

* widget regions are PyPOM regions, so if you want to access inner elements inside the widget container

  the resulting selectors will be simpler because they are relative to the widget region root.

  Also sub/nested regions or dynamic regions are supperted as well

* interact with your model with applicative domain data instead of browser domain data. It is more

  simple and easy to manage Python data (for example you set 12.9 instead of '12.9', same for datetimes

  values like ``datetime.now()``)

* supports chained calls like ``page.set('title', 'the title')``

* supports bulk field updates considering the order defined at schema level via ``page.update(**values)``

* don't reinvent the wheel. It is based on existing and widely used components like the plain PyPOM or

  Colander libraries

* same user experience if you are already familiar with schema declarative models like ``SQLAlchemy``,

  ``Archetypes`` (Plone), ``Dexterity`` (Plone) or form libraries like ``deform``

* since widget implementation is based on regions, you can simply perform a ``page.name = "the name"``

  on page load instead of having to call a wait method before setting the value:

  the widget is able to wait for the widget load before getting or setting data

* page objects classes more simple, with less code, more standard even if different test engineers will

  implement page form logics: there is a structural pattern



In addition:



* 100% test coverage

* both Python 2 and 3 support

* supports Splinter drivers (Selenium support not yet available)

* pytest setup ready thanks to ``pytest-splinter``



Code samples

============



The following code samples assumes that there is a navigation fixture providing the page instance

built with a Splinter driver but you can build by yourself a page instance following

the PyPOM documentation:



* http://pypom.readthedocs.io/en/latest/



Schema definition::



    import colander

    

    from pypom_form.form import BaseFormPage

    

    

    class BaseEditSchema(colander.MappingSchema):

        """ This is the base edit mapping common for all pages """

    

        name = colander.SchemaNode(

            colander.String(),

            selector=('id', 'name-widget'),

        )

    

    

    class BaseEditPage(BaseFormPage):

        """ This is the base edit class """

    

        schema_factory = BaseEditSchema



And assuming you have a page instance you can interact with the above page

just setting an attribute::



    @pytest_bdd.when(pytest_bdd.parsers.parse(

        'I set {name} as name field'))

    def fill_name(navigation, name):

        page = navigation.page

        page.name = name



You can also define other pages with extended schema, for example an integer

type::



    class AnotherPageEditSchema(BaseEditSchema):

    

        duration = colander.SchemaNode(

            colander.Int(),

            missing=0,

            selector=('id',

                      'duration-widget'),

            validator=colander.Range(0, 9999))



but you can create also field types like ``colander.Bool`` or any other colander

supported types.



And the test::



    @pytest_bdd.when(pytest_bdd.parsers.cfparse(

        'I set {duration:Number} as Alarm duration',

        extra_types=dict(Number=int)))

    def fill_alarm_duration(navigation, duration):

        page = navigation.page

        page.duration = duration



You might notice that in the above example you are setting an integer duration

and not a string. So you can perform ``page.duration += 10`` for example. 



You can also define custom widgets on fields if the default implementation does

not match the one available on your application (for example a non standard

checkbox for a boolean widget), for example a pretend ``MyBooleanWidget``::



    mybool = colander.SchemaNode(

        colander.Bool(),

        missing=False,

        selector=(

            'id',

            'mybool-widget'

        ),

        pypom_widget=MyBoolWidget()

    )



Also chained calls are supported (eg: set the title, perform the pretend submit method

and then set a boolean)::



    page.set('title', 'the title'). \

        .submit(). \

        .set('mybool', False)



or bulk updates. All changes occurs following the fields order at schema level::



    page.update(**{'title': 'the title', 'mybool': True})



The ``update`` or ``raw_update`` can be used in test preconditions creation.

Assuming you have a generic given step with parametrized with a complex configuration

you can pass the raw json data and the ``raw_update`` will take care about the

data conversion from browser model (eg: string) to the page model (strings, integers,

datetimes, etc)::



    @pytest_bdd.given(pytest_bdd.parsers.cfparse(

        'I have a CAN bus protocol configured with:\n{raw_conf:json}',

        extra_types=dict(json=json.loads)))

    def create_can_protocol(navigation, base_url, raw_conf):

        """ create a can protocol

        """



        navigation. \

            visit_page('CANBusProtocolsPage'). \

            wait_for_full_spinner(). \

            click_add(). \

            raw_update(**raw_conf). \

            save(). \

            wait_for_success_pop_up_appears(). \

            click_on_ok_pop_up()



assuming that the ``raw_conf`` is specified in json format in

the ``.feature`` file, for example::



    @UI @edit @CANBusParameter

    Scenario: Add a CAN bus parameter

      Given I am logged in as Administrator

      And I have a CAN bus protocol configured with:

          {"name": "The name",

           "baudrate": "250",

           ...

          }

      And ...



As you can see in the above code examples there is no need to perform wait calls before

interacting with a form on page load because each widget is able to wait until its

controlled input element is ready. Wait logics are already defined on widget level and

you can override them.



.. _PyPOM: http://pypom.readthedocs.io

.. _colander: http://docs.pylonsproject.org/projects/colander/en/latest/

.. _Splinter: https://splinter.readthedocs.io/en/latest/

.. _Plone: https://plone.org/

.. _SQLAlchemy: http://www.sqlalchemy.org/

.. _Pyramid: https://trypyramid.com/