pypom_form

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.