Open UI Automation (OUIA) 1.0-RC ================================ Metadata -------- | Key | Value | |-----------------|-------| | **Status** | Draft | | **Authors** | Pete Savage, Karel Hala, Ronny Pfannschmidt | | **Current Version** | 1.0-RC | Abstract -------- This specification is designed to promote certain key guidelines to follow when creating a new web framework or application. Its goal is to ease the burden of individuals wishing to create and maintain automated testing environments. The OUIA is composed of multiple sections. An element of an app/framework can be said to be compliant with either all of the specification or one or more of its parts. As such it is defined as a _composable_ specification. The reason for this is largely due to the prevalent demarcation between responsibilities of framework and application developers. For instance an application may use a particular web framework and be unable to negotiate compliance of that framework with OUIA. However they may choose to make the elements that they _do_ have control over fully compliant with the OUIA. Language -------- The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**MAY**", and "**OPTIONAL**" in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). Namespacing ----------- * All HTML elements created for the sole purpose of fulfilling or augmenting this specification **MUST** be prefixed with `ouia`. Currently there are no custom HTML elements defined. * All custom HTML attributes to be applied to existing HTML elements **MUST** be prefixed with `data-ouia`. * All additional attributes to existing Javascript objects **MUST** be prefixed with `ouia`. Specification Parts ------------------- The OUIA specification is split up into several sections. As stated, an application or framework can implement any number of the specification parts, but each section must be implemented completely. Thus a project can be said to be `OUIA:Component` or `OUIA:Page` compliant, as opposed to being completely `OUIA` compliant, but **ALL** components of the `OUIA:Component` part **MUST** be adhered to. The following blocks exist in the specification: * `OUIA:Component` - components and component frameworks * `OUIA:Page` - page identification * `OUIA:PageSafe` - interaction safety ### `OUIA:Component` This part is designed to cover components in use on pages. Components that are `OUIA:Component` compliant **MUST** have the following properties. * A root level HTML element with a `data-ouia-component-type` attribute describing a unique name identifying **ALL** HTML components that can be controlled with the same code or interactions. These identifiers **MAY** and **SHOULD** be namespaced when used within a framework, particularly when the name is generic. The delimiter between namespace and type name should be a single `/` character. * e.g. A page that has a special dropdown could choose to name that dropdown as `FrameworkA/CustomDropdown`. All instances of this `FrameworkA/CustomDropdown` component **MUST** be expected to be able to be controlled via the same automation. * An id attribute called `data-ouia-component-id` * if there is only one instance of the component on the page at once, it is **OPTIONAL** * if there are multiple instances of a component on the page it **MUST** be used * it **MUST** be unique within the surrounding context of the component (context may be a surrounding component or collection) * e.g. A vertical navigation can be expected to only be instantiated once on a page. As such it does not need any other identifying factors. Another component type, like a button, would be created multiple times on a page and requires some kind of unique identifying id. * e.g. An list of items could have tags associated with them. These could be presented in a tabular format. Whilst the ids of those tags could be identical, they are also contained in rows that make them contextually different. An alternative to this is that the id could be prefixed with the item id that it is related to, to create a compound id. * An attribute called `data-ouia-safe`, which is `True` only when the component is in a static state, i.e. no animations are occurring. At all other times, this value **MUST** be `False`. ### `OUIA:Page` This part is designed to cover page identification. Pages that are `OUIA:Page` compliant **MUST** have the following properties: * A `` html tag with the following attributes: * A `data-ouia-page-type` attribute, which determines the base context of the page. * e.g. A page listing some inventory of food items could have `food` as its `data-ouia-page-type` attribute. * A `data-ouia-page-action` attribute, which determines if the page has a controller associated with it to perform a specific action. This is **OPTIONAL** if the page does not describe a specific action, or is a single action screen displaying information only. * e.g. A page providing the edit action of an inventory item could have an `edit` value for the `data-ouia-page-action` attribute. Whereas a modal about page would not need an `data-ouia-page-action` attribute. * A page which dynamically changes action without a page reload **MUST** correctly update the `data-ouia-page-type` and `data-ouia-page-action` attributes if the context of the page changes. * An **OPTIONAL** `data-ouia-page-object-id` attribute, where the page is in the context of a specific instance of an object. E.g. A page describing a food item that is being edited, could have an `data-ouia-page-object-id` field of 142526. * Each of the four main content areas present on the page, *Header*, *Main*, *Navigation*, *Footer*, **MUST** be embellished with the corresponding data attribute to aid in finding components within certain areas. * `data-ouia-header="true"` - For the header * `data-ouia-footer="true"` - For the footer * `data-ouia-main="true"` - For the main content pane * `data-ouia-navigation="true"` - For the main navigation pane * *Header*, *Footer* and *Main* **MUST NOT** ever be nested inside each other. * *Navigation* **MAY** live inside any of the other content areas but must appear only once. * All links appearing inside the *Navigation* content pane **MUST** specify the `href` attribute with a valid URL to the target, and in addition **MUST** also include a `data-ouia-navigation-name` which identifies the name of the navigation link to aid in building a site map. * All other links which are considered top level navigational, i.e. they force a page reload/load, **MUST** also be defined with hidden links inside the *Navigation* pane to aid in site map creation. * e.g. `.