v2.2 LTS
Masonite Essentials
Selenium Testing

Selenium tests are browser tests. With normal unit testing you are usually testing sections of your code like JSON endpoints or seeing a header on a page.
With Selenium testing, you are able to test more advanced features that may require JS handling like what happens when a user clicks a button or submits or a form.
With selenium testing, you will build a bunch of actions for your tests and a browser will open and actually go step by step according to your instructions.
This package comes shipped with all the required selenium drivers so there is no need for any external selenium server installations.

First we will need to install the package:
$ pip install masonite-selenium

This package extends the current testing framework so you will add the TestCase to your current unit tests.
Let's build a new TestCase and test the homepage that shows when Masonite is first installed:
$ craft test HomePage
This will generate a new test that looks like this:
from masonite.testing import TestCase
class TestHomePage(TestCase):
"""All tests by default will run inside of a database transaction."""
transactions = True
def setUp(self):
"""Anytime you override the setUp method you must call the setUp method
on the parent class like below.
"""
super().setUp()
def setUpFactories(self):
"""This runs when the test class first starts up.
This does not run before every test case. Use this method to
set your database up.
"""
pass

In order to build the selenium test we need to import the class and add it to our TestCase.
from masonite.testing import TestCase
from masonite.testing.selenium import SeleniumTestCase
class TestHomePage(TestCase, SeleniumTestCase):
"""All tests by default will run inside of a database transaction."""
transactions = True
def setUp(self):
"""Anytime you override the setUp method you must call the setUp method
on the parent class like below.
"""
super().setUp()
We now have all methods available to us to start building our selenium tests.

First before we build our TestCase, we need to specify which browser we want. The current 2 options are: chrome and firefox.
You can specify which browser to use using the useBrowser() method inside the setUp() method.
from masonite.testing import TestCase
from masonite.testing.selenium import SeleniumTestCase
class TestHomePage(TestCase, SeleniumTestCase):
"""All tests by default will run inside of a database transaction."""
transactions = True
def setUp(self):
"""Anytime you override the setUp method you must call the setUp method
on the parent class like below.
"""
super().setUp()
self.useBrowser('chrome', version='74')
# self.useBrowser('firefox')
If you are using the chrome driver you can optionally specify which version to run.

You can optionally specify if you want to run your browsers in a headless state. This means that the browser will not actually open to run tests but will run in the background. This will not effect your tests but is just a preference and usually your tests will run faster.
self.useBrowser('chrome', version='74', headless=True)

Here is a basic example on building a test for the installed homepage:
def test_can_see_homepage(self):
(self.visit('/')
.assertSee('Masonite 2.2'))
we can then run the test by running:
$ python -m pytest

You can chain all methods together to build up and mock user actions. An example test might look like this:
def test_can_login_to_pypi(self):
(self.visit('https://pypi.org/')
.clickLink('Log in')
.assertSee('Log in to PyPI')
.text('#username', 'josephmancuso')
.text('#password', 'secret')
.submit().assertCantSee('Your projects'))

When finding a selector you can use a few symbols to help navigate the page
Take this form for example:
<form action="/submit">
<input id="username" type="text" name="username">
<input id="password" type="password" name="password">
<button type="submit">Submit</button>
</form>

You can select an ID by using the # symbol:
(self.visit('/form')
.text('#username', 'user')
.text('#password', 'secret')
.submit())

You can select by the name by simply passing in the name value. This will default to the name attribute:
(self.visit('/form')
.text('#username', 'user')
.text('#password', 'secret')
.submit())

(self.visit('/form')
.text('.username', 'user')
.text('.password', 'secret')
.submit())

The issue with selecting by a normal selector like an ID or a name is that these could change. This is why you are able to select with a unique attribute name.
You may change your form a bit to do something like this instead:
<form action="/submit">
<input selenium="username" type="text" name="username">
<input selenium="password" type="password" name="password">
<button type="submit">Submit</button>
</form>
You can then tell Masonite what the name of your unique attribute is:
from masonite.testing import TestCase
from masonite.testing.selenium import SeleniumTestCase
class TestHomePage(TestCase, SeleniumTestCase):
"""All tests by default will run inside of a database transaction."""
transactions = True
unique_attribute = 'selenium'
def setUp(self):
"""Anytime you override the setUp method you must call the setUp method
on the parent class like below.
"""
super().setUp()
self.useBrowser('chrome', version='74')
# self.useBrowser('firefox')
and finally you can select by that attribute using the @ symbol:
(self.visit('/form')
.text('@username', 'user')
.text('@password', 'secret')
.submit())

Below are the available methods you can use to build your tests.

This method will navigate to a URL
self.visit('/')
If the URL does not start with http then Masonite will prepend the APP_URL environment variable to the front. If this is running inside your Masonite application, you can change this value in your .env file.

This method will assert that the title is a specific value
(self.visit('https://www.python.org/')
.assertTitleIs('Welcome'))

Opposite of assertTitleIs.

This method will assert that the current URL is a specific value
(self.visit('https://www.python.org/')
.assertUrlIs('https://www.python.org/'))

Asserts that something is available on the page that the user can see
(self.visit('https://www.python.org/')
.assertSee('Python'))

Just an alias for assertSee.

Opposite of assertCanSee. Used to assert that text is not on the page.

Types text into a text box.
(self.visit('https://www.python.org/')
.text('#username', 'user123')
.text('#password', 'pass123'))

You can choose an option in a select box by its value:
(self.visit('https://www.python.org/')
.selectBox('#fruit', 'apple'))

This will check a checkbox
(self.visit('https://www.python.org/')
.check('#checkbox'))

Resizes the window based on a width and heigh parameter
(self.visit('https://www.python.org/')
.resize(800, 600)) # width, height

Maximizes the window
(self.visit('https://www.python.org/')
.maximize())

Minimizes the window
(self.visit('https://www.python.org/')
.minimize())

Refreshes the window
(self.visit('https://www.python.org/')
.refresh())

Navigates backwards
(self.visit('https://www.python.org/')
.back())

Navigates forwards
(self.visit('https://www.python.org/')
.forward())
Clicks a link on a page
(self.visit('https://www.python.org/')
.link('#login'))
Alias for link.

Submits the current form the last entered element is in
(self.visit('https://www.python.org/')
.text('#username', 'user123')
.text('#password', 'pass123')
.submit())
You can also submit another form by entering a selector
(self.visit('https://www.python.org/')
.text('#username', 'user123')
.text('#password', 'pass123')
.submit('#another-form'))

Clicks an element
(self.visit('https://www.python.org/')
.click('#button'))

Closes the browser
(self.visit('https://www.python.org/')
.close())
Export as PDF
Copy link
On this page
Introduction
Getting Started
Installation
Creating The TestCase
Building The TestCase
Using a Browser
Headless
Building The Test
Method Chaining
Selectors
Selecting by ID
Selecting by Name
Selecting by Class
Selecting by a Unique Attribute
Available Methods
visit
assertTitleIs
assertTitleIsNot
assertUrlIs
assertSee
assertCanSee
assertCantSee
text
selectBox
check
resize
mazimize
minimize
refresh
back
forward
link
clickLink
submit
click
close