REFACTOR : Cleaned up stories and generated changelog + readme.

Author: crdoconnor

CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+
+### Latest
+
+
+No relevant code changes.
+
+### 0.10.0
+
+* FEATURE : Hover functionality to identify and reveal the secondary element
+
+
+### 0.9.0
+
+* FEATURE : Sub-elements - pick out elements within elements by specifying a selector within a selector.
+* FEATURE : Selectors can use iframes.
+
+
+### 0.8.0
+
+* FEATURE : Should contain now usable with timeout.
+
+
+### 0.7.0
+
+* FEATURE : should_disappear()
+* FEATURE : Added timeouts to 'should_*'
+
+
+### 0.6.1
+
+* FEATURE : Clearer exceptions on should_contain and should_be_on_page.
+* FEATURE : Timeout on explicit wait to appear on page.
+
+
+### 0.6.0
+
+* FEATURE : Clearer timeout exceptions.
+* FEATURE : Added a clearer exception for 'not found in selectors'.
+* FEATURE : Handle 'which' property on 'text is' attributes.
+* FEATURE : Handle 'which' property on attributes.
+* FEATURE : Selects 2nd, 3rd, 4th ... last of elements that contain text.
+* FEATURE : Ability to select 'last' element matching a class name.
+* FEATURE : Allow default timeout to be set up front.
+* FEATURE : Added the ability to pick a single element when more than one is matched by a class.
+
+
+### 0.5.1
+
+* FEATURE : Add the ability to select by text contents or what elements contain.
+
+
+### 0.4.0
+
+* BUGFIX : Locked down the execution space so that invalid conditions cause a true exception.
+* FEATURE : Added time travel to selenium.
+
+
+### 0.3.0
+
+* FEATURE : Classes selector.
+
+
+### 0.2.0
+
+* FEATURE : Handle more than one element with the same ID.
+
+
+### 0.1.3
+
+* FEATURE : .should_appear()
+
+
+### 0.1.2
+
+* FEATURE : Selection by xpath.
+
+
+### 0.1.1
+
+* FEATURE : Do selectors using attributes.
+

README.md

@@ -0,0 +1,219 @@
+# SeleniumDirector
+
+
+SeleniumDirector is a python 3 library that makes it straightforward to write easily maintainable 
+python code to interact with websites in a non-brittle way using the screenplay pattern with
+selenium.
+
+Seleniumdirector reads YAML "selector" files which associate readable labels with complex selectors
+- i.e. class name selectors, id selectors, attribute selectors, text and xpath.
+
+Separating the "element selection" concern from element interaction allows for simpler, more straightforward
+and more readable code.
+
+SeleniumDirector was built to be used with [HitchStory](https://hitchdev.com/hitchstory) as a means
+of writing straightforward to maintain integration/browser tests, but it completely agnostic about
+where it is used. It can be used in py.test, nose or unittest or it could be used to direct other forms
+of automated website interaction - e.g. as a scraper.
+
+
+
+## Example
+
+
+
+
+This example demonstrates how to look for of HTML IDs to
+select and use HTML elements by using 'id=class_name' or 'id: class_name'.
+
+This is often the ideal kind of selector to use if an element has an ID, since IDs tend to be
+relatively unchanging and the likelihood of accidentally selecting the wrong element is low.
+
+If there is more than one element matching a ID (shouldn't be common since that's a 
+violation of HTML semantics, but it still happens!), the element to use can be
+specified using 'which: [ number ]' or which: last.
+
+
+
+HTML:
+
+
+
+index.html:
+
+```html
+<div class="form-login">
+<input type="text" id="id_username" class="form-control input-sm chat-input" placeholder="username" /></br>
+<input type="text" id="id_password" class="form-control input-sm chat-input" placeholder="password" /></br>
+<div class="wrapper">
+<span class="group-btn">     
+<a id="id_ok_button" href="/dashboard.html" class="btn btn-primary btn-md">login <i class="fa fa-sign-in"></i></a>
+</span>
+</div>
+</div>
+
+```
+
+
+dashboard.html:
+
+```html
+<div class="form-login">
+  <h4 id="id_this_is_a_dashboard_element">Dashboard</h4>  <p id="id_dashboard_message">hello!</a>
+</div>
+
+```
+
+
+
+
+
+selectors.yml:
+
+```yaml
+login:
+  appears when: login page identifier
+  elements:
+    login page identifier: id=id_username
+    username: id=id_username
+    password: id=id_password
+    ok: id=id_ok_button
+dashboard:
+  appears when: dashboard identifier
+  elements:
+    dashboard identifier:
+      id: id_this_is_a_dashboard_element
+    message:
+      id: id_dashboard_message
+
+```
+
+set up:
+
+```yaml
+from seleniumdirector import WebDirector
+from selenium import webdriver
+
+driver = webdriver.Chrome()
+selector = WebDirector(driver, "../selectors.yml", default_timeout=5)
+
+```
+
+
+
+
+Successful:
+
+
+
+
+```python
+selector.visit("http://localhost:8000")
+selector.wait_for_page("login")
+selector.the("username").send_keys("login")
+selector.the("password").send_keys("password")
+selector.the("ok").click()
+selector.wait_for_page("dashboard")
+selector.the("message").should_be_on_page()
+selector.the("message").should_contain("hello!")
+driver.quit()
+
+```
+
+
+
+
+
+
+More than one ID:
+
+
+
+
+```python
+selector.visit("http://localhost:8000")
+selector.wait_for_page("login")
+selector.the("username").send_keys("login")
+selector.the("password").send_keys("password")
+selector.the("ok").click()
+selector.wait_for_page("dashboard")
+selector.the("message").should_be_on_page()
+
+```
+
+
+Raises:
+
+```python
+seleniumdirector.exceptions.MoreThanOneElement:
+More than one element matches your query '//*[@id='id_dashboard_message']'.
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+## Install with pip
+
+```bash
+$ pip install seleniumdirector
+```
+
+You can also use hitchkey to generate a skeleton project structure along
+with [hitchstory](https://hitchdev.com/hitchstory/).
+
+Either install hitchkey with [pipsi](https://github.com/mitsuhiko/pipsi):
+
+```bash
+pipsi install hitchkey
+```
+
+Or, if you'd prefer, you can safely install with "sudo pip" (deactivate any virtualenvs you're in):
+
+```bash
+sudo pip install hitchkey
+```
+
+Once hitchkey is installed:
+
+```bash
+cd /your/project/directory
+hk --demo seleniumdirector
+```
+
+This will create a directory called "hitch" and put three files in it, including one story, which you can play by running:
+
+```bash
+hk bdd logged in
+```
+
+
+## Using SeleniumDirector
+
+- [Selector for element inside iframe](https://hitchdev.com/seleniumdirector/using/alpha/iframe)
+- [Sub-elements](https://hitchdev.com/seleniumdirector/using/alpha/subelements)
+- [Selectors with HTML classes](https://hitchdev.com/seleniumdirector/using/alpha/html-classes)
+- [With HTML attributes](https://hitchdev.com/seleniumdirector/using/alpha/attributes)
+- [Overlay - should_be_on_top](https://hitchdev.com/seleniumdirector/using/alpha/element-should-be-on-top)
+- [Element should not be on page](https://hitchdev.com/seleniumdirector/using/alpha/disappearing-element)
+- [Selectors using HTML contents](https://hitchdev.com/seleniumdirector/using/alpha/html-element-contents)
+- [Using a selenium element object](https://hitchdev.com/seleniumdirector/using/alpha/using-selenium-element-object)
+- [Hover - hovering over an element](https://hitchdev.com/seleniumdirector/using/alpha/hovering-over-an-element)
+- [Should contain text](https://hitchdev.com/seleniumdirector/using/alpha/should-contain-text)
+- [Selectors with HTML IDs](https://hitchdev.com/seleniumdirector/using/alpha/html-ids)
+
+
+
+## Why not X instead?
+
+- [Why not use Robot SeleniumLibrary?](https://hitchdev.com/seleniumdirector/why-not/robot)
+- [Why not use the page object pattern?](https://hitchdev.com/seleniumdirector/why-not/page-object)
+- [Why not use Capybara-Py or Splinter?](https://hitchdev.com/seleniumdirector/why-not/capybara-py-or-splinter)

hitch/hitchreqs.in

@@ -1,3 +1,4 @@
+hitchpylibrarytoolkit
 dirtemplate==0.1.4
 strictyaml>=0.11.0
 hitchstory>=0.11.1

hitch/hitchreqs.txt

@@ -16,9 +16,12 @@ dirtemplate==0.1.4
 docutils==0.16            # via readme-renderer
 entrypoints==0.3          # via flake8
 flake8==3.7.9
+gitdb2==2.0.6             # via gitpython
+gitpython==3.0.7          # via hitchpylibrarytoolkit
 hitchbuild==0.4.0
 hitchbuildpy==0.4.6
 hitchdoc==0.1.1
+hitchpylibrarytoolkit==0.3.1
 hitchrun==0.3.2
 hitchrunpy==0.10.0
 hitchstory==0.12.1
@@ -27,13 +30,14 @@ idna==2.8                 # via requests
 importlib-metadata==1.5.0  # via argcomplete, keyring, path, twine
 ipykernel==5.1.4          # via jupyter-console
 ipython-genutils==0.2.0   # via traitlets
-ipython==7.12.0           # via ipykernel, jupyter-console
+ipython==7.12.0           # via hitchpylibrarytoolkit, ipykernel, jupyter-console
 jedi==0.16.0              # via ipython
 jeepney==0.4.2            # via keyring, secretstorage
 jinja2==2.11.1            # via dirtemplate, hitchdoc, hitchrunpy, hitchstory, prettystack
 jupyter-client==5.3.4     # via ipykernel, jupyter-console
 jupyter-console==6.1.0
 jupyter-core==4.6.1       # via jupyter-client
+kaching==0.4.2            # via hitchpylibrarytoolkit
 keyring==21.1.0           # via twine
 markupsafe==1.1.1         # via jinja2
 mccabe==0.6.1             # via flake8
@@ -71,6 +75,7 @@ ruamel.yaml==0.16.7       # via strictyaml
 secretstorage==3.1.2      # via keyring
 simex==0.3.5
 six==1.14.0               # via bleach, cryptography, pip-tools, python-dateutil, readme-renderer, traitlets
+smmap2==2.0.5             # via gitdb2
 strictyaml==1.0.6
 templex==0.2.0
 text-unidecode==1.3       # via python-slugify

hitch/key.py

@@ -20,6 +20,7 @@
 import dirtemplate
 import signal
 
+PROJECT_NAME = "seleniumdirector"
 
 def project_build(paths, python_version, selenium_version=None):
     pylibrary = (
@@ -425,3 +426,14 @@ def rerun(version="3.7.0"):
     Command(DIR.gen.joinpath("py{0}".format(version), "bin", "python"))(
         DIR.gen.joinpath("state", "working", "examplepythoncode.py")
     ).in_dir(DIR.gen.joinpath("state", "working")).run()
+
+
+@expected(dirtemplate.exceptions.DirTemplateException)
+def readmegen():
+    """
+    Build README.md and CHANGELOG.md.
+    """
+    import hitchpylibrarytoolkit
+    hitchpylibrarytoolkit.readmegen(
+        _storybook({}), DIR.project, DIR.key / "story", DIR.gen, PROJECT_NAME
+    )