Package: webdriver-test-tools
WebDriver Test ToolsA front-end testing framework usingSelenium WebDriverand Python.ContentsWebDriver Test ToolsOverviewSet UpCommand Line UsageContributingTest Project OverviewSetupBasic Command Line UsageProject StructureOverviewWebDriver Test Tools provides a framework and utilities for writing front-end
functional tests.FeaturesFramework for writing cross-browser front-end test suitesPre-defined test functions for commonly used test proceduresUtilities and extended functionality for the Selenium WebDriver packageImplementation of thePage Object Modelwith pre-defined page objects for
common elements (navbars, forms, etc)Command line tool for quickly generating files and directories for new test
projectsMobile device layout emulation for responsive testsHeadless browser testingSupport for running tests onBrowserStackThis project uses Selenium WebDriver for automated browser actions and the
python unittest library for the test framework, documentation for which can be
found below:Selenium with PythonPython unit testing frameworkDocumentationFull documentation for WebDriver Test Tools:WebDriver Test Tools Docs: Framework documentationwebdriver_test_tools Package API: Python package APISet UpPrerequisitesPythonPython 3.4+pip (included by default with Python 3.4+)DriversIn order to use Selenium, drivers will need to be installed for any browser
tests will be run on. Below are currently supported drivers, their default
enabled/disabled status, and their supported features:DriverEnabled by DefaultHeadless BrowsingMobile LayoutGoogle Chrome✓✓✓Firefox✓✓SafariEdgeInternet ExplorerCross-platform browsers are enabled by default, while platform-specific browsers
are disabled by default. You can enable or disable drivers in<test_package>/config/browser.pyby setting the corresponding value inBrowserConfig.ENABLED_BROWSERStoTrueorFalse, respectively.The following documentation goes into detail on configuring browsers for
testing:Testing with Additional Browsers: Enabling/disabling browsers, per-test
skipping for certain browsers, emulating mobile browsers, and headless
browser testingBrowserStack Support: Enabling and configuring testing on BrowserStackInstallationThe package can be installed using pip:pip install webdriver-test-toolsNote:Command may bepip3instead ofpipdepending on the system.Creating a Test SuiteThe package itself does not contain test cases. To generate files for a new test
suite, change into the desired directory and run:wtt initThis will generate a new test package with template files and project
directories.The following documentation goes into detail on test projects:Test Projects: Test project setup, configuration, command line usage,
and directory structureExample Test Project: Step-by-step tutorial with a simple example test
projectCommand Line UsageTo initialize a new test project in the current directory:wtt init [<package_name>] [<"Project Title">] [--no-gitignore] [--no-readme]Where:<package_name>: Name for the new test package. (alphanumeric characters
and underscores only. Cannot start with a number)<"Project Title">: (Optional) Friendly name for the test project. Defaults
to the value of <package_name> if not provided--no-gitignore: Do not create .gitignore files for project root and log
directory--no-readme: Do not generate README file with usage infoIf no arguments are provided, a prompt will walk you through project
initialization.For info on command line arguments:wtt --helpTo print the version number:wtt --versionNote:wttandwebdriver_test_toolscan be used interchangeably.ContributingPlease read thecontributing guidelinesfor details on reporting bugs,
requesting features, and making contributions to the project.Test Project OverviewSetupInitializationTo generate files for a new test suite, change into the desired directory and
run:wtt initThis will generate a new test package with template files and project
directories.(Optional) Setup Virtual EnvironmentIf usingvirtualenv, initialize the
virtual environment before installing the test package:virtualenv venv
source ./venv/bin/activateTest Package InstallationAfter initializing the test project, run the following command from the project
root directory:pip install -e .Installing with the-eflag will update the package automatically when
changes are made to the source code.ConfigurationAfter initializing a project, the URL of the site to be tested will need to be
configured. In<test_package>/config/site.py, set theSITE_URLandBASE_URLof theSiteConfigclass. You can add any other URLs you’ll need
as class variables as well.Basic Command Line UsageUsage:<test_package> [-h] <command>If no<command>is specified, theruncommand will be executed by
default.Note:If the test package was not installed withpip, run test packages
commands usingpython-m<test_package> <command>.For info on command line arguments, use the--help(or-h) argument:<test_package> --helpCreating New Project FilesNew tests and page objects can be generated using thenewcommand:<test_package> new [<type>] [<module_name>] [<ClassName>] [-d <description>] [-f]Where:<type>: The type of file to create (testorpage)<module_name>: Filename to use for the new python module<ClassName>: Name to use for the initial class<description>: (Optional) Description for the initial class-f: (Optional) Force overwrite if a file with the same name already existsIf no arguments are provided, a prompt will walk you through generating the new
file. Alternatively, you can skip the prompts by using the arguments shown in
the following sections.Creating New TestsNew test modules can be generated using thenew testcommand:<test_package> new test <module_name> <TestCaseClass>Where<module_name>is the filename for the new test and<TestCaseClass>is the class name for the test case.The--description(or-d) argument can be used to add a description for
the initial test case class:<test_package> new test <module_name> <TestCaseClass> -d "Test case description"If a test module with the same<module_name>already exists,new testwill not overwrite it by default. The--force(or-f) argument can be
used to force overwrite existing files:<test_package> new test <module_name> <TestCaseClass> --forceCreating New Page ObjectsNew page object modules can be generated using thenew pagecommand:<test_package> new page <module_name> <PageObjectClass>Where<module_name>is the filename for the new module and<PageObjectClass>is the class name for the page object.The--description(or-d) argument can be used to add a description for
the initial page object class:<test_package> new page <module_name> <PageObjectClass> -d "Page object description"By default, the new class will be a genericBasePagesubclass. The--prototype(or-p) argument can be used to specify apage object
prototypeclass to use as a parent class for the new page object:<test_package> new page <module_name> <PageObjectClass> -p <prototype>For a list of valid<prototype>options, run<test_package> new page--help.Page object prototypes support YAML file parsing to simplify the syntax of
representing elements. Whether YAML files or Python-only files are generated by
default is configured in<test_package>/config/projectfiles.pyby setting
theENABLE_PAGE_OBJECT_YAMLvariable of theProjectFilesConfigclass.The default setting can be overridden by using command line arguments. IfENABLE_PAGE_OBJECT_YAMLisTrue, the--no-yaml(or-Y) argument
can be used to only generate.pyfiles:<test_package> new page <args> --no-yamlIfENABLE_PAGE_OBJECT_YAMLisFalse, the--yaml(or-y) argument
can be used to generate.pyand.ymlfiles for supported prototypes:<test_package> new page <args> --yamlIf a page module with the same<module_name>already exists,new pagewill not overwrite it by default. The--force(or-f) argument can be
used to force overwrite existing files:<test_package> new page <module_name> <PageObjectClass> --forceRunning TestsBasic UsageTo run all tests:<test_package>Running Specific TestsTo run all test cases in one or more modules, use the--module(or-m)
argument:<test_package> --module <test_module> [<test_module> ...]To skip all test cases in one or more modules, use the--skip-module(or-S) argument:<test_package> --skip-module <test_module> [<test_module> ...]To run specific test case classes or methods, use the--test(or-t)
argument:<test_package> --test <TestClass>[.<test_method>] [<TestClass>[.<test_method>] ...]To skip certain test cases or methods, use the--skip(or-s) argument:<test_package> --skip <TestClass>[.<test_method>] [<TestClass>[.<test_method>] ...]The--testand--skiparguments both support wildcards (*) in class
and method names.These arguments can be used together. When combined, they are processed in the
following order:--skip-moduleremoves the specified modules from the set of tests--modulereduces the set of tests to those in the specified modules--testreduces the set of tests to the specified classes and methods--skipremoves the specified classes and methods from the set of testsUsing Specific BrowsersTo do any of the above in specific browsers rather than running in all available
browsers, use the--browser(or-b) argument:<test_package> <args> --browser <browser> [<browser ...]For a list of options you can specify with--browser, run<test_package>--help.Using Headless BrowsersBy default, tests run using the browser’s GUI. While it can be helpful to see
what’s going on during test execution, loading and rendering the browser window
can be resource-intensive and slows down performance during test execution.To improve performance, tests can be run inheadless browsersusing the--headless(or-H) argument:<test_package> <args> --headlessNote:When using the--headlessargument, tests will only be run with
the following web drivers that support running in a headless environment:ChromeFirefoxUsing BrowserStackTest projects can be configured to run tests onBrowserStack. Once
BrowserStack support is enabled, tests can be run on BrowserStack using the--browserstack(or-B) argument:<test_package> <args> --browserstackSee the documentation onBrowserStack Supportfor more details and setup
instructions.Configuring OutputBy default, detailed output is displayed when running tests. To reduce or
suppress output, use the--verbosity(or-v) argument:<test_package> <args> --verbosity <level>Where<level>is one of the following:0 - Final results only1 - Final results and progress indicator2 - Full outputNote:The default output level can be changed in<test_package>/config/test.pyby setting theDEFAULT_VERBOSITYattribute of theTestSuiteConfigclass.List Available TestsBasic UsageTo print a list of available test classes and methods:<test_package> listTo include docstrings for each test class and method in output:<test_package> list --verboseListing Specific TestsTo only list test classes from specific modules:<test_package> list --module <test_module> [<test_module> ...]To omit specific modules:<test_package> list --skip-module <test_module> [<test_module> ...]To only list specific test classes:<test_package> list --test <TestClass> [<TestClass> ...]To skip certain test classes in output:<test_package> --skip <TestClass> [<TestClass> ...]SeeRunning Specific Testsfor more info on these arguments.Project Structurewtt initwill create the following files and directories
inside the project directory:<project-directory>/
├── README.rst
├── setup.py
└── <test_package>/
    ├── __main__.py
    ├── __init__.py
    ├── config/
    │   ├── __init__.py
    │   ├── browser.py
    │   ├── browserstack.py
    │   ├── projectfiles.py
    │   ├── site.py
    │   ├── test.py
    │   └── webdriver.py
    ├── data.py
    ├── log/
    ├── pages/
    │   └── __init__.py
    ├── screenshot/
    └── tests/
        └── __init__.pyThis test structure is designed to be used with thePage Object Model. Interaction with the page
should be handled by page objects to minimize the need to alter tests whenever
the HTML is changed.Test Project Root Contentssetup.py: Python package setup file that allows the new test suite to be
installed as a pip package.Test Package Root Contents__main__.py: Required to run tests from the command line.__init__.py: Empty init file so Python recognizes the directory as a
package.data.py: Module for storing static data for tests that must use specific
values (e.g. emails, usernames, etc).Test Package Directoriesconfig/Configurations used by test scripts for site URLs, web driver options, and the
python unittest framework.browser.py: Configure which browsers to run tests in.browserstack.py: Enable and configure testing withBrowserStack.projectfiles.py: Configure defaults for generating project files with thenewcommand.site.py: Configure URLs used for testing.test.py: Configure theunittest.TestRunnerclass.webdriver.py: Configure WebDrivers and log output directory.log/Default output directory for WebDriver logs. This can be changed inconfig/webdriver.py.pages/Page object classes for pages and components. These classes should handle
locating and interacting with elements on the page. SeeCreating New Page
Objectsfor info on generating new page object modules.screenshot/Default output directory for screenshots taken during test execution. This can
be changed inconfig/webdriver.py.tests/Test case modules. These use page objects to interact with elements and assert
that the expected behavior occurs. SeeCreating New Testsfor info on
generating new test modules.