Merge branch 'master' of github.com:hitchdev/page-config-model

CHANGELOG.md

@@ -1 +1,7 @@
 # Changelog
+
+
+### 0.3.0
+
+* FEATURE : Added reloading.
+

README.md

@@ -1,3 +1,23 @@
 # HitchPage
 
-The page config model is an alternative to the page object model.
+[![Main branch status](https://github.com/hitchdev/hitchpage/actions/workflows/regression.yml/badge.svg)](https://github.com/hitchdev/hitchpage/actions/workflows/regression.yml)
+
+
+## Install
+
+```bash
+$ pip install hitchpage
+```
+
+## Using
+
+- [Iframe](https://hitchdev.com/hitchpage/using/iframe)
+- [Quickstart](https://hitchdev.com/hitchpage/using/quickstart)
+- [Reload](https://hitchdev.com/hitchpage/using/reload)
+
+
+
+## Approach
+
+- [Page Config Model](https://hitchdev.com/hitchpage/approach/page-config-model)
+

docs/public/approach/index.md

@@ -0,0 +1,6 @@
+---
+title: General Approach
+---
+
+- [Page Config Model](page-config-model)
+

docs/public/approach/page-config-model.md

@@ -0,0 +1,49 @@
+---
+title: Page Config Model
+---
+# Page Config Model
+
+The page config model is a version of the [page object model](https://martinfowler.com/bliki/PageObject.html) design pattern.
+
+A page config object wraps an HTML page or fragment, with an application-specific API, allowing you to manipulate page elements without digging around in the HTML.
+
+The main difference is that the PCM uses **configuration not code** to abstract selectors. This is done according to [the rule of least power](https://en.wikipedia.org/wiki/Rule_of_least_power).
+
+Example:
+
+```python
+pcm.next_page("login")
+pcm.element("username").fill("myusername")
+pcm.element("password").fill("mypassword")
+pcm.element("ok").click()
+pcm.next_page("dashboard") expect(pcm.element("message")).to_be_visible()
+```
+
+With a corresponding page config:
+
+```yaml
+login:
+  element:
+    username: "#id_username"
+    password: "#id_password"
+    ok: "#id_ok_button"
+dashboard:
+   element:
+     message: "#id_dashboard_message"
+```
+
+The page config model is a pattern exhibited by hitchpage, which was designed to be used with the hitchstory testing and documentation framework.
+
+This is so that developers can write declarative, testable specification scenarios that are complely decoupled from selectors and are thus readable and executable. For example:
+
+```yaml
+- enter:
+    username: myusername
+    password: mypassword
+- click: ok
+- new page: dashboard
+- expect: message
+```
+
+Unlike the page object model, the page config model pattern is currently built upon the assumption that, by default, granular interactions - e.g. clicking buttons, filling text boxes are *all* parts of the spec which are of potential interest to stakeholders and should therefore not be abstracted by default.
+

docs/public/changelog.md

@@ -0,0 +1,7 @@
+# Changelog
+
+
+### 0.3.0
+
+* FEATURE : Added reloading.
+

docs/public/index.md

@@ -0,0 +1,27 @@
+---
+title: HitchPage
+---
+
+
+
+<img alt="GitHub Repo stars" src="https://img.shields.io/github/stars/hitchdev/hitchpage?style=social"><img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/hitchpage">
+
+
+## Install
+
+```bash
+$ pip install hitchpage
+```
+
+## Using
+
+- [Iframe](using/iframe)
+- [Quickstart](using/quickstart)
+- [Reload](using/reload)
+
+
+
+## Approach
+
+- [Page Config Model](approach/page-config-model)
+

docs/public/using/iframe.md

@@ -0,0 +1,93 @@
+---
+title: Iframe
+---
+
+
+
+Look for an element inside an iframe.
+
+Then look for an element inside an iframe inside an iframe.
+
+
+# Code Example
+
+
+With code:
+
+```python
+from playwright.sync_api import expect, sync_playwright
+from hitchpage import PlaywrightPageConfig
+from pathlib import Path
+
+browser = sync_playwright().start().chromium.connect("ws://127.0.0.1:3605")
+page = browser.new_page()
+
+conf = PlaywrightPageConfig(
+    *Path(".").glob("*.yml"),    # all .yml files in this folder
+    playwright_page=page,
+)
+
+page.goto("http://localhost:8001")
+
+```
+
+
+selectors.yml:
+
+```yaml
+iframe:
+  element:
+    page title: "#id_iframe_title"
+    message iframe:
+      locator: "#message_iframe"
+    iframe content message:
+      in iframe: message iframe
+      locator: "#id_dashboard_message"
+    iframe in iframe:
+      in iframe: message iframe
+      locator: iframe
+    iframe in iframe message:
+      in iframe: iframe in iframe
+      locator: "#id_iframe_in_iframe"
+
+```
+
+With HTML:
+
+```html
+{'index.html': '<div class="form-login">\n  <h4 id="id_iframe_title">This page contains an iframe</h4>\n  <iframe id="message_iframe" src="iframe_content.html" />\n</div>\n', 'iframe_content.html': '<p id="id_dashboard_message">hello!</a>\n<iframe id="child_iframe" src="iframe_in_iframe_content.html" />\n', 'iframe_in_iframe_content.html': '<p id="id_iframe_in_iframe">message</a>\n'}
+```
+
+
+
+
+
+
+```python
+conf.next_page("iframe")
+print("iframe page")
+expect(conf.element("page title")).to_be_visible()
+expect(conf.element("iframe content message")).to_be_visible()
+expect(conf.element("iframe in iframe message")).to_be_visible()
+
+```
+
+Will output:
+```
+iframe page
+```
+
+
+
+
+
+
+
+
+
+!!! note "Executable specification"
+
+    Documentation automatically generated from 
+    <a href="https://github.com/hitchdev/hitchpage/blob/master/hitch/story/iframe.story">iframe.story
+    storytests.</a>
+

docs/public/using/index.md

@@ -0,0 +1,11 @@
+---
+title: Using HitchPage
+---
+
+How to:
+
+- [Iframe](iframe)
+- [Quickstart](quickstart)
+- [Reload](reload)
+
+

docs/public/using/quickstart.md

@@ -0,0 +1,94 @@
+---
+title: Quickstart
+---
+
+
+
+Simple scenario with a log in page and a dashboard
+with some locator selectors and one text selector.
+
+
+# Code Example
+
+
+With code:
+
+```python
+from playwright.sync_api import expect, sync_playwright
+from hitchpage import PlaywrightPageConfig
+from pathlib import Path
+
+browser = sync_playwright().start().chromium.connect("ws://127.0.0.1:3605")
+page = browser.new_page()
+
+conf = PlaywrightPageConfig(
+    *Path(".").glob("*.yml"),    # all .yml files in this folder
+    playwright_page=page,
+)
+
+page.goto("http://localhost:8001")
+
+```
+
+
+selectors.yml:
+
+```yaml
+login:
+  element:
+    username: "#id_username"
+    password: "#id_password"
+    ok: "#id_ok_button"
+dashboard:
+  element:
+    dashboard: "#id_this_is_a_dashboard_element"
+    message: "#id_dashboard_message"
+    next:
+      text: next
+
+```
+
+With HTML:
+
+```html
+{'index.html': '<div class="form-login">\n<input type="text" id="id_username" placeholder="username" /></br>\n<input type="text" id="id_password" placeholder="password" /></br>\n<div class="wrapper">\n<span class="group-btn">     \n<a id="id_ok_button" href="/dashboard.html" class="btn btn-primary btn-md">login <i class="fa fa-sign-in"></i></a>\n</span>\n</div>\n</div>\n', 'dashboard.html': '<div class="form-login">\n  <h4 id="id_this_is_a_dashboard_element">Dashboard</h4>\n  <p id="id_dashboard_message">hello!</a>\n</div>\n'}
+```
+
+
+
+
+
+
+```python
+conf.next_page("login")
+print("login page")
+conf.element("username").fill("myusername")
+conf.element("password").fill("mypassword")
+conf.element("ok").click()
+
+conf.next_page("dashboard")
+print("dashboard page")
+expect(conf.element("message")).to_be_visible()
+
+```
+
+Will output:
+```
+login page                                                                                                                                                      
+dashboard page
+```
+
+
+
+
+
+
+
+
+
+!!! note "Executable specification"
+
+    Documentation automatically generated from 
+    <a href="https://github.com/hitchdev/hitchpage/blob/master/hitch/story/quickstart.story">quickstart.story
+    storytests.</a>
+