Webdriver-test-tools

ModalObject`s now support YAML representation of the modal to simplify the page object writing process.

Creating a new modal object using the `new page --prototype modal` command now creates a .yml file in addition to a Python module. Locators for the modal container and close button are declared in the file.

For documentation on form object YAML syntax, see:
https://connordelacruz.com/webdriver-test-tools/yaml.html

Details

* Added `YAML_FILE` attribute and `parse_yaml()` method to `ModalObject`
* Added `modal_object.yml.j2` template and updated `modal_object.py.j2` to use `YAML_FILE`
* Updated `new_file` to include `.yml` template for modals
* Documented modal YAML syntax in `yaml.rst`

FormObject`s now support YAML representation of the form and inputs to simplify the page object writing process.

Creating a new form object using the `new page --prototype form` command now creates a `.yml` file in addition to a Python module. Locators for the form and submit button are declared in the file, as well as representations of the inputs in that form including their name, type, and various other attributes.

For documentation on form object YAML syntax, see:
https://connordelacruz.com/webdriver-test-tools/yaml.html

Details

`pageobject.utils.yaml`:

* New module `pageobject.utils.yaml`, which contains methods and exceptions related to parsing YAML files

`pageobject.form`:

* Added `InputObject` class, which represents input elements and handles filling them/retrieving the current values

`FormObject`:

* Added `YAML_FILE` attribute, which is a path to the `.yml` file that should be parsed on `__init()`
* Added `inputs` attribute, which is a dictionary mapping input names to the corresponding `InputObject` instance. Gets populated at runtime after parsing `YAML_FILE`
* Added `parse_yaml()` method, which gets called in `__init__()` if `YAML_FILE` is set and sets `FORM_LOCATOR`, `SUBMIT_LOCATOR`, and `inputs` based on the parsed YAML
* Deprecated `fill_form()` method and `Input` nested class workflow
* Added `fill_inputs()`, which takes an `input_map` similar to the deprecated `fill_form()` and calls the `set_value()` method of the corresponding `InputObject`s
* Added `get_input_values()`, which returns a list mapping input names to their currently set values


`project.templates.templates.page_object`:

* Added `form_object.yml.j2` template
* Updated `form_object.py.j2` template. Added `YAML_FILE` and removed `Input` nested class and `FORM_LOCATOR` and `SUBMIT_LOCATOR` declarations


`project.cmd.new`:

* `module_name` argument is now validated with new method `validate_module_name`, which is essentially the same as `validate_module_filename` but doesn't add '.py' to the return value


`project.new_file`:

* Added support for page object prototypes that render more than 1 template (i.e. for the `.yml` file)
* `new_file()` now returns a list of paths for files created (instead of just one)


`webdriver.actions.form`:

* Added `toggle_checkbox()` helper, which clicks on the specified checkbox element, attempting to handle the case where the checkbox is hidden for styling purposes
* Various fixes, adjustments
* A lot of TODO comments about deprecating old input setter/getter methods in favor of the new `InputObject`


Additional Comments

Currently, `FormObject` is the only page object class that supports YAML representation. Support for other prototype classes will be added in future updates.

Additionally, the old method of filling forms using `fill_form()` is deprecated, and will be replaced with the new `fill_inputs()` workflow.

A page object prototype can be specified when running the `new page` command using the `--prototype` argument (or in a prompt when not enough arguments are provided). The generated page object will subclass the corresponding prototype class and include any variable declarations used by that prototype's methods.


Details

New Command

`webdriver_test_tools.project.cmd.new`

- Added `--prototype` argument to the `new page` subparser
- `main()` now takes the parsed arguments object instead of individual keyword arguments for each one, allowing for the `page` and `test` subparsers to have additional arguments specific to each that get handled along with common args

`webdriver_test_tools.project.templates.templates`

- Added `page_object/` subdirectory
- Deleted old page object template and added `page_object/base_page.py.j2`. This template contains additional blocks, allowing for prototype templates to extend it
- Added templates for each prototype to `page_object/`. Each template extends `page_object/base_page.py.j2` and adds any imports, attributes, and nested class declarations specific to the prototype class

`webdriver_test_tools.project.new_file`

- Added "constants" for prototype names (used with the `--prototype` argument), as well as `PAGE_OBJECT_TEMPLATE_MAP` which maps each to their corresponding template file name
- `new_file()` now accepts additional `**kwargs` for any type-specific arguments. Currently the only one that is handled is `prototype`, which corresponds with the keys in `PAGE_OBJECT_TEMPLATE_MAP`

Prototype Updates

- `NavObject.fixed` was changed to `NavObject.FIXED` for consistency. Any sublcasses of `NavObject` or `CollapsibleNavObject` that set `fixed = False` will need to be updated to `FIXED = False`
- Added `PAGE_URL` attribute to `WebPageObject`, which should be set to the full URL to the page

Fixes

- `FormObject.SUBMIT_SUCCESS_CLASS` and `ModalObject.MODAL_BODY_CLASS` were considered optional, but not setting them to a class was causing `TypeError`s to be thrown when methods checked if their values were subclasses of `BasePage`. Affected methods now first check if their values are classes before calling `issubclass()`

Misc. Templating Changes

- `webdriver_test_tools.common.files.render_template()` now uses sets the `trim_blocks` and `lstrip_blocks` options to `True` in the jinja2 environment, which cleans up leading whitespace before template blocks and new lines after them
- Bumped minimum required version of `Jinja2` package to 2.10

Added optional parameter `ignore_trailing_slash` to `WebDriverTestCase.assertBaseUrlChange()` (and the associated method and class in `webdriver_test_tools.webdriver.support`). If set to `True` (the default), any trailing '/' in the expected URL or the current base URL will be stripped before comparing the two, e.g. `http://example.com` and `http://example.com/` would be treated as identical.


Details

`testcase` submodule

`WebDriverTestCase`:

- Added optional parameter `ignore_trailing_slash` to `assertBaseUrlChange()` (Default = `True`)


`webdriver.support.test` submodule

- Added optional parameter `ignore_trailing_slash` to `base_url_change_test()` (Default = `True`)


`webdriver.support.expected_conditions` submodule

`base_url_to_be` expected condition:

- Added `ignore_trailing_slash` parameter to `__init__()`. If set to `True` (the default), trailing '/' characters will be stripped from the expected URL and current base URL before comparing

Cleaned up and re-organized the templates for config files generated with `wtt init`.

Additionally, the default `config/browserstack.py` that gets generated now grabs the username and access key from environment variables `BROWSERSTACK_USERNAME` and `BROWSERSTACK_ACCESS_KEY`, respectively. This is to discourage storing credentials as string literals, and also makes it easier to re-use credentials between test projects.

Overview

`--test` and `--skip` test project arguments now support wildcards (`*`) in class and method names.

Example

Suppose we have a test package called `example_package`, which includes the following 3 test case classes:

- `PrimaryNavTestCase`
- `SecondaryNavTestCase`
- `PrimaryNavMobileTestCase`

The following are some example use cases for wildcards:


Run all test cases with the word "Nav"
(e.g. PrimaryNavTestCase, SecondaryNavTestCase, PrimaryNavMobileTestCase)
python -m example_package --test *Nav*

Run all test cases with the word "Nav", but not the word "Secondary"
(e.g. PrimaryNavTestCase, PrimaryNavMobileTestCase)
python -m example_package --test *Nav* --skip *Secondary*

Run all methods ending in "_menu" in all test cases with the word "Nav"
(e.g. PrimaryNavTestCase.test_hover_menu, PrimaryNavMobileTestCase.test_mobile_menu)
python -m example_package --test *Nav*.*_menu

Run all methods ending in "_menu" in all test cases with the word "Nav",
but not if the class name contains the word "Mobile"
(e.g. PrimaryNavTestCase.test_hover_menu)
python -m example_package --test *Nav*.*_menu --skip *Mobile*



Details

All code changes were made to modules in `webdriver_test_tools.project`.

**test_loader:**

- `load_project_tests()` now takes `test_class_map` and `skip_class_map` instead of just lists of class names
- Re-worked the internal procedure for loading test modules and classes. First test modules are loaded, then all test cases in those modules, then those results are filtered based on `test_class_map` and `skip_class_map`
- Any wildcards found in test case or method names are expanded to the full names of matching classes/methods
- Added 2 new exception classes for wildcard-related methods (`TestMethodsNotFoundException` and `TestCasesNotFoundException`)
- `load_browser_tests()` now takes the base test case class as an argument (used for method name wildcard expansion)

**test_factory:**

- Updated call to `test_loader.load_browser_tests()` to pass the base test case class as an argument

**cmd.common:**

- Updated call to `test_loader.load_project_tests()` to just pass `test_class_map` and `skip_class_map` instead of lists of class names
- Moved `get_skip_class_names()` to `test_loader`
- Added a try/except statement in `load_tests()` to print the error message and exit in the event of a `test_loader.TestCasesNotFoundException`